tessl/npm-projen
CDK for software projects - synthesizes configuration files from well-typed JavaScript/TypeScript definitions.
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-projen@0.95.0index.mddocs/
Projen
Projen is a comprehensive software project configuration management system that provides a Cloud Development Kit (CDK) approach to defining and maintaining complex project configurations through code. It synthesizes project configuration files such as package.json, tsconfig.json, .gitignore, GitHub Workflows, eslint, jest, and other essential project files from well-typed JavaScript/TypeScript definitions. Unlike traditional templating or scaffolding tools, projen is not a one-off generator but maintains ongoing project configuration management through code, enforcing that synthesized files should never be manually edited.
Package Information
- Package Name: projen
- Package Type: npm
- Language: TypeScript
- Installation:
npm install projen - Peer Dependencies:
constructs ^10.0.0
Core Imports
import { Project, Component, Task, Dependencies } from "projen";
import { TypeScriptProject, NodeProject, PythonProject, JavaProject } from "projen";For CommonJS:
const { Project, Component, Task, Dependencies } = require("projen");
const { TypeScriptProject, NodeProject, PythonProject, JavaProject } = require("projen");For submodules:
import { typescript, javascript, python, java, github, awscdk } from "projen";
import { TypeScriptProject } from "projen/lib/typescript";Basic Usage
import { TypeScriptProject } from "projen";
// Create a new TypeScript project
const project = new TypeScriptProject({
name: "my-awesome-project",
defaultReleaseBranch: "main",
author: "Jane Developer",
authorEmail: "jane@example.com",
repository: "https://github.com/user/my-awesome-project.git",
// TypeScript configuration
srcdir: "src",
testdir: "test",
libdir: "lib",
// Dependencies
deps: ["axios", "lodash"],
devDeps: ["@types/node", "@types/jest"],
// Testing
jest: true,
eslint: true,
prettier: true,
});
// Add custom tasks
project.addTask("custom-build", {
description: "Custom build process",
exec: "echo 'Running custom build'",
});
// Synthesize all project files
project.synth();Architecture
Projen is built around several key architectural concepts:
- Project Hierarchy: Base
Projectclass extended by language-specific projects likeTypeScriptProject,PythonProject, etc. - Component System: Everything is a
Componentthat can be added to projects - from file management to CI/CD workflows - Synthesis Process: Projects synthesize configuration files during the build process, maintaining consistency across updates
- Task System: Unified task execution across different project types with dependency management
- File Management: Abstract file system with support for JSON, YAML, text files, and generated code
- Construct Integration: Built on AWS CDK's construct model for composability and extensibility
Capabilities
Core Project Management
Foundation classes and utilities for creating and managing software projects of any type.
class Project extends Construct {
constructor(options: ProjectOptions);
readonly name: string;
readonly outdir: string;
readonly tasks: Tasks;
readonly deps: Dependencies;
addTask(name: string, props?: TaskOptions): Task;
synth(): void;
static of(construct: IConstruct): Project;
}
interface ProjectOptions {
name: string;
parent?: Project;
outdir?: string;
logging?: LoggerOptions;
projenrcJson?: boolean;
renovatebot?: boolean;
commitGenerated?: boolean;
}TypeScript Projects
Complete TypeScript project setup with compilation, testing, linting, and documentation generation.
class TypeScriptProject extends NodeProject {
constructor(options: TypeScriptProjectOptions);
readonly srcdir: string;
readonly libdir: string;
readonly testdir: string;
readonly tsconfig?: TypescriptConfig;
readonly tsconfigDev: TypescriptConfig;
readonly watchTask: Task;
}Node.js Projects
Node.js projects with package management, testing frameworks, and JavaScript tooling.
class NodeProject extends GitHubProject {
constructor(options: NodeProjectOptions);
readonly package: NodePackage;
readonly jest?: Jest;
readonly eslint?: Eslint;
readonly prettier?: Prettier;
readonly bundler?: Bundler;
}Python Projects
Python projects with packaging, virtual environments, and testing frameworks.
class PythonProject extends GitHubProject {
constructor(options: PythonProjectOptions);
readonly moduleName: string;
readonly pip?: Pip;
readonly poetry?: Poetry;
readonly venv?: Venv;
readonly pytest?: Pytest;
}Java Projects
Java projects with Maven build system and dependency management.
class JavaProject extends GitHubProject {
constructor(options: JavaProjectOptions);
readonly pom: Pom;
readonly junit?: Junit;
readonly packaging: MavenPackaging;
readonly compile: MavenCompile;
}Web Projects
React and Next.js projects with modern web development tooling.
class ReactProject extends NodeProject {
constructor(options: ReactProjectOptions);
}
class NextJsProject extends NodeProject {
constructor(options: NextJsProjectOptions);
}AWS CDK Projects
AWS CDK applications and construct libraries for cloud infrastructure.
class AwsCdkTypeScriptApp extends TypeScriptProject {
constructor(options: AwsCdkTypeScriptAppOptions);
}
class AwsCdkConstructLibrary extends ConstructLibrary {
constructor(options: AwsCdkConstructLibraryOptions);
}Task Management
Unified task system for build processes, testing, and custom workflows.
class Task {
constructor(name: string, props?: TaskOptions);
readonly name: string;
exec(command: string, options?: TaskStepOptions): void;
spawn(subtask: string, options?: TaskStepOptions): void;
lock(): void;
}
interface TaskOptions {
description?: string;
exec?: string;
steps?: TaskStep[];
env?: Record<string, string>;
cwd?: string;
condition?: string;
}Dependency Management
Cross-platform dependency management for different package managers.
class Dependencies extends Component {
constructor(project: Project);
addDependency(spec: string, type: DependencyType, metadata?: object): Dependency;
removeDependency(name: string, type?: DependencyType): void;
getDependency(name: string, type?: DependencyType): Dependency;
}
enum DependencyType {
RUNTIME = "runtime",
PEER = "peer",
BUNDLED = "bundled",
BUILD = "build",
TEST = "test",
DEVENV = "devenv",
OVERRIDE = "override",
OPTIONAL = "optional"
}File Management
Abstract file system for managing configuration files, source code, and generated content.
abstract class FileBase extends Component {
constructor(scope: IConstruct, filePath: string, options?: FileBaseOptions);
readonly path: string;
readonly absolutePath: string;
readonly readonly: boolean;
readonly executable: boolean;
}
class JsonFile extends ObjectFile {
constructor(scope: IConstruct, filePath: string, options?: JsonFileOptions);
}
class YamlFile extends ObjectFile {
constructor(scope: IConstruct, filePath: string, options?: YamlFileOptions);
}GitHub Integration
GitHub Actions workflows, issue templates, and repository management.
class GitHub extends Component {
constructor(project: GitHubProject, options?: GitHubOptions);
}
class GitHubProject extends Project {
constructor(options: GitHubProjectOptions);
readonly github?: GitHub;
}Types
Core Types
interface Component {
readonly node: Node;
readonly project: Project;
toString(): string;
}
interface Dependency {
name: string;
version?: string;
type: DependencyType;
metadata?: object;
}
interface TaskStep {
exec?: string;
spawn?: string;
builtin?: string;
env?: Record<string, string>;
cwd?: string;
condition?: string;
}
interface LoggerOptions {
level?: LogLevel;
usePrefix?: boolean;
}
enum LogLevel {
OFF = 0,
ERROR = 1,
WARN = 2,
INFO = 3,
DEBUG = 4,
VERBOSE = 5
}