projen External Modules

As I’ve written about previously, projen supports the use of external modules. In November 2020 I wrote a blog post on publishing a private, external module to AWS CodeArtifact. I had also tested with GitHub actions but didn’t publish anything on it since it was quite a bit easier. However, with CDK Day coming up in April, I wanted to throw something together to demonstrate how to publish your private modules to GitHub packages. Below steps are just a quick highlight and overview of what you are looking to accomplish. For the full guide checkout the repository or video walthrough above.

Basic Steps

  1. Create new project with npx projen new jsii --synth false
  2. Set the package name in .projenrc.js using @scope/package-name
    • e.g. name: '@kcwinner/projen-github-demo'
  3. Change the jsiiFqn value in .projenrc.js
    • If you plan to only have one project type use jsiiFqn: 'package-name.ProjectType' with ProjectType being the external module type
    • If you plan to have multiple types you can remove the value and let it detect automatically at install time
  4. Set npm dist tag and npm registry in .projenrc.js
    • npmDistTag: 'latest'
    • npmRegistryUrl: 'https://npm.pkg.github.com'

Your .projenrc.js should look similar to this:

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

const project = new JsiiProject({
  name: '@kcwinner/projen-github-demo',
  repositoryUrl: 'https://github.com/kcwinner/projen-github-demo.git',
  author: 'Ken Winner',
  authorAddress: 'myemail@something.com',
  defaultReleaseBranch: 'main',

  devDeps: [
    'fs-extra',
    '@types/fs-extra@^8',
  ],
  deps: ['projen'],
  peerDeps: ['projen'],

  npmDistTag: 'latest', /* Tags can be used to provide an alias instead of version numbers. */
  npmRegistryUrl: 'https://npm.pkg.github.com',
});

project.synth();
  1. Run npx projen to synthesize the project
  2. Generate personal access token for the repository
    • Give it write:packages permission
    • Set it as the NPM_TOKEN repository secret

This will create your project and setup the GitHub release workflow to push to your organizations packages. You’ll need to add whatever you want created in the src/index.ts file. You can see my GitHub for an example.

Test Locally

Disclaimer - there is a small bug with testing external modules locally. You can still synthesize the first time (with npx projen new –from) but subsequent npx projen runs will fail due to the package not being installed in the scoped directory.

  1. Build with yarn build
  2. In a separate directory: npx projen new --from ~/path/to/your/dist/js/package-name@x.x.x.jsii.tgz

Installing From GitHub

  1. Generate a github personal access token
  2. Authenticate against the GitHub NPM registry using your GitHub username and personal access token:
    • npm login --scope @yourorg --registry https://npm.pkg.github.com
  3. Validate you can see the project
    • npm view @yourorg/package-name
  4. npx projen new --from @yourorg/package-name

Complete

After completing the above your project should be setup correctly! Hope to see you in the cdk.dev slack workspace or at CDK Day!

References