CDK for software projects


Keywords
aws-cdk, cdk, constructs, generator, hacktoberfest, jsii, repository-management, repository-tools, scaffolding, templates, typescript
License
Apache-2.0
Install
pip install projen==0.58.29

Documentation

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 ElKhayyat
Adam ElKhayyat

πŸ’»
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

πŸ’»
Andrew Kostka
Andrew Kostka

πŸ’»
Angelo Di Pilla
Angelo Di Pilla

πŸ’»
Ansgar Mertens
Ansgar Mertens

πŸ’»
Armando J. Ortiz Garcia
Armando J. Ortiz Garcia

πŸ’»
Arun Donti
Arun Donti

πŸ’»
Ash
Ash

πŸ’»
Austin
Austin

πŸ’»
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

πŸ’»
Cao Peng
Cao Peng

πŸ’»
Carlos Tasada
Carlos Tasada

πŸ’»
Chris Bateman
Chris Bateman

πŸ’»
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

πŸ’»
Francisco Robles MartΓ­n
Francisco Robles MartΓ­n

πŸ“–
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

πŸ’»
Patrick O'Connor
Patrick O'Connor

πŸ’»
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

πŸ’»
Vinayak Kukreja
Vinayak Kukreja

πŸ’»
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.