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 npx to run projen which takes care of all required setup steps.

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

``console $ mkdir my-project $ cd my-project $ npx projen new PROJECT-TYPE 🤖 Synthesizing project... ...`

`$3`

Currently supported project types (use npx projen newwithout a type for a full list):

Built-in: (run npx projen new )

* 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. * cdktf-construct - CDKTF 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 npx projen new --from )

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

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

The new command will create a .projenrc.jsfile which looks like this forjsii projects:

`js 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 callssynth() to synthesize the project files. By default, the newcommand 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 npx 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 jsiiprojects, you can usepublishToPypi option:

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

Run:

`shell npx projen`

And you'll notice that your package.json file now contains a pythonsection in itsjsii config and the GitHub release.ymlworkflow includes a PyPI publishing step.

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

`bash alias pj='npx 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 withnpx projen --help:

`shell $ npx 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 buildtask is the same task that's executed in your CI builds. It typically compiles, lints, tests and packages your module for distribution.

`$3`

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

`shell

`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 likecompile, 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 .

`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). Thinkprojen 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 extendsprojen.Project(or one of its derivatives). Projen automatically discovers project types so your type will immediately be available inprojen new.

`$3`

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-vuejswhich includes a single project type for vue.js:

`bash $ npx 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 yarn add likeprojen-vuejs@1.2.3, file:/path/to/local/folder,git@github.com/awesome/projen-vuejs#1.2.3, etc.

`bash $ npx projen new --from projen-vuejs@^2 vuejs-ts --description "my awesome vue project"`

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

`javascript 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`

`$3`

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.jsonfile to specify configuration only allows accessing a subset of the entire API - the options which are passed to the constructor of each project type.