projen
TypeScript icon, indicating that this package has built-in type declarations

0.80.2 • Public • Published

projen

Define and maintain complex project configuration through code.

Documentation · Changelog · Project types · Join the community

Apache 2.0 License Gitpod ready-to-code Release badge Commit activity


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:

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

Project types

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 --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: "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.

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:

$ 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();

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.

Virtual Meetup

  • Thursday June 30, 2022
  • 1-2pm America/New_York (EDT)
  • CFP a Google Form
  • CFP Closes Saturday April 30, 2022
  • Hosted on Zoom

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
$ yarn
$ yarn watch # compile in the background

Thanks goes to these wonderful people (emoji key):

All Contributors

 Aatman
Aatman

💻
Abdullah Sahin
Abdullah Sahin

💻
Adam
Adam

💻
Adam Elmore
Adam Elmore

💻
Adrian Dimech
Adrian Dimech

💻
Adrian Mace
Adrian Mace

💻
Alejandro Lorefice
Alejandro Lorefice

💻
Alexander Forsyth
Alexander Forsyth

💻
Alexander Steppke
Alexander Steppke

💻
Amani Kilumanga
Amani Kilumanga

💻
Amin Fazl
Amin Fazl

💻
Amir Szekely
Amir Szekely

💻
Anderson Gomes
Anderson Gomes

💻
Andre de Camargo
Andre de Camargo

💻
Andrew Hammond
Andrew Hammond

💻
Angelo Di Pilla
Angelo Di Pilla

💻
Ansgar Mertens
Ansgar Mertens

💻
Armando J. Ortiz Garcia
Armando J. Ortiz Garcia

💻
Arun Donti
Arun Donti

💻
Ash
Ash

💻
Balagopal Kanattil
Balagopal Kanattil

💻
Bart Callant
Bart Callant

💻
Beau Bouchard
Beau Bouchard

💻
Ben Limmer
Ben Limmer

💻
Bilal Quadri
Bilal Quadri

💻
Boris Petersen
Boris Petersen

💻
Braden Mars
Braden Mars

💻
Brandon Miller
Brandon Miller

💻
Brian Leonard
Brian Leonard

💻
Calvin Combs
Calvin Combs

💻
Cameron Childress
Cameron Childress

💻
Campion Fellin
Campion Fellin

💻
Carlos Tasada
Carlos Tasada

💻
Chris Gatt
Chris Gatt

💻
Christopher Rybicki
Christopher Rybicki

💻
Cory Hall
Cory Hall

💻
Court Schuett
Court Schuett

💻
Craig Burdulis
Craig Burdulis

💻
Cristian Pallarés
Cristian Pallarés

💻
Daniel Schmidt
Daniel Schmidt

💻
Danny Steenman
Danny Steenman

💻
Derek Kershner
Derek Kershner

💻
Eduardo Rodrigues
Eduardo Rodrigues

💻
Elad Ben-Israel
Elad Ben-Israel

💻
Eli Polonsky
Eli Polonsky

💻
Eligio Mariño
Eligio Mariño

💻
Eric Tucker
Eric Tucker

💻
Eugene Cheung
Eugene Cheung

💻
Fons Biemans
Fons Biemans

💻
Fynn Flügge
Fynn Flügge

💻
Gary Sassano
Gary Sassano

💻
Grady Barrett
Grady Barrett

💻
Greg Herlein
Greg Herlein

💻
Gregg
Gregg

💻
Hasan
Hasan

💻
Hassan Azhar
Hassan Azhar

💻
Hassan Mahmud
Hassan Mahmud

💻
Hassan Mahmud
Hassan Mahmud

💻
Heiko Rothe
Heiko Rothe

💻
Henri Yandell
Henri Yandell

💻
Henry Sachs
Henry Sachs

💻
Hoseung
Hoseung

💻
Ikko Ashimine
Ikko Ashimine

💻
Jack Leslie
Jack Leslie

💻
Jack Moseley
Jack Moseley

💻
Jack Stevenson
Jack Stevenson

💻
Jacob
Jacob

💻
Jake Pearson
Jake Pearson

💻
Jan Brauer
Jan Brauer

💻
Jeff Malins
Jeff Malins

💻
Jeremy Jonas
Jeremy Jonas

💻
Jesse Grabowski
Jesse Grabowski

💻
JoLo
JoLo

💻
Job de Noo
Job de Noo

💻
Jonathan Goldwasser
Jonathan Goldwasser

💻
Joost van der Waal
Joost van der Waal

💻
Jordan Sinko
Jordan Sinko

💻
Joseph Egan
Joseph Egan

💻
Josh Kellendonk
Josh Kellendonk

💻
Juho Majasaari
Juho Majasaari

💻
Juho Saarinen
Juho Saarinen

💻
Julian Michel
Julian Michel

💻
Kaizen Conroy
Kaizen Conroy

💻
Kenneth Winner
Kenneth Winner

💻
Kenneth Wußmann
Kenneth Wußmann

💻
Kenny Gatdula
Kenny Gatdula

💻
Konstantin Vyatkin
Konstantin Vyatkin

