@nikovirtala/projen-constructs 0.5.1 → 0.5.3

package/.jsii

@@ -4178,7 +4178,7 @@
       }
     }
   },
-  "description": "Projen project types with standard configuration",
+  "description": "Opinionated projen project types that scaffold TypeScript, JSII and AWS CDK repositories with one shared config.",
   "docs": {
     "stability": "stable"
   },
@@ -4196,7 +4196,7 @@
   },
   "name": "@nikovirtala/projen-constructs",
   "readme": {
-    "markdown": "# @nikovirtala/projen-constructs\n\nProjen project types with standard configuration for consistent project setup across all repositories.\n\n## Installation\n\n```bash\npnpm add -D @nikovirtala/projen-constructs projen constructs\n```\n\nRequires pnpm 12 and `projen` ^0.104.23. `@mrgrain/cdk-esbuild` and `constructs` are peer\ndependencies as well.\n\nTo create a project from scratch:\n\n```bash\npnpm dlx projen new --from @nikovirtala/projen-constructs aws_cdk_construct_library\n```\n\n## Features\n\n- **Standard Configuration**: Opinionated defaults for author, release branch, package manager, Node.js, TypeScript, and tooling\n- **Automatic Project Type Discovery**: Generates the `ProjectType` enum from Projen's JSII manifest (19 project types)\n- **Component System**: Reusable components (Vitest, TypeDoc, Mise, Homebrew, Colima, LocalStack, Lambda bundling)\n- **Code Generation**: `ProjectGenerator` creates project classes with standard configuration\n- **ES Modules**: TypeScript and CDK App projects use ES modules (JSII uses CommonJS)\n- **Code Quality**: Biome for formatting and linting\n- **Testing**: Vitest with coverage\n- **Auto-merge**: Enabled with auto-approve\n- **VSCode**: Recommended extensions and settings\n- **mise**: Node version management\n\n## Standard Configuration\n\n- **Author**: Niko Virtala (niko.virtala@hey.com)\n- **Default Release Branch**: main\n- **Package Manager**: pnpm 12.16.1\n- **Node Version**: 26.13.0\n- **TypeScript**: 6.0.3\n- **CDK Version**: 2.263.0 (for CDK projects)\n- **JSII Version**: ~6.0.3 (for JSII projects)\n\nThe AWS CDK, Node.js and TypeScript versions live in `src/versions.json` and are refreshed by the\n`update-versions` task, which the dependency upgrade workflow runs.\n\n### pnpm\n\npnpm reads its settings from `pnpm-workspace.yaml`, not `.npmrc`, since pnpm 11. Generated projects\nget:\n\n| Setting                | Value             | Reason                                                                                                       |\n| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |\n| `nodeLinker`           | `hoisted`         | jsii tooling resolves dependencies from a flat `node_modules`                                                |\n| `allowBuilds`          | `esbuild: true`   | esbuild links its platform binary in a postinstall script, and pnpm 11 fails an install with ignored builds   |\n| `verifyDepsBeforeRun`  | `false`           | projen resolves the task `PATH` with `$(pnpm -c exec ...)`, which otherwise re-enters `pnpm install` and deadlocks |\n| `minimumReleaseAge`    | `0`              | the pnpm 11 default of 1440 minutes makes pnpm write `minimumReleaseAgeExclude` entries into this generated file |\n\n### TypeScript configuration\n\nProjen renders three configs, and none of them should be edited directly:\n\n- `tsconfig.json` compiles `src` to `lib`. For JSII projects, jsii validates it against its `strict`\n  rule set, so it only carries compiler options jsii accepts.\n- `test/tsconfig.json` extends it and is type-check only. This is the config Vitest type checking and\n  the editor use, and the one `tsconfigDev` points at.\n- `projenrc/tsconfig.json` covers `.projenrc.ts`.\n\n### Native TypeScript\n\nTypeScript and AWS CDK app projects run TypeScript with Node.js's built-in\n[type stripping](https://nodejs.org/api/typescript.html#type-stripping) instead of `tsx` or\n`ts-node`: the default task is `node .projenrc.ts`, and the cdk.json `app` is `node src/main.ts`.\nTheir `tsconfig.json` sets `erasableSyntaxOnly` and `verbatimModuleSyntax`, so `tsc` reports code\nthat Node.js can't run before Node.js does.\n\nCode in these projects must therefore:\n\n- only use syntax that can be stripped: no `enum`s (use an `as const` object), no namespaces with\n  values, and no constructor parameter properties\n- mark type-only imports with `type` (Biome's `useImportType` fixes these)\n- import relative files with their `.ts` extension, and never import a directory\n- use Node.js [subpath imports](https://nodejs.org/api/packages.html#subpath-imports)\n  (`#stacks` in `package.json` `imports`) instead of tsconfig `paths`, which Node.js doesn't read\n- import packages without an `exports` map either from the package root or with an explicit file,\n  e.g. `projen/lib/component.js` rather than `projen/lib/component`\n\nLambda handlers bundled by esbuild and tests run by Vitest aren't run by Node.js directly, but the\nsame compiler options apply to them.\n\nJSII and AWS CDK construct library projects keep using `tsx`, because jsii compiles to CommonJS, and\ntheir `.projenrc.ts` often imports their own `src`.\n\nWhen you start a new project by hand, make sure `package.json` has `\"type\": \"module\"` before the\nfirst `node .projenrc.ts`: `npm init` writes `\"type\": \"commonjs\"`, which makes Node.js reject the\n`import` statements in `.projenrc.ts`.\n\n## Customization\n\nOverride any option by passing it to the constructor:\n\n```typescript\nimport { JsiiProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new JsiiProject({\n  name: \"my-project\",\n  repositoryUrl: \"https://github.com/nikovirtala/my-project.git\",\n  minNodeVersion: \"26.0.0\",\n  author: \"Custom Author\",\n  authorAddress: \"custom@example.com\",\n  mise: false,\n  vitest: false,\n  tsconfig: {\n    compilerOptions: {\n      noUnusedLocals: false,\n    },\n  },\n  biomeOptions: {\n    biomeConfig: {\n      formatter: {\n        lineWidth: 100,\n      },\n    },\n  },\n});\n```\n\nEvery component is exposed as an enable flag (`mise`, `vitest`, ...) plus an options property\n(`miseOptions`, `vitestOptions`, ...).\n\n## Usage\n\n### Projects\n\n#### AWS CDK Construct Library Project\n\n```typescript\nimport { AwsCdkConstructLibraryProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new AwsCdkConstructLibraryProject({\n  name: \"my-cdk-construct\",\n  repositoryUrl: \"https://github.com/nikovirtala/my-cdk-construct.git\",\n});\n\nproject.synth();\n```\n\n#### AWS CDK TypeScript App Project\n\n```typescript\nimport { AwsCdkTypeScriptAppProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new AwsCdkTypeScriptAppProject({\n  name: \"my-cdk-app\",\n  repository: \"https://github.com/nikovirtala/my-cdk-app.git\",\n});\n\nproject.synth();\n```\n\n#### JSII Project\n\n```typescript\nimport { JsiiProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new JsiiProject({\n  name: \"my-jsii-project\",\n  repositoryUrl: \"https://github.com/nikovirtala/my-jsii-project.git\",\n});\n\nproject.synth();\n```\n\n#### TypeScript Project\n\n```typescript\nimport { TypeScriptProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new TypeScriptProject({\n  name: \"my-typescript-project\",\n  repository: \"https://github.com/nikovirtala/my-typescript-project.git\",\n});\n\nproject.synth();\n```\n\n### Components\n\nThe package includes reusable components for common development tasks:\n\n#### Vitest\n\n[Vitest](https://vitest.dev) testing framework component.\n\n```typescript\nimport { Vitest, CoverageProvider, CoverageReporter } from \"@nikovirtala/projen-constructs\";\n\nnew Vitest(project, {\n  vitestVersion: \"^5\",\n  config: {\n    coverageProvider: CoverageProvider.V8,\n    coverageReporters: [CoverageReporter.TEXT, CoverageReporter.LCOV],\n  },\n});\n```\n\nType checking runs against the project's development tsconfig (`test/tsconfig.json`) unless\n`config.typecheckTsconfig` says otherwise.\n\nFor Vitest settings that `config` doesn't cover, use `extraTestConfig` (merged into `test`) and\n`extraConfig` (top-level options next to `test`):\n\n```typescript\nimport { Vitest } from \"@nikovirtala/projen-constructs\";\n\nnew Vitest(project, {\n  extraTestConfig: {\n    setupFiles: [\"test/setup.ts\"],\n  },\n  extraConfig: {\n    resolve: { alias: { \"@\": \"/src\" } },\n  },\n});\n```\n\n`extraTestConfig` is deep-merged over the generated `test` options: objects merge, and other values\n(including arrays) replace the generated value. Both options are rendered as JSON, so their values\ncan't contain functions or regular expressions, which rules out plugins.\n\n#### TypeDoc\n\n[TypeDoc](https://typedoc.org) documentation generation component.\n\n```typescript\nimport { TypeDoc, EntryPointStrategy } from \"@nikovirtala/projen-constructs\";\n\nnew TypeDoc(project, {\n  version: \"^0.28\",\n  typeDocConfig: {\n    entryPointStrategy: EntryPointStrategy.EXPAND,\n    out: \"docs/api\",\n    exclude: [\"**/*.test.ts\"],\n  },\n});\n```\n\n#### Mise\n\n[Mise](https://mise.jdx.dev) dev tools/runtimes management component.\n\n```typescript\nimport { Mise } from \"@nikovirtala/projen-constructs\";\n\nnew Mise(project, {\n  nodeVersion: \"26.13.0\",\n});\n```\n\n#### Homebrew\n\n[Homebrew](https://brew.sh) package management component. Writes a `Brewfile` and adds an\n`install:homebrew` task that bootstraps Homebrew and runs `brew bundle`.\n\n```typescript\nimport { Homebrew } from \"@nikovirtala/projen-constructs\";\n\nconst homebrew = new Homebrew(project, {\n  packages: [\"jq\", \"yq\"],\n});\n\nhomebrew.addPackage(\"gh\");\n```\n\nA fully qualified formula (`user/repository/formula`) also adds a `tap` entry. Since Homebrew 6,\nformulae from non-official taps only load when trusted, so they're written with `trusted: true`.\nThat trusts only the formula, not the rest of its tap.\n\n#### Colima\n\n[Colima](https://github.com/abiosoft/colima) container runtime component. Alternative for Docker.\n\n```typescript\nimport { Colima } from \"@nikovirtala/projen-constructs\";\n\nnew Colima(project);\n```\n\n#### LocalStack\n\n[LocalStack](https://www.localstack.cloud) AWS emulation component.\n\n```typescript\nimport { LocalStack } from \"@nikovirtala/projen-constructs\";\n\nnew LocalStack(project, {\n  services: [\"s3\", \"lambda\", \"dynamodb\"],\n  port: 4566,\n  debug: true,\n});\n```\n\n#### LambdaFunctionConstructGenerator\n\nGenerates AWS CDK Lambda Function constructs and bundles their code.\n\n```typescript\nimport { LambdaFunctionConstructGenerator } from \"@nikovirtala/projen-constructs\";\n\nnew LambdaFunctionConstructGenerator(project, {\n  sourceDir: \"src/handlers\",\n  outputDir: \"src/constructs/lambda\",\n  filePattern: \"*.lambda.ts\",\n  esbuildOptions: {\n    minify: true,\n    sourcemap: true,\n  },\n});\n```\n\n#### Bundler\n\nLow-level bundling utilities for Lambda functions.\n\n```typescript\nimport {\n  Bundler,\n  LambdaFunctionCodeBundle,\n} from \"@nikovirtala/projen-constructs\";\n\nconst bundler = new Bundler(project, {\n  assetsDir: \"assets\",\n  esbuildVersion: \"^0.25\",\n});\n\nnew LambdaFunctionCodeBundle(project, {\n  entrypoint: \"src/my-function.lambda.ts\",\n  extension: \".lambda.ts\",\n});\n```\n\n#### ProjectGenerator\n\nGenerates TypeScript project classes with standard configuration.\n\n```typescript\nimport { ProjectGenerator, ProjectType, Mise, Vitest } from \"@nikovirtala/projen-constructs\";\n\nnew ProjectGenerator(project, {\n  name: \"TypeScriptProject\",\n  projectType: ProjectType.TYPE_SCRIPT_PROJECT,\n  filePath: \"./src/projects/typescript.generated.ts\",\n  components: [\n    { componentClass: Mise },\n    { componentClass: Vitest }, // Auto-detects VitestOptions from JSII manifest\n  ],\n});\n```\n\nFeatures:\n\n- Automatically generates the `ProjectType` enum from Projen's JSII manifest\n- Auto-detects component options types from JSII manifests\n- Strips Projen's `@pjnew` annotation from `packageManager`, which `projen new` would otherwise\n  render into a generated `.projenrc.ts` as the package manager that ran the command\n- Validates paths to prevent directory traversal attacks\n- Structured error handling with custom error classes\n\n## Migrating from the standalone packages\n\nThe components used to be published as separate packages. Those packages are deprecated and won't\nget new features or fixes. Every class, interface, enum and function they exported is exported from\n`@nikovirtala/projen-constructs` under the same name, except `AwsCdkApp` (see below).\n\n| Deprecated package | Replacement in `@nikovirtala/projen-constructs` |\n| --- | --- |\n| `@nikovirtala/projen-vitest` | `Vitest`, `VitestOptions`, `VitestConfigOptions`, `Environment`, `Pool`, `CoverageProvider`, `CoverageReporter` |\n| `@nikovirtala/projen-typedoc` | `TypeDoc`, `TypeDocOptions`, `TypeDocConfiguration` and its enums |\n| `@nikovirtala/projen-homebrew` | `Homebrew`, `HomebrewOptions` |\n| `@nikovirtala/projen-colima` | `Colima` |\n| `@nikovirtala/projen-localstack` | `LocalStack`, `LocalStackOptions` |\n| `@nikovirtala/projen-bundle-lambda-function-code` | `Bundler`, `LambdaFunctionCodeBundle`, `LambdaFunctionCodeBundler` and their options |\n| `@nikovirtala/projen-lambda-function-construct-generator` | `LambdaFunctionConstructGenerator`, `LambdaFunctionConstructGeneratorOptions` |\n| `@nikovirtala/projen-aws-cdk-app` | `AwsCdkTypeScriptAppProject`, `AwsCdkTypeScriptAppProjectOptions` |\n\n### Steps\n\n1. In `.projenrc.ts`, replace the old package in `devDeps` with `@nikovirtala/projen-constructs`, and\n   change the imports:\n\n   ```typescript\n   // before\n   import { Vitest } from \"@nikovirtala/projen-vitest\";\n   // after\n   import { Vitest } from \"@nikovirtala/projen-constructs\";\n   ```\n\n2. Check the peer dependencies. `@nikovirtala/projen-constructs` needs `projen` ^0.104.23, `constructs`\n   ^10 and `@mrgrain/cdk-esbuild` ^5. The standalone packages accepted older projen versions, so you\n   may have to upgrade projen in the same change.\n3. Install the new package, run `npx projen` and review the changes to the generated files.\n\n### Changes to expect\n\nThese are the differences in behaviour or generated files between the standalone packages and this\nlibrary.\n\n**Vitest**\n\n- `vitest.config.ts` imports `defineConfig` from\n  `@nikovirtala/projen-constructs/lib/vitest-define-config` instead of\n  `@nikovirtala/projen-vitest/lib/bundled-define-config`. Projen rewrites the file, so there's\n  nothing to change by hand.\n- The config is rendered as JSON, so its keys are quoted. The settings are the same.\n- `config.typecheckTsconfig` defaults to the project's development tsconfig (`test/tsconfig.json`\n  in current projen) instead of `tsconfig.dev.json`.\n- JSII and construct library projects exclude `vitest.config.ts` from the published package.\n- New: `extraTestConfig` and `extraConfig` for Vitest settings that `config` doesn't cover.\n\n**Homebrew and Colima**\n\n- Packages from a tap (`owner/tap/formula`) also add a `tap` line to the `Brewfile`, and the\n  `Brewfile` is sorted.\n- The `install:homebrew`, `homebrew:bundle` and `colima` tasks run in bash. `homebrew:bundle` also\n  finds a freshly installed `brew` that isn't on the `PATH` yet.\n\n**LocalStack**\n\n- `imageTag` is applied: LocalStack starts with `localstack/localstack:<imageTag>`. It used to be\n  ignored.\n\n**Bundler / LambdaFunctionCodeBundler**\n\n- `LambdaFunctionCodeBundler.bundleOptions` applies to every discovered entrypoint. Its `entrypoint`\n  used to replace them all.\n\n**LambdaFunctionConstructGenerator**\n\n- The bundle task runs `tsx` with the project's development tsconfig instead of `tsconfig.dev.json`.\n\n**TypeDoc**: no changes.\n\n### From `AwsCdkApp` to `AwsCdkTypeScriptAppProject`\n\n```typescript\n// before\nimport { AwsCdkApp } from \"@nikovirtala/projen-aws-cdk-app\";\nconst project = new AwsCdkApp({ name: \"my-app\", cdkVersion: \"2.221.0\" });\n\n// after\nimport { AwsCdkTypeScriptAppProject } from \"@nikovirtala/projen-constructs\";\nconst project = new AwsCdkTypeScriptAppProject({ name: \"my-app\", cdkVersion: \"2.221.0\" });\n```\n\nBoth are ES module apps using pnpm, Biome, Vitest and mise. The differences:\n\n- **Native TypeScript**: `.projenrc.ts` and the app run with `node` instead of `tsx`, and the\n  tsconfig sets `erasableSyntaxOnly` and `verbatimModuleSyntax` (see [Native TypeScript](#native-typescript)).\n\n- **`nvm` is removed.** Use mise (on by default), which pins the Node.js version in `mise.toml`.\n- **Homebrew is on by default.** The project gets a `Brewfile`, and `npx projen` runs\n  `install:homebrew` (installs Homebrew if `brew` is missing) and `homebrew:bundle`. Set\n  `homebrew: false` to turn it off.\n- **cdk.json `app`** is `node src/main.ts` instead of `tsx --tsconfig tsconfig.json src/main.ts`.\n- **Defaults** come from this library: Node.js, TypeScript, CDK and pnpm versions (pnpm 12 instead\n  of 10), Dependabot off, auto-merge on, `auto-approve` and `auto-merge` labels on dependency\n  upgrade PRs, and auto-approval of PRs by `nikovirtala`. Any option you set explicitly still wins,\n  so set `autoApproveOptions` if you aren't `nikovirtala`.\n- **tsconfig**: `noImplicitOverride` and `allowSyntheticDefaultImports` move from `tsconfig.json`\n  to the development tsconfig (`test/tsconfig.json`).\n- **Options removed from the interface**: `eslint`, `jest`, `prettier` (and their options),\n  `sampleCode` and `tsJestOptions`.\n- `vitestOptions` takes the `VitestOptions` of this library, and now also `homebrewOptions` and\n  `miseOptions`.\n\n## Development\n\nThis project is managed by Projen and generates itself: `.projenrc.ts` defines the project using the\n`JsiiProject` type from `src/`. Configuration changes belong in `.projenrc.ts`, never in the\ngenerated files.\n\n```bash\npnpm projen           # synthesize project files\npnpm build            # synthesize, compile, test and package\npnpm test             # biome, vitest, typedoc\npnpm test:watch       # vitest in watch mode\npnpm test:update      # update snapshots\npnpm biome            # format and lint\npnpm docgen           # regenerate API.md from the .jsii manifest\npnpm update-versions  # refresh src/versions.json\npnpm upgrade          # upgrade dependencies\n```\n\n### Build process\n\n```mermaid\nflowchart TD\n    projenrc[\".projenrc.ts\"]\n\n    subgraph synthesize[\"default (synthesize)\"]\n        direction TB\n        synth[\"tsx .projenrc.ts\"]\n        generator[\"ProjectGenerator\"]\n        generated[\"src/project-type.ts<br/>src/projects/*.generated.ts<br/>src/projects/*-options.generated.ts\"]\n        projenfiles[\"package.json, tsconfig.json,<br/>pnpm-workspace.yaml, workflows, ...\"]\n        brew[\"install:homebrew<br/>brew bundle\"]\n        definecfg[\"bundle-vitest-define-config<br/>esbuild → lib/vitest-define-config.js\"]\n\n        synth --> generator --> generated\n        synth --> projenfiles\n        synth --> brew\n        synth --> definecfg\n    end\n\n    subgraph compile[\"compile\"]\n        direction TB\n        jsii[\"jsii<br/>validates tsconfig.json against the strict rule set\"]\n        lib[\"lib/**\"]\n        manifest[\".jsii manifest\"]\n\n        jsii --> lib\n        jsii --> manifest\n    end\n\n    subgraph test[\"test\"]\n        direction TB\n        biome[\"biome check --write\"]\n        vitest[\"vitest run<br/>+ type checking\"]\n        typedoc[\"typedoc → docs/api\"]\n\n        biome --> vitest --> typedoc\n    end\n\n    subgraph package[\"package\"]\n        direction TB\n        pacmak[\"jsii-pacmak<br/>--pack-command 'pnpm pack'\"]\n        dist[\"dist/js/*.tgz\"]\n\n        pacmak --> dist\n    end\n\n    projenrc --> synthesize\n    synthesize --> compile\n    compile --> test\n    test --> package\n\n    manifest -. \"component options FQNs<br/>read on the next synthesis\" .-> generator\n    docgen[\"docgen<br/>jsii-docgen → API.md\"]\n    manifest --> docgen\n\n    classDef artifact fill:#eef,stroke:#88a\n    class generated,projenfiles,lib,manifest,dist artifact\n```\n\nThe dashed edge is the part worth knowing about: `ProjectGenerator` reads the committed `.jsii`\nmanifest to resolve component options types, so the manifest produced by `compile` feeds the *next*\nsynthesis. This is why `.jsii` is committed rather than ignored. A component options type that is\nmissing from the manifest is reported as a warning and its options property is left out of the\ngenerated interface, which is expected only while a new component is being introduced: compile once,\nthen synthesize again.\n\n`package` runs `package:js` on CI and `package-all` locally; both end up in `jsii-pacmak`.\n`docgen` is not part of `build` and has to be run explicitly after the manifest changes.\n"
+    "markdown": "# @nikovirtala/projen-constructs\n\nOpinionated projen project types that scaffold TypeScript, JSII and AWS CDK repositories with one shared config.\n\n[![npm version badge, latest release on npm](https://img.shields.io/npm/v/@nikovirtala/projen-constructs?label=npm)](https://www.npmjs.com/package/@nikovirtala/projen-constructs)\n[![build status badge from the GitHub Actions build workflow](https://img.shields.io/github/actions/workflow/status/nikovirtala/projen-constructs/build.yml?branch=main&label=build)](https://github.com/nikovirtala/projen-constructs/actions/workflows/build.yml)\n[![license badge, Apache-2.0](https://img.shields.io/npm/l/@nikovirtala/projen-constructs?label=license)](./LICENSE)\n[![supported Node.js version badge, requires Node.js 26.13.0 or newer](https://img.shields.io/badge/node-%3E%3D26.13.0-informational?label=node)](https://nodejs.org)\n[![projen peer dependency version badge, requires projen 0.104.23 or newer](https://img.shields.io/badge/projen-%5E0.104.23-informational?label=projen)](https://projen.io)\n\n## Why this exists\n\nProjen gives you code-first project configuration, but wiring up a consistent setup across many\nTypeScript, JSII and AWS CDK repositories still means repeating the same choices. This library\npackages those choices into ready-made project types and reusable components, so every repository\nyou generate shares the same package manager, Node.js and TypeScript versions, testing, linting and\nrelease tooling.\n\nIt is for anyone in the projen and AWS CDK community who maintains more than one repository and wants\nthem to behave the same way without hand-copying configuration between them.\n\n## When not to use this\n\nReach for plain projen instead when:\n\n- you want unopinionated projen defaults and prefer to make each tooling choice yourself\n- your setup is not pnpm-based or cannot run Node.js 26\n- you build in languages beyond TypeScript, JSII and AWS CDK\n\n## Status and supported versions\n\nStability: **stable**. This library requires `projen` ^0.104.23, pnpm 12, and Node.js >= 26.13.0.\nThese values are maintained in `src/versions.json` and the project configuration; the numbers quoted\nacross this documentation track those sources.\n\n## Documentation\n\n| Guide | What it covers |\n| --- | --- |\n| [Configuration](./docs/configuration.md) | Standard defaults, pnpm settings, the TypeScript configs, native TypeScript, and how to customize any option |\n| [Components](./docs/components.md) | Reference for every component: Vitest, TypeDoc, Mise, Homebrew, Colima, LocalStack, LambdaFunctionConstructGenerator, Bundler, and ProjectGenerator |\n| [Migration](./docs/migration.md) | Moving from the deprecated standalone packages, including the name mapping and behaviour changes |\n| [Development](./docs/development.md) | Development commands and the build process diagram |\n| [API reference](./docs/api/index.html) | Generated TypeDoc API documentation |\n\nQuick links: [Quick start](#quick-start) · [Usage](#usage) · [Features](#features).\n\n## Quick start\n\nTo start a new project from scratch, run `projen new --from` in an empty directory. It installs the\nlibrary and writes a ready-to-use `.projenrc.ts` and the full project for you, with no manual setup:\n\n```bash\npnpm dlx projen new --from @nikovirtala/projen-constructs aws_cdk_construct_library\n```\n\n**Expected output**: projen installs `@nikovirtala/projen-constructs` and its peers, writes a\n`.projenrc.ts` that defines the project, and synthesizes the generated files into the directory:\n`package.json`, `tsconfig.json`, `pnpm-workspace.yaml`, the GitHub Actions workflows, the Vitest and\nBiome configuration, `mise.toml`, and the source and test scaffolding for your construct library.\n\nPass a different project type to scaffold one of the others this library provides:\n\n| Project type | `projen new --from` argument |\n| --- | --- |\n| AWS CDK construct library | `aws_cdk_construct_library` |\n| AWS CDK TypeScript app | `aws_cdk_type_script_app` |\n| JSII | `jsii_project` |\n| TypeScript | `type_script_project` |\n\n### Adding it to an existing project\n\nIf you already have a `.projenrc.ts`, install the library alongside its `projen` and `constructs`\npeers instead:\n\n```bash\npnpm add -D @nikovirtala/projen-constructs projen constructs\n```\n\nThen define a project in `.projenrc.ts`:\n\n```typescript\nimport { AwsCdkConstructLibraryProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new AwsCdkConstructLibraryProject({\n  name: \"my-cdk-construct\",\n  author: \"Your Name\",\n  authorAddress: \"you@example.com\",\n  repositoryUrl: \"https://github.com/your-org/my-cdk-construct.git\",\n  cdkVersion: \"2.275.0\",\n});\n\nproject.synth();\n```\n\nRun synthesis to write or update the generated files:\n\n```bash\npnpm dlx projen\n```\n\nRe-running `projen` after you edit `.projenrc.ts` updates those files in place.\n\n## Features\n\n- **Standard configuration**: opinionated defaults for author, release branch, package manager,\n  Node.js, TypeScript, and tooling\n- **Automatic project type discovery**: generates the `ProjectType` enum from projen's JSII manifest\n  (<!-- generated:project-type-count-start -->21<!-- generated:project-type-count-end --> project types)\n- **Component system**: reusable components (Vitest, TypeDoc, Mise, Homebrew, Colima, LocalStack,\n  Lambda bundling)\n- **Code generation**: `ProjectGenerator` creates project classes with standard configuration\n- **ES modules**: TypeScript and CDK app projects use ES modules (JSII uses CommonJS)\n- **Code quality**: Biome for formatting and linting\n- **Testing**: Vitest with coverage\n- **Auto-merge**: enabled with auto-approve\n- **VSCode**: recommended extensions and settings\n- **mise**: Node version management\n\n## Usage\n\nEach project type applies the standard configuration and the shared components. See\n[Configuration](./docs/configuration.md) for the defaults and how to override them, and\n[Components](./docs/components.md) for the component reference.\n\n### AWS CDK construct library project\n\n```typescript\nimport { AwsCdkConstructLibraryProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new AwsCdkConstructLibraryProject({\n  name: \"my-cdk-construct\",\n  author: \"Your Name\",\n  authorAddress: \"you@example.com\",\n  repositoryUrl: \"https://github.com/nikovirtala/my-cdk-construct.git\",\n  cdkVersion: \"2.275.0\",\n});\n\nproject.synth();\n```\n\n### AWS CDK TypeScript app project\n\n```typescript\nimport { AwsCdkTypeScriptAppProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new AwsCdkTypeScriptAppProject({\n  name: \"my-cdk-app\",\n  repository: \"https://github.com/nikovirtala/my-cdk-app.git\",\n  cdkVersion: \"2.275.0\",\n});\n\nproject.synth();\n```\n\n### JSII project\n\n```typescript\nimport { JsiiProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new JsiiProject({\n  name: \"my-jsii-project\",\n  author: \"Your Name\",\n  authorAddress: \"you@example.com\",\n  repositoryUrl: \"https://github.com/nikovirtala/my-jsii-project.git\",\n});\n\nproject.synth();\n```\n\n### TypeScript project\n\n```typescript\nimport { TypeScriptProject } from \"@nikovirtala/projen-constructs\";\n\nconst project = new TypeScriptProject({\n  name: \"my-typescript-project\",\n  repository: \"https://github.com/nikovirtala/my-typescript-project.git\",\n});\n\nproject.synth();\n```\n\n## Contributing\n\nSee [Development](./docs/development.md) for the commands and the build process. Configuration\nchanges belong in `.projenrc.ts`, never in the generated files.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"
   },
   "repository": {
     "type": "git",
@@ -21397,6 +21397,6 @@
       "symbolId": "src/components/vitest:VitestOptions"
     }
   },
