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 --helpto 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.
2 maintainers
Release files for projen 0.103.23
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| projen-0.103.23.tar.gz | 5.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| projen-0.103.23-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 11.4 MB
Release files / projen-0.103.23.tar.gz
| Download URL | projen-0.103.23.tar.gz |
|---|---|
| Size | 5.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f29a5204fb3a67e5e27f827c03fa581f297e9bb7c28dcda25be012434dc5b1da
|
|
BLAKE2b-256 checksum How to use checksums |
a277bd58bcec8716701fcb42dafc613b19f6d9deb4b7dd7d380aa1b4e177fc48
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.14.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency logRelease files / projen-0.103.23-py3-none-any.whl
| Download URL | projen-0.103.23-py3-none-any.whl |
|---|---|
| Size | 5.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a793a6f941be5320aca0ade729653a02cf0a4b1b60f9c7ddf7ba7c5146c0a63
|
|
BLAKE2b-256 checksum How to use checksums |
6ff11f064ec119b7993a52967d7b5754f0f60586559439ceacc27867fcbed88f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.14.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.
Transparency log
