- Notifications
You must be signed in to change notification settings - Fork385
Rapidly build modern applications with advanced configuration management
License
projen/projen
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Define and maintain complex project configuration through code.
Documentation ·Changelog ·Project types ·Join the community
projen synthesizes project configuration files such aspackage.json,tsconfig.json,.gitignore, GitHub Workflows, eslint, jest, etc. from awell-typed definition written in JavaScript.
As opposed to existing templating/scaffolding tools,projen is not a one-offgenerator. Synthesized files should never be manually edited (in fact, projenenforces that). To modify your project setup, users interact with richstrongly-typed class and executeprojen to update their project configurationfiles.
By defining a custom project type and using projen in multiple repositories, it'spossible to update configuration files and CI/CD workflows across dozens (orhundreds!?) of projects.
Check outthis talk about projen from its creator.
projen doesn't need to be installed. You will be usingnpx to runprojen 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 (usenpx projen new without a type for afull list):
Built-in: (runnpx projen new <type>)
- awscdk-app-java - AWS CDK app in Java.
- awscdk-app-py - AWS CDK app in Python.
- awscdk-app-ts - AWS CDK app in TypeScript.
- awscdk-construct - AWS CDK construct library project.
- cdk8s-app-py - CDK8s app in Python.
- 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 using JavaScript.
- nextjs-ts - Next.js project using TypeScript.
- node - Node.js project.
- project - Base project.
- python - Python project.
- react - React project using JavaScript.
- react-ts - React project using TypeScript.
- typescript - TypeScript project.
- typescript-app - TypeScript app.
External: (runnpx projen new --from <type>)
- projen-github-action-typescript - GitHub Action in TypeScript project.
Use
npx projen new PROJECT-TYPE --helpto view a list of command lineswitches that allows you to specify most project options during bootstrapping.For example:npx projen new jsii --author-name "Jerry Berry".
Thenew command will create a.projenrc.js file which looks like this forjsii projects:
const{ JsiiProject}=require('projen');constproject=newJsiiProject({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 callssynth() to synthesize the project files. By default, thenew command willalso 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-runningnpx projen to synthesize again.
The files generated byprojen are considered an "implementation detail" andprojen protects them from being manually edited (most files are markedread-only, and an "anti tamper" check is configured in the CI build workflowto ensure that files are not updated during build).
For example, to setup PyPI publishing injsii projects, you can usepublishToPypi option:
constproject=newJsiiProject({// ...publishToPypi:{distName:"mydist",module:"my_module",}});
Run:
npx projen
And you'll notice that yourpackage.json file now contains apython section initsjsii config and the GitHubrelease.yml workflow includes a PyPIpublishing step.
We recommend to put this in your shell profile, so you can simply runpj everytime you update.projenrc.js:
alias pj='npx projen'
Most projects come with an assortment oftasks that handle variousdevelopment activities, from compiling to publishing. Tasks can be and composedtogether, and can be run as local commands or turned into GitHub workflows. Youcan list all tasks withnpx projen --help:
$ npx projen --helpprojen [command]Commands: projen new [PROJECT-TYPE-NAME] [OPTIONS] Creates a new projen project projen clobber hard resets to HEAD of origin and cleans thelocal repo projen compile Only compile projentest Run tests projen build Full release build (test+compile) projen upgrade upgrade dependencies (including projen)...
Thebuild task is the same task that's executed in your CI builds. Ittypically 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:
# Bashprojen completion>>~/.bashrc# ZSHprojen completion>>~/.zshrc
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
For documentation including examples and a full API reference, visithttps://projen.io/.
projen takes a "batteries included" approach and aims to offer dozens of different project types out ofthe box (we are just getting started). Thinkprojen 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 thatextendsprojen.Project (or one of its derivatives). Projen automatically discovers project types so yourtype will immediately be available inprojen new.
projen is bundled with many project types out of the box, but it can also workwith project types and components defined in external jsii modules (the reasonwe need jsii is because projen uses the jsii metadata to discover project types& options in projen new).
Say we have a module in npm calledprojen-vuejs which includes a single projecttype 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 typeAPIs. You can also use any package syntax supported byyarnadd likeprojen-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 theprojen-vuejs module from npm(version 2.0.0 and above), discover the project types in it and bootstrap thevuejs-ts project type. It will assign the value"my awesome vue project" tothedescription field. If you examine your.projenrc.js file, you'll seethatprojen-vuejs is defined as a dev dependency:
const{ VueJsProject}=require('projen-vuejs');constproject=newVueJsProject({name:'my-vuejs-sample',description:"my awesome vue project",// ...devDeps:['projen-vuejs']});project.synth();
SeeVision.
Not at all! JavaScript is the default, but it's also possible to write it inJava, Python, TypeScript, or even JSON. This is madepossible by thejsii library which allows usto write APIs once and generate libraries in several languages. You can choosea different language by passing the--projenrc-ts,--projenrc-py,--projenrc-java, or--projenrc-json flags when runningprojen new.
Note: using a.projenrc.json file to specify configuration only allowsaccessing a subset of the entire API - the options which are passed to theconstructor of each project type.
projen has an unofficialVS Code extension. Check it out!
The projen community can be found within the #projen channel in thecdk.devcommunity Slack workspace.
- Thursday June 30, 2022
- 1-2pm America/New_York (EDT)
- CFP a Google Form
- CFP Closes Saturday April 30, 2022
- Hosted onZoom
Contributions of all kinds are welcome! Check out ourcontributor'sguide and ourcode 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 theApache-2.0 license.
About
Rapidly build modern applications with advanced configuration management