-  "version": "0.5.1",
-  "fingerprint": "lRTyhf+ZhOeupjIiVw+BEiEh09V9s7tiv8V/ZXRJZaQ="
+  "version": "0.5.3",
+  "fingerprint": "9ZXx2a7Wj9+u8ZpSRwZ7hp1KuPU9hkOQ0Xjh8OzPbws="
 }

package/.kiro/steering/product.md

@@ -9,18 +9,20 @@ Automates project scaffolding and configuration for TypeScript, JSII, and AWS CD
 ## Key Features
 
 - **Standard Configuration**: Opinionated defaults for author, release branch, package manager, Node.js, TypeScript, and tooling
-- **Automatic Project Type Discovery**: Generates `ProjectType` enum from Projen's JSII manifest (18 project types)
+- **Automatic Project Type Discovery**: Generates `ProjectType` enum from Projen's JSII manifest (<!-- generated:project-type-count-start -->21<!-- generated:project-type-count-end --> project types)
 - **Component System**: Reusable components (Vitest, Mise, TypeDoc, LocalStack, Homebrew, Colima, etc.)
 - **Code Generation**: `ProjectGenerator` creates project classes with standard configuration
 - **ES Modules**: TypeScript and CDK App projects use ES modules (JSII uses CommonJS)
 
 ## Standard Defaults
 
