projen

Define and maintain complex project configuration through code.

Documentation · Changelog · Project types · Join the community

projen synthesizes project configuration files such as package.json, tsconfig.json, .gitignore, GitHub Workflows, eslint, jest, etc. from a well-typed definition written in JavaScript.

As opposed to existing templating/scaffolding tools, projen is not a one-off generator. Synthesized files should never be manually edited (in fact, projen enforces that). To modify your project setup, users interact with rich strongly-typed class and execute projen to update their project configuration files.

By defining a custom project type and using projen in multiple repositories, it's possible to update configuration files and CI/CD workflows across dozens (or hundreds!?) of projects.

Check out this talk about projen from its creator.

Getting Started

projen doesn't need to be installed. You will be using pnpm dlx to run projen which takes care of all required setup steps. (npx works too, but pnpm dlx avoids the supply-chain risk of phantom dependency resolution in npm.)

To create a new project, run the following command and follow the instructions:

$ mkdir my-project
$ cd my-project
$ pnpm dlx projen new PROJECT-TYPE
🤖 Synthesizing project...
...

Project types

Currently supported project types (use pnpm dlx projen new without a type for a full list):

Built-in: (run pnpm dlx projen new <type>)

awscdk-app-java - AWS CDK app in Java.
awscdk-app-py - AWS CDK app in Python.
awscdk-app-ts - AWS CDK app in TypeScript.
awscdk-construct - AWS CDK construct library project.
cdk8s-app-py - CDK8s app in Python.
cdk8s-app-ts - CDK8s app in TypeScript.
cdk8s-construct - CDK8s construct library project.
cdktn-app-ts - CDKTN app in TypeScript.
cdktn-construct - CDKTN construct library project.
java - Java project.
jsii - Multi-language jsii library project.
nextjs - Next.js project using JavaScript.
nextjs-ts - Next.js project using TypeScript.
node - Node.js project.
project - Base project.
python - Python project.
react - React project using JavaScript.
react-ts - React project using TypeScript.
typescript - TypeScript project.
typescript-app - TypeScript app.

External: (run pnpm dlx projen new --from <type>)

projen-github-action-typescript - GitHub Action in TypeScript project.

Use pnpm dlx projen new PROJECT-TYPE --help to view a list of command line switches that allows you to specify most project options during bootstrapping. For example: pnpm dlx projen new jsii --author-name "Jerry Berry".

The new command will create a .projenrc.js file which looks like this for jsii projects:

const { JsiiProject } = require('projen');

const project = new JsiiProject({
  authorAddress: "elad.benisrael@gmail.com",
  authorName: "Elad Ben-Israel",
  name: "foobar",
  repository: "https://github.com/eladn/foobar.git",
});

project.synth();

This program instantiates the project type with minimal setup, and then calls synth() to synthesize the project files. By default, the new command will also execute this program, which will result in a fully working project.

Once your project is created, you can configure your project by editing .projenrc.js and re-running pnpm dlx projen to synthesize again.

The files generated by projen are considered an "implementation detail" and projen protects them from being manually edited (most files are marked read-only, and an "anti tamper" check is configured in the CI build workflow to ensure that files are not updated during build).

For example, to setup PyPI publishing in jsii projects, you can use publishToPypi option:

const project = new JsiiProject({
  // ...
  publishToPypi: {
    distName: "mydist",
    module: "my_module",
  }
});

Run:

pnpm dlx projen

And you'll notice that your package.json file now contains a python section in its jsii config and the GitHub release.yml workflow includes a PyPI publishing step.

We recommend to put this in your shell profile, so you can simply run pj every time you update .projenrc.js:

alias pj='pnpm dlx projen'

Most projects come with an assortment of tasks that handle various development activities, from compiling to publishing. Tasks can be and composed together, and can be run as local commands or turned into GitHub workflows. You can list all tasks with pnpm dlx projen --help:

$ pnpm dlx projen --help
projen [command]

Commands:
  projen new [PROJECT-TYPE-NAME] [OPTIONS]  Creates a new projen project
  projen clobber                            hard resets to HEAD of origin and cleans the local repo
  projen compile                            Only compile
  projen test                               Run tests
  projen build                              Full release build (test+compile)
  projen upgrade                            upgrade dependencies (including projen)
...

The build task is the same task that's executed in your CI builds. It typically compiles, lints, tests and packages your module for distribution.

Shell Completions

If installed as a global package, projen includes rich shell tab-completion support. To enable this in your shell, run:

# Bash
projen completion >> ~/.bashrc

# ZSH
projen completion >> ~/.zshrc

Features

Some examples of features built-in to project types:

Fully synthesize package.json
Standard npm scripts like compile, build, test, package
eslint
Jest
jsii: compile, package, api compatibility checks, API.md
Bump & release scripts with CHANGELOG generation based on conventional commits
Automated PR builds
Automated releases to npm, maven, NuGet and PyPI
Automated dependency upgrades
Mergify configuration
LICENSE file generation
gitignore + npmignore management
Node "engines" support with coupling to CI build environment and @types/node
Anti-tamper: CI builds will fail if a synthesized file is modified manually

