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.
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:
$ mkdir my-project
$ cd my-project
$ npx projen new PROJECT-TYPE
🤖 Synthesizing project...
...
Currently supported project types (use npx projen new without a type for a
full list):
Built-in: (run npx projen new <type>)
External: (run npx projen new --from <type>)
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.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 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
publishToPypi option:
const project = new JsiiProject({
// ...
publishToPypi: {
distName: "mydist",
module: "my_module",
}
});
Run:
npx 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='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 with npx projen --help:
$ 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 build task is the same task 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 of features built-in to project types:
package.jsoncompile, build, test, packageFor documentation including examples and a full API reference, visit https://projen.io/.
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.
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
projen-vuejs@1.2.3, file:/path/to/local/folder,
git@github.com/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.
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.
projen has an unofficial VS Code extension. Check it out!
The projen community can be found within the #projen channel in the cdk.dev community Slack workspace.
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
$ yarn
$ yarn watch # compile in the background
Thanks goes to these wonderful people (emoji key):
Distributed under the Apache-2.0 license.
FAQs
CDK for software projects
We found that projen demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.