+<!-- generated:product-defaults-start -->
 - Author: Niko Virtala (niko.virtala@hey.com)
-- Package Manager: pnpm 11
-- Node Version: 24.11.1
-- TypeScript: 5.9.3
-- CDK Version: 2.223.0
+- Package Manager: pnpm 12
+- Node Version: 26.13.0
+- TypeScript: 6.0.3
+- CDK Version: 2.275.0
+<!-- generated:product-defaults-end -->
 - Code Quality: Biome for formatting and linting
 - Testing: Vitest with coverage
 - Version Management: mise

package/.kiro/steering/tech.md

@@ -15,10 +15,12 @@ This project is **entirely managed by projen**. Key implications:
 
 ## Core Technologies
 
-- **TypeScript 5.9.3** - Primary language
-- **Node.js 24.11.1** - Runtime (managed via mise)
-- **JSII ~5.9.3** - Multi-language library support
-- **pnpm 11** - Package manager (settings live in `pnpm-workspace.yaml`, not `.npmrc`)
+<!-- generated:tech-core-start -->
+- **TypeScript 6.0.3** - Primary language
+- **Node.js 26.13.0** - Runtime (managed via mise)
+- **JSII ~6.0.3** - Multi-language library support
+- **pnpm 12** - Package manager (settings live in `pnpm-workspace.yaml`, not `.npmrc`)
+<!-- generated:tech-core-end -->
 
 ## Code Quality
 
