projen/projen

Rapidly build modern applications with advanced configuration management

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

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 [email protected], file:/path/to/local/folder, [email protected]/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 [email protected]:projen/projen
$ cd projen
$ yarn
$ yarn watch # compile in the background

Thanks goes to these wonderful people (emoji key):

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.

projen's Issues

The Version component does not support alternate branch names for the default branch

The scripts generated by the Version component assume the main branch to be called master. There should be a way to configure this, as new projects tend to use main.

yarn build fails for default typescript-app project if eslint and jest are disabled

Steps to reproduce:

1. npx projen new typescript-app
2. Modify .projenrc.js to add eslint: false and jest: false
3. yarn run build

Feature Request: During cleanup, ignore contents of `.npmignore` as well as `.gitignore` and `node_modules/`

During cleanup, the code removes any files with the magic projen tags unless they are in .gitignore or node_modules/

This means if for any reason there are files with PROJEN_MARKER in sub directories, they get wiped out. This seems rather dangerous to do to a global namespace as well as not allowing a sub directory to have its own projen file (for e.g. doing an integration test for a CDK project, see related issue).

If NPM is going to ignore the files, then projen probably should as well.

It might be cleaner to just add a projenIgnoreFiles option and avoid this kind of dependency on npm and git.

Related change: https://github.com/eladb/projen/pull/70

code: https://github.com/eladb/projen/blob/master/src/cleanup.ts

Pattern to split Integration from Unit Tests

Should be pretty simple with a regex and/or dir split on file names.

RFC: using external project types

It's unclear what the steps and process looks like to use projen with external project types. There is a chicken&egg problem with getting the project type installed and usable.

Composable Github Workflows

For custom requirements around Github build workflows, it'd be good to have a bit more flexibility when it comes to composing workflows. Right now it's pretty much take what the NodeProject provides, or build your own from scratch.

Things I'd like to do for a JsiiProject release workflow:

• Add an explicit step before yarn bump.
• Prepend some sort guard step, or maybe even an entire job, which decides if a release is actually required or not

I'm using a prebump script to make it work somehow for the time being. However, I think it would be beneficial to allow more flexibility by exposing the individual jobs as reusable components.

React project

Reference from @harrysolovay: https://github.com/harrysolovay/react-templates-are-evil

Kotlin with Gradle support

It would be nice to be able to bootstrap projects with Kotlin support (as well as gradle and options for cdk constructs etc..)

cdk8s import location is not compatible with projen projects

cdk8s imports normally go to an imports directory under the project root. This is incompatible with the fact that projen typescript projects require that all sources go under src/. https://github.com/awslabs/cdk8s/issues/335 proposes that it will be possible to configure the output for import in cdk8s.yaml so that imports can go in the right place.

We need to make sure this is supported for cdk8s projects.

EPERM: operation not permitted, unlink 'node_modules/projen'

Affected version: 0.3.51

const {
  ConstructLibraryAws
} = require('projen');

const project = new ConstructLibraryAws({
  "authorName": "Pahud Hsieh",
  "authorEmail": "[email protected]",
  "name": "pahud-demo",
  "repository": "https://github.com/pahud/pahud-demo.git"
});

project.synth();

Got 'Permission denied' when 'yarn test'

When i use 'yarn test' and get 👇

rm: lib//index.js: Permission denied
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Should 'yarn test' add 'chmod +w' before 'rm' ?

https://github.com/eladb/projen/blob/a715a069e1d6f0ed4608a93f04ae086f567ed94b/src/typescript.ts#L208-L214

feature request(NodeProject): support for private NPM/GPR dependencies

Let's assume following config:

const { AwsCdkTypeScriptApp } = require("projen");

const project = new AwsCdkTypeScriptApp({
  cdkVersion: "1.63.0",
  name: "test",
  npmRegistry: "https://npm.pkg.github.com/myOrg",
});

project.addDevDependencies({
  "@myOrg/mySecretRepo": "0.0.1",
});

