Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/projen/projen

Rapidly build modern applications with advanced configuration management
https://github.com/projen/projen
aws-cdk cdk constructs generator hacktoberfest jsii repository-management repository-tools scaffolding templates typescript
Last synced: 4 days ago
JSON representation
Rapidly build modern applications with advanced configuration management
Host: GitHub
URL: https://github.com/projen/projen
Owner: projen
License: apache-2.0
Created: 2020-05-11T05:07:24.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2024-10-29T11:28:13.000Z (2 months ago)
Last Synced: 2024-10-29T11:46:52.290Z (2 months ago)
Topics: aws-cdk, cdk, constructs, generator, hacktoberfest, jsii, repository-management, repository-tools, scaffolding, templates, typescript
Language: TypeScript
Homepage: https://projen.io
Size: 25.1 MB
Stars: 2,661
Watchers: 29
Forks: 374
Open Issues: 225
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project

awesome - projen/projen - Rapidly build modern applications with advanced configuration management (TypeScript)
awesome-cloudops - Projen - raw/projen/projen" alt="Issues"><br><img align="right" src="https://img.shields.io/github/last-commit/projen/projen">](https://github.com/projen/projen) | | project-structure | Project structure as a code. Projen is one of the core project behind CDK | (Tools)
awesome-github-repos - projen/projen - Rapidly build modern applications with advanced configuration management (TypeScript)
awesome-list - projen
awesome-javascript - projen
awesome-javascript - projen
README

        


  

    

    
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](https://youtu.be/SOWMPzXtTCw) about projen from its creator.

## Getting Started

_projen_ doesn't need to be installed. You will be using [npx](https://docs.npmjs.com/cli/v7/commands/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...

...

```

### Project types

Currently supported project types (use `npx projen new` without a type for a

full list):

**Built-in:** (run `npx projen new `)

* [awscdk-app-java](https://projen.io/docs/api/awscdk#awscdkjavaapp-) - AWS CDK app in Java.

* [awscdk-app-py](https://projen.io/docs/api/awscdk#awscdkpythonapp-) - AWS CDK app in Python.

* [awscdk-app-ts](https://projen.io/docs/api/awscdk#awscdktypescriptapp-) - AWS CDK app in TypeScript.

* [awscdk-construct](https://projen.io/docs/api/awscdk#awscdkconstructlibrary-) - AWS CDK construct library project.

* [cdk8s-app-py](https://projen.io/docs/api/cdk8s#cdk8spythonapp-) - CDK8s app in Python.

* [cdk8s-app-ts](https://projen.io/docs/api/cdk8s#cdk8stypescriptapp-) - CDK8s app in TypeScript.

* [cdk8s-construct](https://projen.io/docs/api/cdk8s#constructlibrarycdk8s-) - CDK8s construct library project.

* [cdktf-construct](https://projen.io/docs/api/cdktf#constructlibrarycdktf-) - CDKTF construct library project.

* [java](https://projen.io/docs/api/java#javaproject-) - Java project.

* [jsii](https://projen.io/docs/api/cdk#jsiiproject-) - Multi-language jsii library project.

* [nextjs](https://projen.io/docs/api/web#nextjsproject-) - Next.js project using JavaScript.

* [nextjs-ts](https://projen.io/docs/api/web#nextjstypescriptproject-) - Next.js project using TypeScript.

* [node](https://projen.io/docs/api/javascript#nodeproject-) - Node.js project.

* [project](https://projen.io/docs/api/projen#project-) - Base project.

* [python](https://projen.io/docs/api/python#pythonproject-) - Python project.

* [react](https://projen.io/docs/api/web#reactproject-) - React project using JavaScript.

* [react-ts](https://projen.io/docs/api/web#reacttypescriptproject-) - React project using TypeScript.

* [typescript](https://projen.io/docs/api/typescript#typescriptproject-) - TypeScript project.

* [typescript-app](https://projen.io/docs/api/typescript#typescriptappproject-) - TypeScript app.

**External:** (run `npx projen new --from `)

* [projen-github-action-typescript](https://github.com/projen/projen-github-action-typescript/blob/main/API.md) - GitHub Action in TypeScript project.

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

```js

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

[`publishToPypi option`](https://projen.io/publisher.html):

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

```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 with `npx 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 `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:

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

## 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:

```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](https://classic.yarnpkg.com/en/docs/cli/add#toc-adding-dependencies) like

`[email protected]`, `file:/path/to/local/folder`,

`[email protected]/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-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:

```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](./VISION.md).

## 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](https://github.com/aws/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!

[VS Code extension]: https://marketplace.visualstudio.com/items?itemName=MarkMcCulloh.vscode-projen

## Community

The projen community can be found within the #projen channel in the [cdk.dev]

community Slack workspace.

[cdk.dev]: https://cdk.dev/

### Virtual Meetup

- Thursday June 30, 2022 

- 1-2pm America/New_York (EDT)

- [CFP](https://bit.ly/3NEc0UQ) a Google Form

- CFP Closes Saturday April 30, 2022

- Hosted on [Zoom](https://zoom.us/j/92399854777?pwd=OUZybHlobHNoZUs1VVordWhaRTVGdz09#success)

## Contributions

Contributions of all kinds are welcome! Check out our [contributor's

guide](./CONTRIBUTING.md) and our [code of conduct](./CODE_OF_CONDUCT.md).

For a quick start, check out a development environment:

```bash

$ git clone [email protected]:projen/projen

$ cd projen

$ yarn

$ yarn watch # compile in the background

```

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

[![All Contributors](https://img.shields.io/badge/all_contributors-193-orange.svg?style=flat-square)](#contributors-)

  

    

      
_Aatman
💻

      
_{Abdullah Sahin}
💻

      
_Adam
💻

      
_{Adam ElKhayyat}
💻

      
_{Adam Elmore}
💻

      
_{Adrian Dimech}
💻

      
_{Adrian Mace}
💻

    

    

      
_{Alejandro Lorefice}
💻

      
_{Alexander Forsyth}
💻

      
_{Alexander Steppke}
💻

      
_{Amani Kilumanga}
💻

      
_{Amin Fazl}
💻

      
_{Amir Szekely}
💻

      
_{Anderson Gomes}
💻

    

    

      
_{Andre de Camargo}
💻

      
_{Andrew Hammond}
💻

      
_{Andrew Kostka}
💻

      
_{Angelo Di Pilla}
💻

      
_{Ansgar Mertens}
💻

      
_{Armando J. Ortiz Garcia}
💻

      
_{Arun Donti}
💻

    

    

      
_Ash
💻

      
_Austin
💻

      
_{Balagopal Kanattil}
💻

      
_{Bart Callant}
💻

      
_{Beau Bouchard}
💻

      
_{Ben Limmer}
💻

      
_{Bilal Quadri}
💻

    

    

      
_{Boris Petersen}
💻

      
_{Braden Mars}
💻

      
_{Brandon Miller}
💻

      
_{Brian Leonard}
💻

      
_{Calvin Combs}
💻

      
_{Cameron Childress}
💻

      
_{Campion Fellin}
💻

    

    

      
_{Cao Peng}
💻

      
_{Carlos Tasada}
💻

      
_{Chris Bateman}
💻

      
_{Chris Gatt}
💻

      
_{Christopher Rybicki}
💻

      
_{Cory Hall}
💻

      
_{Court Schuett}
💻

    

    

      
_{Craig Burdulis}
💻

      
_{Cristian Pallarés}
💻

      
_{Daniel Schmidt}
💻

      
_{Danny Steenman}
💻

      
_{Derek Kershner}
💻

      
_{Eduardo Rodrigues}
💻

      
_{Elad Ben-Israel}
💻

    

    

      
_{Eli Polonsky}
💻

      
_{Eligio Mariño}
💻

      
_{Eric Tucker}
💻

      
_{Eugene Cheung}
💻

      
_{Fons Biemans}
💻

      
_{Francisco Robles Martín}
📖

      
_{Fynn Flügge}
💻

    

    

      
_{Gary Sassano}
💻

      
_{Grady Barrett}
💻

      
_{Greg Herlein}
💻

      
_Gregg
💻

      
_Hasan
💻

      
_{Hassan Azhar}
💻

      
_{Hassan Mahmud}
💻

    

    

      
_{Hassan Mahmud}
💻

      
_{Heiko Rothe}
💻

      
_{Henri Yandell}
💻

      
_{Henry Sachs}
💻

      
_Hoseung
💻

      
_{Ikko Ashimine}
💻

      
_{Jack Leslie}
💻

    

    

      
_{Jack Moseley}
💻

      
_{Jack Stevenson}
💻

      
_Jacob
💻

      
_{Jake Pearson}
💻

      
_{Jan Brauer}
💻

      
_{Jeff Malins}
💻

      
_{Jeremy Jonas}
💻

    

    

      
_{Jesse Grabowski}
💻

      
_JoLo
💻

      
_{Job de Noo}
💻

      
_{Jonathan Goldwasser}
💻

      
_{Joost van der Waal}
💻

      
_{Jordan Sinko}
💻

      
_{Joseph Egan}
💻

    

    

      
_{Josh Kellendonk}
💻

      
_{Juho Majasaari}
💻

      
_{Juho Saarinen}
💻

      
_{Julian Michel}
💻

      
_{Kaizen Conroy}
💻

      
_{Kenneth Winner}
💻

      
_{Kenneth Wußmann}
💻

    

    

      
_{Kenny Gatdula}
💻

      
_{Konstantin Vyatkin}
💻

      
_{Kraig Amador}
💻

      
_{Kunal Dabir}
💻

      
_{Kyle Laker}
💻

      
_{Lex Felix}
💻

      
_{Lex Felix}
💻

    

    

      
_{Liam Johnston}
💻

      
_Manuel
💻

      
_{Marcio Cruz de Almeida}
💻

      
_{Mark McCulloh}
💻

      
_{Mark McCulloh}
💻

      
_{Mark Nielsen}
💻

      
_{Markus Schuch}
💻

    

    

      
_{Marnix Dessing}
💻

      
_{Martin Muller}
💻

      
_{Martin Zuber}
💻

      
_{Masashi Tomooka}
💻

      
_{Matt Gucci}
💻

      
_{Matt Martz}
💻

      
_{Matt Wise}
💻

    

    

      
_{Matteo Sessa}
💻

      
_{Matthew Bonig}
💻

      
_{Matthew Gamble}
💻

      
_{Max Körlinge}
💻

      
_{Mayur Mahrotri}
💻

      
_{Mayuresh Dharwadkar}
💻

      
_Mike
💻

    

    

      
_{Mitchell Valine}
💻

      
_{Momo Kornher}
💻

      
_{Mukul Bansal}
💻

      
_{Neil Kuan}
💻

      
_{Nick Keers}
💻

      
_{Nick Lynch}
💻

      
_{Nicolas Byl}
💻

    

    

      
_{Nikhil Zadoo}
💻

      
_{Niko Virtala}
💻

      
_{Niraj Palecha}
💻

      
_Nurbanu
💻

      
_{Pahud Hsieh}
💻

      
_Patrick
💻

      
_{Patrick Aikens}
💻

    

    

      
_{Patrick Florek}
💻

      
_{Patrick O'Connor}
💻

      
_{Philip M. Gollucci}
💻

      
_{Philip White}
💻

      
_{Philipp Garbe}
💻

      
_{Rafal Wilinski}
💻

      
_{Rami Husein}
💻

    

    

      
_{Rico Huijbers}
💻

      
_{Rob Giseburt}
💻

      
_{Robbie Mackay}
💻

      
_Robert
💻

      
_{Rodrigo Farias Rezino}
💻

      
_{Roger Chi}
💻

      
_{Romain Marcadier}
💻

    

    

      
_{Roman Vasilev}
💻

      
_{Ruben Pascal Abel}
💻

      
_{Ryan Sonshine}
💻

      
_{Ryosuke Iwanaga}
💻

      
_{Samuel Tschiedel}
💻

      
_{Saud Khanzada}
💻

      
_{Scott McFarlane}
💻

    

    

      
_{Scott Schreckengaust}
💻

      
_{Sebastian Korfmann}
💻

      
_{Shawn MacIntyre}
💻

      
_{Suhas Gaddam}
💻

      
_{Thomas Klinger}
💻

      
_{Thorsten Hoeger}
💻

      
_Tiara
💻

    

    

      
_Tobias
💻

      
_{Tom Howard}
💻

      
_{Tom Keller}
💻

      
_{Tomasz Łakomy}
💻

      
_{Travis Martensen}
💻

      
_{Victor Korzunin}
💻

      
_{VinayKokate22}
💻

    

    

      
_{Vinayak Kukreja}
💻

      
_{Vlad Cos}
💻

      
_{Will Dady}
💻

      
_{Yigong Liu}
💻

      
_{Yohta Kimura}
💻

      
_{Yuichi Kageyama}
💻

      
_Yuval
💻

    

    

      
_andrestone
💻

      
_codeLeeek
💻

      
_flyingImer
💻

      
_huaxk
💻

      
_john-tipper
💻

      
_{karlderkaefer}
💻

      
_kmkhr
💻

    

    

      
_kt-hr
💻

      
_lmarsden
💻

      
_michaeltimbs
💻

      
_orlandronen1
💻

      
_pvbouwel
💻

      
_suhussai
💻

      
_t0bst4r
💻

    

    

      
_tHyt-lab
💻

      
_txxnano
💻

      
_vVahe
💻

      
_zetashift
💻

    

  

## License

Distributed under the [Apache-2.0](./LICENSE) license.