Documentation

For documentation including examples and a full API reference, visit https://projen.io/.

Ecosystem

projen takes a "batteries included" approach and aims to offer dozens of different project types out of the box (we are just getting started). Think projen new react, projen new angular, projen new java-maven, projen new awscdk-typescript, projen new cdk8s-python (nothing in projen is tied to javascript or npm!)...

Adding new project types is as simple as submitting a pull request to this repo and exporting a class that extends projen.Project (or one of its derivatives). Projen automatically discovers project types so your type will immediately be available in projen new.

Projects in external modules

projen is bundled with many project types out of the box, but it can also work with project types and components defined in external jsii modules (the reason we need jsii is because projen uses the jsii metadata to discover project types & options in projen new).

Say we have a module in npm called projen-vuejs which includes a single project type for vue.js:

$ pnpm dlx projen new --from projen-vuejs

If the referenced module includes multiple project types, the type is required. Switches can also be used to specify initial values based on the project type APIs. You can also use any package syntax supported by pnpm add like projen-vuejs@1.2.3, file:/path/to/local/folder, git@github.com/awesome/projen-vuejs#1.2.3, etc.

$ pnpm dlx projen new --from projen-vuejs@^2 vuejs-ts --description "my awesome vue project"

Under the hood, projen new will install the projen-vuejs module from npm (version 2.0.0 and above), discover the project types in it and bootstrap the vuejs-ts project type. It will assign the value "my awesome vue project" to the description field. If you examine your .projenrc.js file, you'll see that projen-vuejs is defined as a dev dependency:

const { VueJsProject } = require('projen-vuejs');

const project = new VueJsProject({
  name: 'my-vuejs-sample',
  description: "my awesome vue project",
  // ...
  devDeps: [
    'projen-vuejs'
  ]
});

project.synth();

Roadmap

See Vision.

FAQ

Do I have to write my configuration in JavaScript?

Not at all! JavaScript is the default, but it's also possible to write it in Java, Python, TypeScript, or even JSON. This is made possible by the jsii library which allows us to write APIs once and generate libraries in several languages. You can choose a different language by passing the --projenrc-ts, --projenrc-py, --projenrc-java, or --projenrc-json flags when running projen new.

Note: using a .projenrc.json file to specify configuration only allows accessing a subset of the entire API - the options which are passed to the constructor of each project type.

How does projen work with my IDE?

projen has an unofficial VS Code extension. Check it out!

Community

The projen community can be found within the #projen channel in the cdk.dev community Slack workspace.

Security

projen follows a shared responsibility model: projen is responsible for generating secure default configuration through its built-in project types; you are responsible for the code you write in your projenrc file, the third-party project types and components you use, and the environment projen runs in.

projen is designed to run in a trusted environment with trusted inputs. Your projenrc file is a program executed with your user's permissions, and projen tasks execute shell commands defined in .projen/tasks.json. This file is prescriptive by design: the projen CLI executes what it contains, so anyone with write access to it (or to your repository in general) can change what projen runs. This is expected behavior — equivalent to write access to a Makefile or package.json scripts. The same trust model applies as with any other build tool. Since all synthesized files are derived from your projenrc program and checked in, source control always lets you review or restore what projen will run.

See the security documentation for details, and report security issues via our security policy rather than public GitHub issues.

Contributions

Contributions of all kinds are welcome! Check out our contributor's guide and our code of conduct.

For a quick start, check out a development environment:

$ git clone git@github.com:projen/projen
$ cd projen
$ npm ci
$ npm run watch # compile in the background

Contributors

Thanks goes to our wonderful contributors!

License

Distributed under the Apache-2.0 license.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

projen-0.103.6.tar.gz (5.6 MB view details)

Uploaded Aug 28, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

projen-0.103.6-py3-none-any.whl (5.6 MB view details)

Uploaded Aug 28, 2026 Python 3

File details

Details for the file projen-0.103.6.tar.gz.

File metadata

Download URL: projen-0.103.6.tar.gz
Upload date: Aug 28, 2026
Size: 5.6 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.14.7

File hashes

Hashes for projen-0.103.6.tar.gz
Algorithm	Hash digest
SHA256	`be6a8aa5e6b34c70bf2f6f280f53d35d7fc513b69d2e852dd1c34ba6efe3c08d`
MD5	`28ad0053a32c81ad50645f6cd8d75caf`
BLAKE2b-256	`b4843e3681e7a46c197ba42ac5396165705ebcac07c3aea916ecaf6bbfe4894d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for projen-0.103.6.tar.gz:

Publisher: release.yml on projen/projen

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: projen-0.103.6.tar.gz
- Subject digest: be6a8aa5e6b34c70bf2f6f280f53d35d7fc513b69d2e852dd1c34ba6efe3c08d
- Sigstore transparency entry: 2624234594
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: projen/projen@12bcacc980448ca03b491f40da8ecd825ac27235
- Branch / Tag: refs/heads/main
- Owner: https://github.com/projen
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@12bcacc980448ca03b491f40da8ecd825ac27235
- Trigger Event: push