project.synth();

Despite pointing to correct npmRegistry and setting the NPM_TOKEN, yarn fails to find the correct dependency:

Command failed: yarn install --check-files
error Couldn't find package "@myOrg/mySecretRepo" on the "npm" registry.

projen:upgrade fails

A local yarn projen:upgrade looks like this:

Which fails in CI with this error:

That's using TypeScriptProject

RFC: projen new FOO

$ mkdir my-first-jsii-library
$ cd my-first-jsii-library
$ npx projen init jsii
.projenrc.js generated from the "jsii" template. 
go edit it, nothing there is what you want (until someone adds interactive mode (#552))
$ edit ...
$ npx projen // or "pj" for the die hard
$ ls
<all of it, ready to rock>

RFC .projenrc.ts support

For more complex projects, specially with the monorepo support, wouldn't it be interesting to:

npx projen init typescript --types

Then generate a .projenrc.ts file instead of the .js and incorporate a check on the cli to compile on the fly if .ts file is there?

Cannot link local projen fork to new package

I was interested in adding a new project type to projen, but I've seemed to hit a roadblock. My plan was to use yarn link to create a symlink between a local version of projen and a test package in which I'm going to use it. However, when I try this and run yarn projen to actually synthesize things (in the test package), projen automatically deletes the symlink and runs yarn install to replace it with the latest version of projen, overriding the symlink. It seems to be caused by https://github.com/eladb/projen/blob/8aa5e311e298acc11a5df833fcc838bd70401a01/src/node-project.ts#L999

I was able to work around this temporarily commenting out some of the symlinking lines, but is there a better way to test things? I imagine there's some kind of escape hatch in place, but I couldn't seem to figure it out.

peerDependencyOptions not passed

peerDependencyOptions is not passed in this statement

https://github.com/eladb/projen/blob/64006b966e44500868c61f547793fbddb464921b/src/node-project.ts#L411

Feature request: Support custom licenses

Problem

It seems that currently Projen supports following licenses:

• Apache-2.0
• MIT
• MPL-2.0

… but for internally distributed (within a company) constructs / projects one should be able to set the license to something else (proprietary license).

Proposed solution

One idea could be allowing to specify the license as string:

project.license = `COWBOY LICENSE
This is a custom proprietary license. 
Only people wearing cowboy hats can use this project. 
Beware of our scary legal team.`;

Proposed Workaround

For a workaround one could use in .projenrc.js:

project.gitignore.exclude('LICENSE');

… but that doesn't work since Projen applies !/LICENSE after that:

So at least having some way of "forcing" manual project.gitignore.exclude operations to be appended at the end would solve the issue.

Semver should accept less strict version constraints

When attempting to declare a dependency like this Semver.caret('0.0') an invalid Semver error is thrown. According to this it should be possible.

Out of curiosity, what was the motivation to roll your own semver implementation rather than using something like https://www.npmjs.com/package/semver ?

NodeProjectCommonOptions.npmIgnore is not honored

NodeProjectCommonOptions.npmIgnore is not honored and always generated.

const { NodeProject } = require("projen");

const project = new NodeProject({
  name: "projen-test",
  npmIgnore: false,
});

project.synth();

$ rm --force .npmignore

$ yarn projen
<snip>

$ cat .npmignore 
# ~~ Generated by projen. To modify, edit .projenrc.js and run "npx projen".
/.projenrc.js
/.versionrc.json
/.mergify.yml

NodeProjectCommonOptions.npmIgnore and NodeProjectCommonOptions.npmignore are somewhat tricky names...
https://github.com/eladb/projen/blob/2288f2bff06e601243d4e7ffdae92d4e286123f5/src/node-project.ts#L522-L524

It seems like this line should be NodeProjectCommonOptions.npmIgnore.

Permissions issue on windows trying to symlink

Hi @eladb

I just tried this out on my windows machine, and ran into an issue with not running my command line as administrator. I was just using the vs code command line interface (but not running as admin)

When I ran as admin it works

EPERM: operation not permitted, symlink 'C:\Users\jake\AppData\Roaming\npm-cache\_npx\11080\node_modules\projen' -> 'node_modules\projen'

Templates vs Project Classes

Hey there!

With the latest commits, we now have 1:1 relation between classes and initialization options. But, in fact, one class could have many templates to serve many different purposes.

So, the question is: should we have a templating system or just go creating project classes to support common use cases? None of those and stick with current state (single template per project type) ?

rfc: migrating existing projects to projen

Idea

Hi Elad!

What about a migrator/generator that helps port existing projects to projen?

Context

I've been porting a CDK construct that I just started over to projen, and due to our restrictive CI environment, I ended up shutting a lot of features off. It would be cool to have a generator that spits out at least a rough .projenrc.js to get you started, based on existing configs and known patterns.

I don't feel qualified yet to contribute to this effort, but am looking forward to digging into the code in the future.

Love this idea by the way. It's been a point of frustration for me for a long time and I always thought something like this would be really useful. I never consider it on this scale though. Very cool!

Disabling projenUpgrade should delete workflow

When setting projenUpgrade: false in an existing project, the following things are changed:

• npm script
• gitignore

However, the .github/workflows/projenupgrade.yml file isn't removed. When removing this file manually, it won't be synthesized as expected.

Using 3rd Party Projects

I'm wondering what the best way is for using a project generator class which is not part of this project. There might be project generators which only make sense to a small or private audience. Is that even a case which will be supported?

`tsconfig.json` in jsii projects

In jsii projects, tsconfig.json is normally created by the compiler (jsii) during compilation and therefore is currently not managed by projen and currently ignored in .gitingore. This means that when a fresh jsii project is checked out, there is no tsconfig.json until the project is compiled, which is not required for other typescript projects (since jest is configured to compile the sources).

We need to:

1. Create an initial tsconfig.json (read-write, with the jsii marker, so jsii can override).
2. Make sure it's checked into the repo.

The `types` path in `package.json` is missing a `/`

After seeing a talk from @eladb during the CDK Day I created a test project to see projen in action. And during some exploring I noticed the types path in the package.json file is missing a / between the lib dir and the entrypoint file name when using the TypeScriptProject template.

Steps to reproduce

Initialize a project with the following .projenrc.js:

const { TypeScriptProject } = require("projen");

const project = new TypeScriptProject({
  name: "test-project"
});

project.synth();

Version

projen: 0.3.77

Possible solution

I think adding the / between ${path.dirname(this.entrypoint)} and ${path.basename(this.entrypoint, '.js')} seems like it enough to make this work.
By modifying the compiled output, I tested this fix and it seems to work as expected. There do not seem to be any tests yet for the TypeScriptPoject, so not really sure how to continue there. I can already create a PR for the changes: https://github.com/bartcallant/projen/commit/39e9da0aeff7269809190d3b136bef6fd653ecd1

Start menu entries not removed in AWS CDK app

The AWS CDK app removes some scripts from package.json but these scripts still show up un the generated start menu configuration.

Generate `src/index.ts` and `test/index.test.ts` for typescript/jsii projects

Feature request: Use NPM instead of Yarn

Yarn is not playing well with private dependencies from Github Package Registry. It would be nice to have an option to choose between npm and yarn, like in create-react-app: https://create-react-app.dev/docs/getting-started/#selecting-a-package-manager

feature request : customizable projen upgrade schedule

At this moment, projen upgrades itself and opens PRs on a daily basis, which is a little bit annoying if the downstream repos are not going to stick to the latest projen version.

Would be great to have a customizable schedule expression.

https://github.com/eladb/projen/blob/9cea082317765219efc43c9f09e3356024c833d9/src/projen-upgrade.ts#L45

RFC: gitlab CI support

I've created this as an RFC, as I am not sure if these types of extensions are considered. It would be nice if Github as the default workflow was configurable so you could have different providers such as Gitlab.

Currently the NodeBuildWorkflow has tight coupling with the GithubWorkflow class as it extends it on node-project. If the relationship was different gitlab CI support could be added.

Gitlab CI places a file called .gitlab-ci.yml in the root of a project, a little different to Githubs ./workflows structure. Sample gitlab CI files are here.
https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Bash.gitlab-ci.yml

I've tried working on this myself, but wasn't sure how to proceed because of the class extension.

Enforcing .projenrc as SSOT

Since we already decided to enforce it via anti-tamper on workflows, how about making projen files read-only?

support 'keywords' ?

Please add 'keywords' support so I can add 'cdk' in the keywords :-)

"Anti-tamper check after build"

Use version 0.3.13 but still can't pass this check 😢

https://github.com/jialechan/cdk-elasticache-monitor/runs/922973170?check_suite_focus=true

Feature Request: Create CDK integration test apps for a CDK construct

I am creating a construct for exporting/importing VPCs since CDK's support for that is missing/undocumented.

I need to integration test the construct (i.e. an actual deployment that tests that network traffic passes). (I've already encountered misconfiguration issues that prove I need this kind of test, as much or more than actual unit tests). This means I have several options, all with issues. I also want to use AWS's CI Pipeline to automate deployment (and maybe running) of the integration tests, though I'm open to other solutions.

My options appear to be:

1. Create an awscdk-app-ts project. However this is different than a awscdk-construct project so I won't be able to publish a construct from this type of project.

2. Create an awscdk-construct (which I did already) project but then I cannot create apps using this project type

3. Create an awscdk-construct in the main directory, add a subdirectory called integration-tests, and then put an awscdk-app-ts in that directory. I'm uncertain how the automated Github and NPM integrations will interact with each other.

4. Create a separate repo for the awscdk-app-ts to test the other repo's awscdk-construct. Not sure I like this, it means I'll be releasing untested NPM modules to npmjs.org.

5. Using yarn pack, copy the package over to a second repository that is awscdk-app-ts project. then untar the resulting tarred package in the second repository, and run the tests. The problem with this method is yet a third repository will be needed to automate this process since it is manual. Or make a bad assumption about the local paths of the workspaces (e.g. hard code ..\<cdklib_repo>. 3 repos for automated integration tests seems excessively tedious.

Any ideas on the best approach here?

Feature request: expose TypeScript project APIs for choosing eslint target directories

Right now EslintOptions is pretty bare bones, although it does have a dirs field:
https://github.com/eladb/projen/blob/e39f2b138d9591b4ece2ffd4fa6d0960a14f9709/src/eslint.ts#L6-L13

But currently the dirs values get hardcoded in TypeScriptProject, so anything other project types that extend TypeScriptProject must use these two directories which can't be changed. Moreover, if you create a new typescript-app project, disable jest, and remove the tests directory, eslint will complain to you because it is trying to lint the testdir directory, but finds nothing.

https://github.com/eladb/projen/blob/e39f2b138d9591b4ece2ffd4fa6d0960a14f9709/src/typescript.ts#L269-L274

We should add some APIs / options to the TypeScript class to allow this to be customized, and to handle the case when users do not want to have tests in their project (or if they want to just have tests intermingled in their src directory).

Feature Request: Let Mergify merge ProjenUpgrade PRs once build passes

ProjenUpgrade PRs now require manually merge and is a little bit annoying.

Would be great if we allow Mergify to merge it for us just like how it works with dependabot PRs.

more discussion here: https://twitter.com/pahudnet/status/1310870742746034176

Proposed Solution:

We probably can add a rule here:
https://github.com/eladb/projen/blob/ccb0aa946d9be7c328676396b58c9cb0bba1aebb/src/node-project.ts#L632-L658

And I was wondering if we should provide an opt-out option and where would be the best place to hold this option.

RFC: AWS Lambda function project

What about a new project type for Lambda functions. It would be a TypeScript project but with type definitions, middleware etc as dependencies and some opinionated defaults for Lambda functions.

It could even generate the handler code and then hand over to the business logic implementation.

It would be optimized to be used with the NodeJsFunction construct of the AWS CDK.

We can collect ideas here and then draft a PR for this.

Feature request: Support for private / non-default repositories

Problem

Currently it seems that Projen only supports the public repositories (npmjs.com, pypi.org, maven central).

This is controlled by jsii-project.ts:

• for NPM in lines 299-300:

  env: {
     NPM_TOKEN: '${{ secrets.NPM_TOKEN }}',
     NPM_DIST_TAG: this.npmDistTag,
  },

• for Python in lines 400-401:

  env: {
     TWINE_USERNAME: '${{ secrets.TWINE_USERNAME }}',
     TWINE_PASSWORD: '${{ secrets.TWINE_PASSWORD }}',
  },

Proposed solution

Since jsii-release already supports setting NPM_REGISTRY and TWINE_REPOSITORY_URL this probably could be managed by allowing one to set values in .projenrc.js:

• options.nodejs.defaultRegistry = false to enable NPM_REGISTRY: '${{ secrets.NPM_REGISTRY }}',
• options.python.defaultRegistry = false to enable TWINE_REPOSITORY_URL: '${{ secrets.TWINE_REPOSITORY_URL }}',

Related AWS CodeArtifact issues

Then there's the issue of AWS CodeArtifact, which does not provide permanent token, but a temporary token which has a maximum duration of 12 hours (43200 seconds). It would require having some extra step in the Github workflow which might not be that easy to support with projen 🤷‍♂️

RFC: Lerna Project

Hey!

How about projen for bootstrapping and maintaining Lernyarn monorepos?

import { LernaProject, TypeScriptLibraryProject, NodeProject } from '../lib';

const lernaProject = new LernaProject({
  name: 'my-monorepo-project',
  packages: [
    {
      name: 'ddb-connector',
      location: 'packages/@services',
      project: new TypeScriptLibraryProject({ name: 'ddb-connector', description: 'DynamoDB API / Connector' })
    },
    {
      name: 'service-portal',
      location: 'packages/@services',
      project: new NodeProject({ name: 'service-portal-api', description: 'Service Portal' })
    }],
  workSpaces: {
    packages: [
      "packages/@web/*",
      "packages/@rn/*",
      "packages/@iac/*",
      "packages/@services/*",
    ],
    nohoist: [],
  }
});

lernaProject.addPackage({
  name: 'geo',
  location: 'packages/@services',
  project: new TypeScriptLibraryProject({ name: 'geocoding-service', description: 'Geocoding Service' })
});
lernaProject.addBootstrappedPackage({
  name: 'cloud-infra',
  location: 'packages/@iac',
  beforeCommand: 'mkdir cloud && cd cloud',
  npxCommand: 'npx cdk init --language typescript',
});
lernaProject.addBootstrappedPackage({
  name: 'core',
  location: 'packages/@web',
  npxCommand: 'npx create-react-app web-frontend',
});

lernaProject.synth();

Specifying 'publishConfig' in package.json

Use case: Building AWS CDK JSII construct and publishing to company internal Artifactory repository.

It would be good to have a possibility to specify this in package.json:

  "publishConfig": {
    "registry": "https://company.com/api/npm/company-local/"
  },

Feature Request: Initialize .projenrc.js with commented out project options

Quality of life / convenience feature.

The idea is when .projenrc.js gets generated, it should include a list of the available options out of the box, similar to how they are provided when you run tsc --init in a new repository, which produces:

{
  "compilerOptions": {
    /* Visit https://aka.ms/tsconfig.json to read more about this file */

    /* Basic Options */
    // "incremental": true,                   /* Enable incremental compilation */
    "target": "es5",                          /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */
    "module": "commonjs",                     /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */
    // "lib": [],                             /* Specify library files to be included in the compilation. */
    // "allowJs": true,                       /* Allow javascript files to be compiled. */
    ...

I see that jsii is being used to generate API docs right now -- maybe there's some way to hook into that or leverage it to perform this automatically?

Why Semver.pinned() in addPeerDependencies()?

Hello Eladb:

I would like to asking you why 'addPeerDependencies()' use 'Semver.pinned()' but not just like 'addDevDependencies()' use 'v.spec' when pinnedDevDependency eq ture? Is there something diff between devDependencies and peerDependencies?

Thanks a lot!

https://github.com/eladb/projen/blob/a715a069e1d6f0ed4608a93f04ae086f567ed94b/src/node-project.ts#L602-L617

Permission denied on package.json

I'm adding projen to my CDK construct library using the ConstructLibraryAws project. As my construct includes a NodeJsFunction, it fails during tests as it can't access the package.json file. If I change the permissions it works until they are resetted by npx projen.

EACCES: permission denied, open '.../package.json'

Inquiry: Creating Additional Files in Repo

This is just a question I have after searching the docs.

Is there a common way to create additional files within the project, similar to JsonFile? Is this something that should be manually created when needed?

An example of this would be a buildspec.yml for CodeBuild. Personally, I've created a class that does this for me but I was just curious if this was a native feature.

class ContentFile extends FileBase {
  constructor(project, path, options) {
    super(project, path, options);
    this.options = options;
  }

  synthesizeContent() {
    return this.options.content;
  }
}

new ContentFile(project, ".prettierignore", {
  content: `package.json
API.md
`,
});

scheduled ProjenUpgrade failed

Hi @eladb

Looks like the scheduled ProjenUpgrade will need to update the yarn.lock but --frozen-lockfile was passed.

https://github.com/pahud/cdk-spot-one/runs/987656093?check_suite_focus=true

Any comments on this ?

Anti-tamper check failed with the 'start' script

I am having the Anti-tamper check when I commit the package.json and .projenrc.js together to my aws cdk construct lib repo:

https://github.com/aws-samples/cdk-serverless-lamp/runs/1039788734?check_suite_focus=true

Affected version: [email protected]

It was working in 0.3.47.

Hi @eladb

Any comments? Did I miss anything?

"EEXIST: file already exist" after first "npx projen"

Following the example in the readme I get the following error:

$ git init
Leeres Git-Repository in /Users/sebastian/projects/cdk/foobar/.git/ initialisiert

$ npx projen new jsii \
  --name my-module \
  --author-name "Sebastian Korfmann" \
  --author-email "[email protected]" \
  --repository "https://github.com/skorfmann/my-module.git"
Project config created for "JsiiProject" project in .projenrc.js.
Now run `npx projen && yarn install` (or `pj` if you are one of the cool kids with an alias).

$ npx projen && yarn install
EEXIST: file already exists, symlink '/Users/sebastian/.npm/_npx/77646/lib/node_modules/projen' -> 'node_modules/projen'

When removing node_modules I can run it once again

npx projen --version
0.3.5

And then it starts to fail again.

• Node Version Manager (v0.35.3)
• Node version: v13.14.0

Feature request: allow multiple source directories

Related to #182.

A lot of code repositories just use a single directory for putting the main code in, typically src. But other repositories and templates/frameworks may suggest other organization of files at the root level. e.g. https://github.com/vercel/next.js/tree/canary/examples/with-typescript

We should enable projen users to specify multiple source directories in some fashion. As a result, the directories would be automatically added to all related config files that have some notion of "entry" or "target" directories, such as tsconfig.json, jest.config.js, eslintrc.json and so on.

We can also enable multiple source directories for each of these components individually - but I think the global option is worth evaluating. Here is how it would look like on an individual component basis:

let srcDirs = ['components', 'pages', 'utils'];

const project = new TypeScriptProject({
  name: "my-app",
  eslintDirs: srcDirs,
  tscDirs: srcDirs,
  ...
});

This is not something I have any immediate need for, but I thought it's worth submitting this for tracking purposes / to gauge interest. 🙂