@@ -30,7 +32,7 @@ This project is **entirely managed by projen**. Key implications:
 
 ## Testing
 
-- **Vitest 4** - Test framework (replaces Jest)
+- **Vitest <!-- generated:vitest-major-start -->5<!-- generated:vitest-major-end -->** - Test framework (replaces Jest)
   - Coverage provider: v8
   - Coverage reporters: text, lcov
   - Type checking enabled with tsc

package/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+This file orients AI and code agents working in this repository. It is intentionally short and points to the authoritative docs rather than restating them.
+
+## What this project is
+
+`@nikovirtala/projen-constructs` is a JSII library of opinionated [projen](https://projen.io) project types (TypeScript, JSII, and AWS CDK) that scaffold repositories with one shared configuration. It is written in TypeScript, compiled with JSII, and published to npm.
+
+## The single most important rule
+
+**This project generates itself with projen. Never hand-edit generated files.** Make configuration changes in `.projenrc.ts` (or the helpers in `src/` it uses), then run `pnpm projen` to regenerate everything else.
+
+Generated files carry a `~~ Generated by projen` header or are listed in `.projen/files.json`. That set includes `package.json`, `tsconfig*.json`, `vitest.config.ts`, `biome.jsonc`, `mise.toml`, the GitHub workflows, `src/project-type.ts`, and `src/projects/*.generated.ts`. Any manual edit to those is overwritten on the next synth.
+
+## Where things live
+
+- `.projenrc.ts` — the project definition and the only place to make config-level changes.
+- `src/components/` — reusable projen components (Vitest, TypeDoc, Mise, Homebrew, Colima, LocalStack, Lambda helpers). Edit directly.
+- `src/config.ts`, `src/errors.ts`, `src/utils.ts`, `src/versions.json` — editable core sources.
+- `src/projects/` — **generated** project classes. Do not edit.
+- `src/project-generator.ts` and `src/project-type.ts` — code generation (`project-type.ts` is generated).
+- `test/` — mirrors `src/`; unit tests in `test/**`, integration tests in `test/integration/`.
+- `docs/` — hand-written guides plus `docs/api/` (generated TypeDoc output).
+
+## Build and test
+
+- Runtime: Node.js `>= 26.13.0` (managed via mise) and pnpm 12.
+- `pnpm install` — install dependencies.
+- `pnpm projen` — regenerate projen-managed files after editing `.projenrc.ts`.
+- `pnpm build` — full synth, JSII compile, tests, and docs.
+- `pnpm test` — Vitest unit tests with tsc type checking.
+- `pnpm biome` — format and lint.
+
+Note on older Node: the engines require Node `>= 26.13.0`, but the build and unit tests also run on Node 24 (npm prints a harmless `EBADENGINE` warning). If you are in an environment where Homebrew cannot be installed, the projen `default` task and `pnpm build`/`pnpm projen` abort at the `install:homebrew` step; synthesize directly instead with `pnpm exec tsx --tsconfig test/tsconfig.json .projenrc.ts`, then compile with `pnpm exec jsii --silence-warnings=reserved-word`.
+
+## Read these for depth (do not duplicate them)
+
+- `.kiro/steering/product.md` — product overview and purpose.
+- `.kiro/steering/tech.md` — technology stack, tooling, and conventions.
+- `.kiro/steering/structure.md` — directory layout and file ownership.
+- `CONTRIBUTING.md` — setup, key commands, Conventional Commits, PR-title linting, and how to propose changes.

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Releases are published automatically with [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) from Conventional Commit history. GitHub also hosts auto-generated release notes for every tag at [the releases page](https://github.com/nikovirtala/projen-constructs/releases); the entries below summarize the breaking and otherwise notable changes.
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.5.0] - 2026-11-03
+
+### Changed
+
+- **BREAKING:** Generated TypeScript and AWS CDK app projects now run `.projenrc.ts` and the app itself with `node` using native type stripping instead of `tsx`. Project code must use only erasable TypeScript syntax, mark type-only imports with `import type`, import relative files with their `.ts` extension, and can no longer rely on `tsconfig` path aliases (#248).
+
+### Removed
+
+- **BREAKING:** Dropped the `tsx` fallback for Node.js versions that lack native type stripping. Running these projects now requires a Node.js version with type-stripping support (#248).
+
+## [0.4.1] - 2026-11-03
+
+Maintenance release. No notable changes.
+
+## [0.4.0] - 2026-11-02
+
+### Changed
+
+- **BREAKING:** Default to Node.js 26 LTS. Generated projects now require Node.js `>= 26.13.0` and receive `@types/node ^26` unless `minNodeVersion` is set explicitly (#242).
+- **BREAKING:** Default to pnpm 12. Generated projects pin pnpm `12.16.1` unless `pnpmVersion` is set. A globally installed pnpm older than 11 cannot switch to this version, and `--frozen-lockfile false` and `--resolution-only` are no longer accepted flags (#243).
+- **BREAKING:** Default to Vitest 5. It requires Node.js `>= 22.12` and Vite `>= 6.4`, enables `clearMocks` by default, and throws when `vi.mock` is called outside the top level of a module. Set `vitestVersion: '^4'` to stay on Vitest 4 (#241).
+
+## Earlier releases
+
+Releases before `0.4.0` (the `0.3.x` line and earlier) are not detailed here. See the [automated GitHub release notes](https://github.com/nikovirtala/projen-constructs/releases) for the full history of older tags.
+
+[Unreleased]: https://github.com/nikovirtala/projen-constructs/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/nikovirtala/projen-constructs/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/nikovirtala/projen-constructs/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/nikovirtala/projen-constructs/compare/v0.3.0...v0.4.0

package/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thanks for your interest in improving `@nikovirtala/projen-constructs`. This guide covers how the repository is built, how to set it up locally, and how to propose changes.
+
+## This project generates itself with projen
+
+The repository is managed by [projen](https://projen.io). `.projenrc.ts` is the single source of truth: it defines the project using the `JsiiProject` type from this very library, and running projen regenerates the rest of the configuration (`package.json`, `tsconfig*.json`, `vitest.config.ts`, `biome.jsonc`, `mise.toml`, the GitHub workflows, and more).
+
+Because of this, there is one rule that matters more than any other:
+
+> **Never hand-edit generated files.** Change `.projenrc.ts` (or the helpers in `src/` it uses) and run `pnpm projen` to regenerate.
+
+Generated and linguist-generated files carry a `~~ Generated by projen` header or are listed in `.projen/files.json`. This also includes `src/project-type.ts` and everything under `src/projects/*.generated.ts`, which are produced by the `ProjectGenerator` component during synthesis. Editing any of these by hand is pointless: the next synth overwrites your change.
+
+Files you *can* edit directly include `.projenrc.ts`, the non-generated sources under `src/` (`src/components/*.ts`, `src/config.ts`, `src/errors.ts`, `src/utils.ts`, `src/versions.json`), the tests under `test/`, and the hand-written docs (`README.md`, `docs/*.md`, `.kiro/steering/*.md`, and the root markdown files like this one).
+
+## Local setup
+
+- **Node.js** `>= 26.13.0`. The version is managed with [mise](https://mise.jdx.dev) via `mise.toml`; run `mise install` to get the pinned toolchain.
+- **pnpm 12** is the package manager (pinned to `12.16.1`). `corepack enable` will resolve it automatically from `package.json`.
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+## Key commands
+
+| Command | What it does |
+| --- | --- |
+| `pnpm projen` | Regenerate all projen-managed files from `.projenrc.ts`. Run this after any config change. |
+| `pnpm build` | Full build: synth, compile with JSII, run tests, and generate docs. |
+| `pnpm test` | Run the Vitest unit tests (with tsc type checking). |
+| `pnpm biome` | Format and lint with Biome. |
+| `pnpm docgen` | Regenerate `API.md` with jsii-docgen. |
+| `pnpm update-versions` | Refresh `src/versions.json` with the latest AWS CDK, Node.js, and TypeScript versions. |
+
+## Running tests
+
+Unit tests live in `test/**` and run with [Vitest](https://vitest.dev):
+
+```bash
+pnpm test
+```
+
+Integration tests under `test/integration/` build and pack the package into a temporary directory and exercise the generated projects. They are heavier and environment-sensitive, so run the unit suite for day-to-day work and rely on CI for the full matrix.
+
+## Commits, PR titles, and releases
+
+- Follow [Conventional Commits](https://www.conventionalcommits.org). The commit type drives the changelog and the next version number.
+- **Pull request titles are linted** by the `pull-request-lint` workflow and must also follow Conventional Commits. Use `feat!:` / `fix!:` (or a `BREAKING CHANGE:` footer) for breaking changes.
+- Releases are automated with [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) from the merged commit history. You do not bump versions or edit `CHANGELOG.md` by hand for a release.
+
+## Proposing a change
+
+1. Fork the repository and create a feature branch off `main`.
+2. Make your change in `.projenrc.ts` and/or the editable sources, then run `pnpm projen` so the generated files are in sync.
+3. Run `pnpm build` (or at least `pnpm test` and `pnpm biome`) and commit every file the workflow touched, including regenerated output.
+4. Open a pull request with a Conventional Commit style title and a clear description of the change.
+
+## Where to learn more
+
+- `.kiro/steering/product.md`, `.kiro/steering/tech.md`, and `.kiro/steering/structure.md` describe the product, tech stack, and directory layout in depth.
+- `docs/*.md` holds the longer-form reference material and guides.
+- `AGENTS.md` is a short orientation for AI/code agents working in the repository.