jsii-pacmak: jsii Package Maker

Common errors

• Error: Node.js version 12.x.y is not supported. Please use >= 14.17.0.

  cause Attempting to run `jsii-pacmak` with an unsupported Node.js version.
  fix Upgrade your Node.js environment to version 14.17.0 or newer using `nvm install 18 && nvm use 18` or similar tools.

• `jsii-pacmak` command not found

  cause The `jsii-pacmak` executable is not in your system's PATH or `npx` cannot locate it.
  fix Ensure `jsii-pacmak` is installed (`npm install jsii-pacmak`) and either run it with `npx jsii-pacmak` from your project root or add `$(npm bin)` to your PATH.

• Peer dependency 'jsii-rosetta' is missing or incompatible.

  cause The `jsii-rosetta` package, a required peer dependency, is not installed or its version does not satisfy `jsii-pacmak`'s requirements.
  fix Install the correct version of `jsii-rosetta`: `npm install jsii-rosetta@^5.9.0` (adjust version as needed per `jsii-pacmak`'s `package.json`).

• error TS2307: Cannot find module 'my-jsii-lib' or its corresponding type declarations.

  cause The TypeScript compilation of your jsii module failed because required modules are not found or paths are incorrect.
  fix Verify your `tsconfig.json` paths, `include` array, and ensure all dependencies are installed. Run `npx jsii` separately to compile the TypeScript code before running `jsii-pacmak`.

Warnings

• breaking jsii-pacmak requires Node.js version 14.17.0 or newer. Running with older Node.js versions will result in an error or unexpected behavior.
  Fix: Upgrade your Node.js installation to version 14.17.0 or higher. Use a Node.js version manager like `nvm` to easily switch versions (`nvm install 18` then `nvm use 18`).
• gotcha The `jsii-rosetta` peer dependency must be installed and meet the specified version requirements (currently `>=5.9.0`). Failure to do so can lead to issues with documentation generation or type translation, even if `jsii-pacmak` itself runs.
  Fix: Ensure `jsii-rosetta` is installed in your project: `npm install jsii-rosetta` or `yarn add jsii-rosetta`. Check your `package.json` for compatible versions.
• breaking When targeting Go, `jsii-pacmak` previously added `GOSUMDB=off` to the Go target environment. This has been removed in v1.127.0, which might affect build environments relying on this behavior, particularly those behind firewalls or in air-gapped networks.
  Fix: If your Go builds now fail due to sumdb issues, you may need to explicitly set `GOSUMDB=off` or configure `GOPRIVATE` and `GONOPROXY` environment variables in your build pipeline when invoking Go tools.
• gotcha Using older Maven versions or specific configurations can lead to 'dependency ranges make Maven download too many files' issues, causing slow builds or network strain. This was addressed in v1.122.0 and v1.123.0 for `jsii-pacmak` and `java-runtime` respectively.
  Fix: Ensure you are using `jsii-pacmak` version 1.123.0 or newer. If issues persist, verify your Maven settings and consider adjusting dependency resolution strategies or using fixed versions where possible.

Install

• npm install jsii-pacmak npm
• yarn add jsii-pacmak yarn
• pnpm add jsii-pacmak pnpm

Imports

• main

  import { main } from 'jsii-pacmak';
  // or
  const { main } = require('jsii-pacmak');

  While primarily a CLI tool, the 'main' function is the programmatic entry point for direct integration, accepting an array of arguments similar to process.argv.
• cli
  wrong:

  import { cli } from 'jsii-pacmak'

  correct:

  npx jsii-pacmak [options]

  jsii-pacmak is most commonly invoked as a command-line interface tool via `npx` or directly from `node_modules/.bin/jsii-pacmak`. There is no 'cli' symbol to import.

Quickstart

This quickstart demonstrates how to set up a basic `jsii` project, define a simple TypeScript class, and then use `jsii-pacmak` to generate language-specific packages (Java and Python in this example) ready for publishing.

mkdir my-jsii-lib
cd my-jsii-lib
npm init -y
npm install jsii
npm install -D typescript @types/node

cat > tsconfig.json <<EOF
{
  "compilerOptions": {
    "alwaysStrict": true,
    "declaration": true,
    "experimentalDecorators": true,
    "lib": ["es2018"],
    "module": "commonjs",
    "noEmitOnError": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "resolveJsonModule": true,
    "strict": true,
    "strictBindCallApply": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,
    "stripInternal": true,
    "target": "es2018",
    "outDir": "lib"
  },
  "include": ["src/**/*.ts"]
}
EOF

mkdir src
cat > src/index.ts <<EOF
export interface MyProps {
  readonly message: string;
}

export class Greeter {
  public readonly greeting: string;

  constructor(props: MyProps) {
    this.greeting = `Hello, ${props.message} from jsii!`;
  }

  public sayHello(): string {
    return this.greeting;
  }
}
EOF

# Configure package.json for jsii targets
node -e "const pkg = require('./package.json'); pkg.jsii = { 'outdir': 'dist', 'targets': { 'java': { 'package': 'com.myorg.mylib', 'maven': { 'groupId': 'com.myorg', 'artifactId': 'mylib' } }, 'python': { 'distName': 'my-jsii-lib', 'module': 'my_jsii_lib' } } }; require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2));"

npx jsii
npx jsii-pacmak