Define and maintain complex project configuration through code.
JOIN THE #TemplatesAreEvil MOVEMENT!
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.
Check out this talk about projen.
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.
To create a new project, run the following command and follow the instructions:
$ mkdir my-project
$ cd my-project
$ git init
$ npx projen new PROJECT-TYPE
π€ Synthesizing project...
...
Currently supported project types (use npx projen new
without a type for a
list):
- awscdk-app-ts - AWS CDK app in TypeScript.
- awscdk-construct - AWS CDK construct library project.
- 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 without TypeScript.
- nextjs-ts - Next.js project with TypeScript.
- node - Node.js project.
- project - Base project.
- python - Python project.
- react - React project without TypeScript.
- react-ts - React project with TypeScript.
- typescript - TypeScript project.
- typescript-app - TypeScript app.
Use
npx 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:npx 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: "[email protected]",
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 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 jsii
projects, you can use
python option
:
const project = new JsiiProject({
// ...
python: {
distName: "mydist",
module: "my_module",
}
});
Run:
npx projen
And you'll notice that your package.json
file now contains a python
section in
it's 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='npx projen'
Most projects support a start
command which displays a menu of workflow
activities:
$ yarn start
? Scripts: (Use arrow keys)
BUILD
β― compile Only compile
watch Watch & compile in the background
build Full release build (test+compile)
TEST
test Run tests
test:watch Run jest in watch mode
eslint Runs eslint against the codebase
...
The build
command is the same command that's executed in your CI builds. It
typically compiles, lints, tests and packages your module for distribution.
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
Some examples for 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
- 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
See API Reference for API details.
In addition, several projen components and project types are explained with examples in /docs (currently a work in progress!).
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 it's derivatives). Projen automatically discovers project types so your
type will immediately be available in projen new
.
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:
$ 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 like
[email protected]
, file:/path/to/local/folder
,
[email protected]/awesome/projen-vuejs#1.2.3
, etc.
$ npx 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();
See Vision.
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 [email protected]:projen/projen
$ cd projen
$ yarn
$ yarn watch # compile in the background
Thanks goes to these wonderful people (emoji key):
Distributed under the Apache-2.0 license.