💻
Kraig Amador
Kraig Amador

💻
Kunal Dabir
Kunal Dabir

💻
Kyle Laker
Kyle Laker

💻
Lex Felix
Lex Felix

💻
Lex Felix
Lex Felix

💻
Liam Johnston
Liam Johnston

💻
Manuel
Manuel

💻
Marcio Cruz de Almeida
Marcio Cruz de Almeida

💻
Mark McCulloh
Mark McCulloh

💻
Mark McCulloh
Mark McCulloh

💻
Mark Nielsen
Mark Nielsen

💻
Markus Schuch
Markus Schuch

💻
Marnix Dessing
Marnix Dessing

💻
Martin Muller
Martin Muller

💻
Martin Zuber
Martin Zuber

💻
Masashi Tomooka
Masashi Tomooka

💻
Matt Gucci
Matt Gucci

💻
Matt Martz
Matt Martz

💻
Matt Wise
Matt Wise

💻
Matteo Sessa
Matteo Sessa

💻
Matthew Bonig
Matthew Bonig

💻
Matthew Gamble
Matthew Gamble

💻
Max Körlinge
Max Körlinge

💻
Mayur Mahrotri
Mayur Mahrotri

💻
Mayuresh Dharwadkar
Mayuresh Dharwadkar

💻
Mike
Mike

💻
Mitchell Valine
Mitchell Valine

💻
Momo Kornher
Momo Kornher

💻
Mukul Bansal
Mukul Bansal

💻
Neil Kuan
Neil Kuan

💻
Nick Keers
Nick Keers

💻
Nick Lynch
Nick Lynch

💻
Nicolas Byl
Nicolas Byl

💻
Nikhil Zadoo
Nikhil Zadoo

💻
Niko Virtala
Niko Virtala

💻
Niraj Palecha
Niraj Palecha

💻
Nurbanu
Nurbanu

💻
Pahud Hsieh
Pahud Hsieh

💻
Patrick
Patrick

💻
Patrick Aikens
Patrick Aikens

💻
Patrick Florek
Patrick Florek

💻
Philip M. Gollucci
Philip M. Gollucci

💻
Philip White
Philip White

💻
Philipp Garbe
Philipp Garbe

💻
Rafal Wilinski
Rafal Wilinski

💻
Rami Husein
Rami Husein

💻
Rico Huijbers
Rico Huijbers

💻
Rob Giseburt
Rob Giseburt

💻
Robbie Mackay
Robbie Mackay

💻
Robert
Robert

💻
Rodrigo Farias Rezino
Rodrigo Farias Rezino

💻
Roger Chi
Roger Chi

💻
Romain Marcadier
Romain Marcadier

💻
Roman Vasilev
Roman Vasilev

💻
Ruben Pascal Abel
Ruben Pascal Abel

💻
Ryan Sonshine
Ryan Sonshine

💻
Ryosuke Iwanaga
Ryosuke Iwanaga

💻
Samuel Tschiedel
Samuel Tschiedel

💻
Saud Khanzada
Saud Khanzada

💻
Scott McFarlane
Scott McFarlane

💻
Scott Schreckengaust
Scott Schreckengaust

💻
Sebastian Korfmann
Sebastian Korfmann

💻
Shawn MacIntyre
Shawn MacIntyre

💻
Suhas Gaddam
Suhas Gaddam

💻
Thomas Klinger
Thomas Klinger

💻
Thorsten Hoeger
Thorsten Hoeger

💻
Tiara
Tiara

💻
Tobias
Tobias

💻
Tom Howard
Tom Howard

💻
Tom Keller
Tom Keller

💻
Tomasz Łakomy
Tomasz Łakomy

💻
Travis Martensen
Travis Martensen

💻
Victor Korzunin
Victor Korzunin

💻
VinayKokate22
VinayKokate22

💻
Vlad Cos
Vlad Cos

💻
Will Dady
Will Dady

💻
Yigong Liu
Yigong Liu

💻
Yohta Kimura
Yohta Kimura

💻
Yuichi Kageyama
Yuichi Kageyama

💻
Yuval
Yuval

💻
andrestone
andrestone

💻
codeLeeek
codeLeeek

💻
flyingImer
flyingImer

💻
huaxk
huaxk

💻
john-tipper
john-tipper

💻
karlderkaefer
karlderkaefer

💻
kmkhr
kmkhr

💻
kt-hr
kt-hr

💻
lmarsden
lmarsden

💻
michaeltimbs
michaeltimbs

💻
orlandronen1
orlandronen1

💻
pvbouwel
pvbouwel

💻
suhussai
suhussai

💻
t0bst4r
t0bst4r

💻
tHyt-lab
tHyt-lab

💻
txxnano
txxnano

💻
vVahe
vVahe

💻
zetashift
zetashift

💻

License

Distributed under the Apache-2.0 license.

Package Sidebar

Install

npm i projen

Weekly Downloads

175,754

Version

0.80.2

License

Apache-2.0

Unpacked Size

12 MB

Total Files

1808

Last publish

Collaborators

  • cdklabs-automation