@Stability(Experimental)
Package io.github.cdklabs.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 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>)
- 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: (run npx 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 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):
License
Distributed under the Apache-2.0 license.
-
Interface Summary Interface Description CreateProjectOptions Dependency (experimental) Represents a project dependency.DependencyCoordinates (experimental) Coordinates of the dependency (name and version).DepsManifest DevEnvironmentOptions (experimental) Base options for configuring a container-based development environment.DockerComposeBuild (experimental) Build arguments for creating a docker image.DockerComposeNetworkConfig (experimental) Network configuration.DockerComposeNetworkIpamConfig (experimental) IPAM configuration.DockerComposeNetworkIpamSubnetConfig (experimental) IPAM subnet configuration.DockerComposePortMappingOptions (experimental) Options for port mappings.DockerComposeProps (experimental) Props for DockerCompose.DockerComposeServiceDescription (experimental) Description of a docker-compose.yml service.DockerComposeServicePort (experimental) A service port mapping.DockerComposeVolumeConfig (experimental) Volume configuration.DockerComposeVolumeMount (experimental) Service volume mounting information.FileBaseOptions GitOptions (experimental) Git configuration options.GitpodOptions (experimental) Constructor options for the Gitpod component.GitpodPort (experimental) Options for an exposed port on Gitpod.GitpodPrebuilds (experimental) Configure the Gitpod App for prebuilds.GitpodTask (experimental) Configure options for a task to be run when opening a Gitpod workspace (e.g.GroupRunnerOptions IDevEnvironment (experimental) Abstract interface for container-based development environments, such as Gitpod and GitHub Codespaces.IDevEnvironment.Jsii$Default Internal default implementation forIDevEnvironment.IDockerComposeNetworkBinding (experimental) Network binding information.IDockerComposeNetworkBinding.Jsii$Default Internal default implementation forIDockerComposeNetworkBinding.IDockerComposeNetworkConfig (experimental) Storage for network configuration.IDockerComposeNetworkConfig.Jsii$Default Internal default implementation forIDockerComposeNetworkConfig.IDockerComposeServiceName (experimental) An interface providing the name of a docker compose service.IDockerComposeServiceName.Jsii$Default Internal default implementation forIDockerComposeServiceName.IDockerComposeVolumeBinding (experimental) Volume binding information.IDockerComposeVolumeBinding.Jsii$Default Internal default implementation forIDockerComposeVolumeBinding.IDockerComposeVolumeConfig (experimental) Storage for volume configuration.IDockerComposeVolumeConfig.Jsii$Default Internal default implementation forIDockerComposeVolumeConfig.IgnoreFileOptions IniFileOptions (experimental) Options forIniFile.InitProject (experimental) Information passed fromprojen newto the project object when the project is first created.IResolvable IResolvable.Jsii$Default Internal default implementation forIResolvable.IResolver (experimental) API for resolving tokens when synthesizing file content.IResolver.Jsii$Default Internal default implementation forIResolver.JsonFileOptions (experimental) Options forJsonFile.LicenseOptions LoggerOptions (experimental) Options for logging utilities.MakefileOptions (experimental) Options for Makefiles.ObjectFileOptions (experimental) Options forObjectFile.ProjectOptions (experimental) Options forProject.ProjenrcJsonOptions ProjenrcOptions Deprecated. useProjenrcJsonOptionsRenovatebotOptions (experimental) Options for Renovatebot.ResolveOptions (experimental) Resolve options.Rule (experimental) A Make rule.SampleDirOptions (experimental) SampleDir options.SampleFileOptions (experimental) Options for the SampleFile object.SampleReadmeProps (experimental) SampleReadme Properties.SnapshotOptions (experimental) Options for the Snapshot synthesis.SourceCodeOptions (experimental) Options forSourceCodeFile.TaskCommonOptions TaskOptions TasksManifest (experimental) Schema fortasks.json.TaskSpec (experimental) Specification of a single task.TaskStep (experimental) A single step within a task.TaskStepOptions (experimental) Options for task steps.TextFileOptions (experimental) Options forTextFile.TomlFileOptions (experimental) Options forTomlFile.VersionOptions (experimental) Options forVersion.XmlFileOptions (experimental) Options forXmlFile.YamlFileOptions (experimental) Options forJsonFile. -
Class Summary Class Description Component (experimental) Represents a project component.CreateProjectOptions.Builder A builder forCreateProjectOptionsCreateProjectOptions.Jsii$Proxy An implementation forCreateProjectOptionsDependencies (experimental) TheDependenciescomponent is responsible to track the list of dependencies a project has, and then used by project types as the model for rendering project-specific dependency manifests such as the dependencies sectionpackage.jsonfiles.Dependency.Builder A builder forDependencyDependency.Jsii$Proxy An implementation forDependencyDependencyCoordinates.Builder A builder forDependencyCoordinatesDependencyCoordinates.Jsii$Proxy An implementation forDependencyCoordinatesDepsManifest.Builder A builder forDepsManifestDepsManifest.Jsii$Proxy An implementation forDepsManifestDevEnvironmentDockerImage (experimental) Options for specifying the Docker image of the container.DevEnvironmentOptions.Builder A builder forDevEnvironmentOptionsDevEnvironmentOptions.Jsii$Proxy An implementation forDevEnvironmentOptionsDockerCompose (experimental) Create a docker-compose YAML file.DockerCompose.Builder (experimental) A fluent builder forDockerCompose.DockerComposeBuild.Builder A builder forDockerComposeBuildDockerComposeBuild.Jsii$Proxy An implementation forDockerComposeBuildDockerComposeNetworkConfig.Builder A builder forDockerComposeNetworkConfigDockerComposeNetworkConfig.Jsii$Proxy An implementation forDockerComposeNetworkConfigDockerComposeNetworkIpamConfig.Builder A builder forDockerComposeNetworkIpamConfigDockerComposeNetworkIpamConfig.Jsii$Proxy An implementation forDockerComposeNetworkIpamConfigDockerComposeNetworkIpamSubnetConfig.Builder A builder forDockerComposeNetworkIpamSubnetConfigDockerComposeNetworkIpamSubnetConfig.Jsii$Proxy An implementation forDockerComposeNetworkIpamSubnetConfigDockerComposePortMappingOptions.Builder A builder forDockerComposePortMappingOptionsDockerComposePortMappingOptions.Jsii$Proxy An implementation forDockerComposePortMappingOptionsDockerComposeProps.Builder A builder forDockerComposePropsDockerComposeProps.Jsii$Proxy An implementation forDockerComposePropsDockerComposeService (experimental) A docker-compose service.DockerComposeService.Builder (experimental) A fluent builder forDockerComposeService.DockerComposeServiceDescription.Builder A builder forDockerComposeServiceDescriptionDockerComposeServiceDescription.Jsii$Proxy An implementation forDockerComposeServiceDescriptionDockerComposeServicePort.Builder A builder forDockerComposeServicePortDockerComposeServicePort.Jsii$Proxy An implementation forDockerComposeServicePortDockerComposeVolumeConfig.Builder A builder forDockerComposeVolumeConfigDockerComposeVolumeConfig.Jsii$Proxy An implementation forDockerComposeVolumeConfigDockerComposeVolumeMount.Builder A builder forDockerComposeVolumeMountDockerComposeVolumeMount.Jsii$Proxy An implementation forDockerComposeVolumeMountFileBase FileBaseOptions.Builder A builder forFileBaseOptionsFileBaseOptions.Jsii$Proxy An implementation forFileBaseOptionsGitAttributesFile (experimental) Assign attributes to file names in a git repository.GitOptions.Builder A builder forGitOptionsGitOptions.Jsii$Proxy An implementation forGitOptionsGitpod (experimental) The Gitpod component which emits .gitpod.yml.Gitpod.Builder (experimental) A fluent builder forGitpod.GitpodOptions.Builder A builder forGitpodOptionsGitpodOptions.Jsii$Proxy An implementation forGitpodOptionsGitpodPort.Builder A builder forGitpodPortGitpodPort.Jsii$Proxy An implementation forGitpodPortGitpodPrebuilds.Builder A builder forGitpodPrebuildsGitpodPrebuilds.Jsii$Proxy An implementation forGitpodPrebuildsGitpodTask.Builder A builder forGitpodTaskGitpodTask.Jsii$Proxy An implementation forGitpodTaskGroupRunnerOptions.Builder A builder forGroupRunnerOptionsGroupRunnerOptions.Jsii$Proxy An implementation forGroupRunnerOptionsIDevEnvironment.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.IDockerComposeNetworkBinding.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.IDockerComposeNetworkConfig.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.IDockerComposeServiceName.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.IDockerComposeVolumeBinding.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.IDockerComposeVolumeConfig.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.IgnoreFile IgnoreFile.Builder (experimental) A fluent builder forIgnoreFile.IgnoreFileOptions.Builder A builder forIgnoreFileOptionsIgnoreFileOptions.Jsii$Proxy An implementation forIgnoreFileOptionsIniFile (experimental) Represents an INI file.IniFile.Builder (experimental) A fluent builder forIniFile.IniFileOptions.Builder A builder forIniFileOptionsIniFileOptions.Jsii$Proxy An implementation forIniFileOptionsInitProject.Builder A builder forInitProjectInitProject.Jsii$Proxy An implementation forInitProjectIResolvable.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.IResolver.Jsii$Proxy A proxy class which represents a concrete javascript instance of this type.JsonFile (experimental) Represents a JSON file.JsonFile.Builder (experimental) A fluent builder forJsonFile.JsonFileOptions.Builder A builder forJsonFileOptionsJsonFileOptions.Jsii$Proxy An implementation forJsonFileOptionsJsonPatch (experimental) Utility for applying RFC-6902 JSON-Patch to a document.License License.Builder (experimental) A fluent builder forLicense.LicenseOptions.Builder A builder forLicenseOptionsLicenseOptions.Jsii$Proxy An implementation forLicenseOptionsLogger (experimental) Project-level logging utilities.Logger.Builder (experimental) A fluent builder forLogger.LoggerOptions.Builder A builder forLoggerOptionsLoggerOptions.Jsii$Proxy An implementation forLoggerOptionsMakefile (experimental) Minimal Makefile.Makefile.Builder (experimental) A fluent builder forMakefile.MakefileOptions.Builder A builder forMakefileOptionsMakefileOptions.Jsii$Proxy An implementation forMakefileOptionsObjectFile (experimental) Represents an Object file.ObjectFileOptions.Builder A builder forObjectFileOptionsObjectFileOptions.Jsii$Proxy An implementation forObjectFileOptionsProject (experimental) Base project.Project.Builder (experimental) A fluent builder forProject.ProjectBuild (experimental) Manages a standard build process for all projects.ProjectOptions.Builder A builder forProjectOptionsProjectOptions.Jsii$Proxy An implementation forProjectOptionsProjects (experimental) Programmatic API for projen.ProjectTree Projenrc Deprecated. useProjenrcJsonProjenrc.Builder (experimental) A fluent builder forProjenrc.ProjenrcFile (experimental) A component representing the projen runtime configuration.ProjenrcJson (experimental) Sets up a project to use JSON for projenrc.ProjenrcJson.Builder (experimental) A fluent builder forProjenrcJson.ProjenrcJsonOptions.Builder A builder forProjenrcJsonOptionsProjenrcJsonOptions.Jsii$Proxy An implementation forProjenrcJsonOptionsProjenrcOptions.Builder Deprecated. ProjenrcOptions.Jsii$Proxy Deprecated. ReleasableCommits (experimental) Find commits that should be considered releasable to decide if a release is required.Renovatebot (experimental) Defines renovatebot configuration for projen project.Renovatebot.Builder (experimental) A fluent builder forRenovatebot.RenovatebotOptions.Builder A builder forRenovatebotOptionsRenovatebotOptions.Jsii$Proxy An implementation forRenovatebotOptionsResolveOptions.Builder A builder forResolveOptionsResolveOptions.Jsii$Proxy An implementation forResolveOptionsRule.Builder A builder forRuleRule.Jsii$Proxy An implementation forRuleSampleDir (experimental) Renders the given files into the directory if the directory does not exist.SampleDir.Builder (experimental) A fluent builder forSampleDir.SampleDirOptions.Builder A builder forSampleDirOptionsSampleDirOptions.Jsii$Proxy An implementation forSampleDirOptionsSampleFile (experimental) Produces a file with the given contents but only once, if the file doesn't already exist.SampleFile.Builder (experimental) A fluent builder forSampleFile.SampleFileOptions.Builder A builder forSampleFileOptionsSampleFileOptions.Jsii$Proxy An implementation forSampleFileOptionsSampleReadme (experimental) Represents a README.md sample file.SampleReadme.Builder (experimental) A fluent builder forSampleReadme.SampleReadmeProps.Builder A builder forSampleReadmePropsSampleReadmeProps.Jsii$Proxy An implementation forSampleReadmePropsSemver Deprecated. This class will be removed in upcoming releases.SnapshotOptions.Builder A builder forSnapshotOptionsSnapshotOptions.Jsii$Proxy An implementation forSnapshotOptionsSourceCode (experimental) Represents a source file.SourceCode.Builder (experimental) A fluent builder forSourceCode.SourceCodeOptions.Builder A builder forSourceCodeOptionsSourceCodeOptions.Jsii$Proxy An implementation forSourceCodeOptionsTask (experimental) A task that can be performed on the project.Task.Builder (experimental) A fluent builder forTask.TaskCommonOptions.Builder A builder forTaskCommonOptionsTaskCommonOptions.Jsii$Proxy An implementation forTaskCommonOptionsTaskOptions.Builder A builder forTaskOptionsTaskOptions.Jsii$Proxy An implementation forTaskOptionsTaskRuntime (experimental) The runtime component of the tasks engine.Tasks (experimental) Defines project tasks.TasksManifest.Builder A builder forTasksManifestTasksManifest.Jsii$Proxy An implementation forTasksManifestTaskSpec.Builder A builder forTaskSpecTaskSpec.Jsii$Proxy An implementation forTaskSpecTaskStep.Builder A builder forTaskStepTaskStep.Jsii$Proxy An implementation forTaskStepTaskStepOptions.Builder A builder forTaskStepOptionsTaskStepOptions.Jsii$Proxy An implementation forTaskStepOptionsTesting (experimental) A Testing static class with a .synth helper for getting a snapshots of construct outputs.TextFile (experimental) A text file.TextFile.Builder (experimental) A fluent builder forTextFile.TextFileOptions.Builder A builder forTextFileOptionsTextFileOptions.Jsii$Proxy An implementation forTextFileOptionsTomlFile (experimental) Represents a TOML file.TomlFile.Builder (experimental) A fluent builder forTomlFile.TomlFileOptions.Builder A builder forTomlFileOptionsTomlFileOptions.Jsii$Proxy An implementation forTomlFileOptionsVersion Version.Builder (experimental) A fluent builder forVersion.VersionOptions.Builder A builder forVersionOptionsVersionOptions.Jsii$Proxy An implementation forVersionOptionsXmlFile (experimental) Represents an XML file.XmlFile.Builder (experimental) A fluent builder forXmlFile.XmlFileOptions.Builder A builder forXmlFileOptionsXmlFileOptions.Jsii$Proxy An implementation forXmlFileOptionsYamlFile (experimental) Represents a YAML file.YamlFile.Builder (experimental) A fluent builder forYamlFile.YamlFileOptions.Builder A builder forYamlFileOptionsYamlFileOptions.Jsii$Proxy An implementation forYamlFileOptions -
Enum Summary Enum Description DependencyType (experimental) Type of dependency.DockerComposeProtocol (experimental) Network protocol for port mapping.GitpodOnOpen (experimental) What to do when a service on a port is detected.GitpodOpenIn (experimental) Configure where in the IDE the terminal should be opened.GitpodOpenMode (experimental) Configure how the terminal should be opened relative to the previous task.GitpodPortVisibility (experimental) Whether the port visibility should be private or public.InitProjectOptionHints (experimental) Choices for how to display commented out options in projenrc files.LogLevel (experimental) Logging verbosity.ProjectType Deprecated. no longer supported at the base project levelRenovatebotScheduleInterval (experimental) How often to check for new versions and raise pull requests for version updates.TestFailureBehavior