Nutella with Pepperoni and Mushrooms
    Have ideas to improve npm?Join in the discussion! »

    projen
    TypeScript icon, indicating that this package has built-in type declarations

    0.24.12 • Public • Published

    License

    All Contributors

    Gitpod ready-to-code Build Release

    projen

    projen logo

    Define and maintain complex project configuration through code.

    JOIN THE #TemplatesAreEvil MOVEMENT!

    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.

    Check out this talk about projen.

    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.

    Getting Started

    To create a new project, run the following command and follow the instructions:

    $ mkdir my-project
    $ cd my-project
    $ git init
    $ npx projen new PROJECT-TYPE
    🤖 Synthesizing project...
    ...

    Currently supported project types (use npx projen new without a type for a list):

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

    const project = new JsiiProject({
      // ...
      python: {
        distName: "mydist",
        module: "my_module",
      }
    });

    Run:

    npx projen

    And you'll notice that your package.json file now contains a python section in it's 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 support a start command which displays a menu of workflow activities:

    $ yarn start
    ? Scripts: (Use arrow keys)
    
      BUILD
    ❯ compile          Only compile
      watch            Watch & compile in the background
      build            Full release build (test+compile)
    
      TEST
      test             Run tests
      test:watch       Run jest in watch mode
      eslint           Runs eslint against the codebase
    
      ...

    The build command is the same command 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 for 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
    • 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

    API Reference

    See API Reference for API details.

    In addition, several projen components and project types are explained with examples in /docs (currently a work in progress!).

    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 it's 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.

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


    Elad Ben-Israel

    💻

    Christopher Rybicki

    💻

    Philip M. Gollucci

    💻

    Thorsten Hoeger

    💻

    Kenneth Winner

    💻

    Jordan Sinko

    💻

    Josh Kellendonk

    💻

    andrestone

    💻

    Cristian Pallarés

    💻

    Jonathan Goldwasser

    💻

    Matthew Bonig

    💻

    Pahud Hsieh

    💻

    Adam Elmore

    💻

    Ash

    💻

    Jacob

    💻

    Kraig Amador

    💻

    Martin Muller

    💻

    Tomasz Łakomy

    💻

    john-tipper

    💻

    Henry Sachs

    💻

    Joseph Egan

    💻

    Sebastian Korfmann

    💻

    Bart Callant

    💻

    Campion Fellin

    💻

    Grady Barrett

    💻

    Hassan Mahmud

    💻

    Hassan Mahmud

    💻

    Jake Pearson

    💻

    Jeremy Jonas

    💻

    Matt Martz

    💻

    Max Körlinge

    💻

    Neil Kuan

    💻

    Rafal Wilinski

    💻

    Romain Marcadier

    💻

    Thomas Klinger

    💻

    Tobias

    💻

    flyingImer

    💻

    Aatman

    💻

    Mark McCulloh

    💻

    Samuel Tschiedel

    💻

    Eli Polonsky

    💻

    Alexander Steppke

    💻

    Balagopal Kanattil

    💻

    Jan Brauer

    💻

    Mark Nielsen

    💻

    Mitchell Valine

    💻

    Neil Kuan

    💻

    Philipp Garbe

    💻

    Shawn MacIntyre

    💻

    Tobias

    💻

    Yigong Liu

    💻

    License

    Distributed under the Apache-2.0 license.

    Keywords

    none

    Install

    npm i projen

    DownloadsWeekly Downloads

    20,352

    Version

    0.24.12

    License

    Apache-2.0

    Unpacked Size

    11.1 MB

    Total Files

    1620

    Last publish

    Collaborators

    • avatar