@nikovirtala/projen-constructs 0.5.1 → 0.5.2

package/docs/api/media/configuration.md

@@ -0,0 +1,108 @@
+# Configuration
+
+This page covers the configuration that `@nikovirtala/projen-constructs` applies to generated
+projects: package manager settings, the TypeScript configs, native TypeScript execution, and how
+you override any of it.
+
+## Standard configuration
+
+Every project type ships with the same opinionated defaults:
+
+<!-- generated:version-table-start -->
+- **Author**: Niko Virtala (niko.virtala@hey.com)
+- **Default release branch**: main
+- **Package manager**: pnpm 12.16.1
+- **Node version**: 26.13.0
+- **TypeScript**: 6.0.3
+- **CDK version**: 2.275.0 (for CDK projects)
+- **JSII version**: ~6.0.3 (for JSII projects)
+<!-- generated:version-table-end -->
+
+The AWS CDK, Node.js and TypeScript versions live in `src/versions.json` and are refreshed by the
+`update-versions` task, which the dependency upgrade workflow runs.
+
+## pnpm
+
+pnpm reads its settings from `pnpm-workspace.yaml`, not `.npmrc`, since pnpm 11. Generated projects
+get:
+
+| Setting                | Value             | Reason                                                                                                       |
+| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `nodeLinker`           | `hoisted`         | jsii tooling resolves dependencies from a flat `node_modules`                                                |
+| `allowBuilds`          | `esbuild: true`   | esbuild links its platform binary in a postinstall script, and pnpm 11 fails an install with ignored builds   |
+| `verifyDepsBeforeRun`  | `false`           | projen resolves the task `PATH` with `$(pnpm -c exec ...)`, which otherwise re-enters `pnpm install` and deadlocks |
+| `minimumReleaseAge`    | `0`              | the pnpm 11 default of 1440 minutes makes pnpm write `minimumReleaseAgeExclude` entries into this generated file |
+
+## TypeScript configuration
+
+Projen renders three configs, and you should not edit any of them directly:
+
+- `tsconfig.json` compiles `src` to `lib`. For JSII projects, jsii validates it against its `strict`
+  rule set, so it only carries compiler options jsii accepts.
+- `test/tsconfig.json` extends it and is type-check only. This is the config Vitest type checking and
+  the editor use, and the one `tsconfigDev` points at.
+- `projenrc/tsconfig.json` covers `.projenrc.ts`.
+
+## Native TypeScript
+
+TypeScript and AWS CDK app projects run TypeScript with Node.js's built-in
+[type stripping](https://nodejs.org/api/typescript.html#type-stripping) instead of `tsx` or
+`ts-node`: the default task is `node .projenrc.ts`, and the cdk.json `app` is `node src/main.ts`.
+Their `tsconfig.json` sets `erasableSyntaxOnly` and `verbatimModuleSyntax`, so `tsc` reports code
+that Node.js cannot run before Node.js does.
+
+Code in these projects must therefore:
+
+- only use syntax that can be stripped: no `enum`s (use an `as const` object), no namespaces with
+  values, and no constructor parameter properties
+- mark type-only imports with `type` (Biome's `useImportType` fixes these)
+- import relative files with their `.ts` extension, and never import a directory
+- use Node.js [subpath imports](https://nodejs.org/api/packages.html#subpath-imports)
+  (`#stacks` in `package.json` `imports`) instead of tsconfig `paths`, which Node.js does not read
+- import packages without an `exports` map either from the package root or with an explicit file,
+  e.g. `projen/lib/component.js` rather than `projen/lib/component`
+
+Lambda handlers bundled by esbuild and tests run by Vitest are not run by Node.js directly, but the
+same compiler options apply to them.
+
+JSII and AWS CDK construct library projects keep using `tsx`, because jsii compiles to CommonJS, and
+their `.projenrc.ts` often imports their own `src`.
+
+When you start a new project by hand, make sure `package.json` has `"type": "module"` before the
+first `node .projenrc.ts`: `npm init` writes `"type": "commonjs"`, which makes Node.js reject the
+`import` statements in `.projenrc.ts`.
+
+## Customization
+
+Override any option by passing it to the constructor:
+
+```typescript
+import { JsiiProject } from "@nikovirtala/projen-constructs";
+
+const project = new JsiiProject({
+  name: "my-project",
+  author: "Custom Author",
+  authorAddress: "custom@example.com",
+  repositoryUrl: "https://github.com/nikovirtala/my-project.git",
+  minNodeVersion: "26.0.0",
+  mise: false,
+  vitest: false,
+  tsconfig: {
+    compilerOptions: {
+      noUnusedLocals: false,
+    },
+  },
+  biomeOptions: {
+    biomeConfig: {
+      formatter: {
+        lineWidth: 100,
+      },
+    },
+  },
+});
+
+project.synth();
+```
+
+Every component is exposed as an enable flag (`mise`, `vitest`, ...) plus an options property
+(`miseOptions`, `vitestOptions`, ...).

package/docs/api/media/development.md

@@ -0,0 +1,93 @@
+# Development
+
+This project is managed by projen and generates itself: `.projenrc.ts` defines the project using the
+`JsiiProject` type from `src/`. Configuration changes belong in `.projenrc.ts`, never in the
+generated files.
+
+## Commands
+
+```bash
+pnpm projen           # synthesize project files
+pnpm build            # synthesize, compile, test and package
+pnpm test             # biome, vitest, typedoc
+pnpm test:watch       # vitest in watch mode
+pnpm test:update      # update snapshots
+pnpm biome            # format and lint
+pnpm docgen           # regenerate API.md from the .jsii manifest
+pnpm update-versions  # refresh src/versions.json
+pnpm upgrade          # upgrade dependencies
+```
+
+## Build process
+
+The diagram below shows how synthesis, compile, test and package connect. Each node names a task or
+artifact, and the arrows show the order they run in.
+
+```mermaid
+flowchart TD
+    projenrc[".projenrc.ts"]
+
+    subgraph synthesize["default (synthesize)"]
+        direction TB
+        synth["tsx .projenrc.ts"]
+        generator["ProjectGenerator"]
+        generated["src/project-type.ts<br/>src/projects/*.generated.ts<br/>src/projects/*-options.generated.ts"]
+        projenfiles["package.json, tsconfig.json,<br/>pnpm-workspace.yaml, workflows, ..."]
+        brew["install:homebrew<br/>brew bundle"]
+        definecfg["bundle-vitest-define-config<br/>esbuild → lib/vitest-define-config.js"]
+
+        synth --> generator --> generated
+        synth --> projenfiles
+        synth --> brew
+        synth --> definecfg
+    end
+
+    subgraph compile["compile"]
+        direction TB
+        jsii["jsii<br/>validates tsconfig.json against the strict rule set"]
+        lib["lib/**"]
+        manifest[".jsii manifest"]
+
+        jsii --> lib
+        jsii --> manifest
+    end
+
+    subgraph test["test"]
+        direction TB
+        biome["biome check --write"]
+        vitest["vitest run<br/>+ type checking"]
+        typedoc["typedoc → docs/api"]
+
+        biome --> vitest --> typedoc
+    end
+
+    subgraph package["package"]
+        direction TB
+        pacmak["jsii-pacmak<br/>--pack-command 'pnpm pack'"]
+        dist["dist/js/*.tgz"]
+
+        pacmak --> dist
+    end
+
+    projenrc --> synthesize
+    synthesize --> compile
+    compile --> test
+    test --> package
+
+    manifest -. "component options FQNs<br/>read on the next synthesis" .-> generator
+    docgen["docgen<br/>jsii-docgen → API.md"]
+    manifest --> docgen
+
+    classDef artifact fill:#eef,stroke:#88a
+    class generated,projenfiles,lib,manifest,dist artifact
+```
+
+The dashed edge is the part worth knowing about: `ProjectGenerator` reads the committed `.jsii`
+manifest to resolve component options types, so the manifest produced by `compile` feeds the *next*
+synthesis. This is why `.jsii` is committed rather than ignored. A component options type that is
+missing from the manifest is reported as a warning and its options property is left out of the
+generated interface, which is expected only while a new component is being introduced: compile once,
+then synthesize again.
+
+`package` runs `package:js` on CI and `package-all` locally; both end up in `jsii-pacmak`.
+`docgen` is not part of `build` and has to be run explicitly after the manifest changes.

package/docs/api/media/index.html

@@ -0,0 +1,169 @@
+<!DOCTYPE html><html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@nikovirtala/projen-constructs</title><meta name="description" content="Documentation for @nikovirtala/projen-constructs"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar">
+<div class="tsd-toolbar-contents container"><a href="index.html" class="title">@nikovirtala/projen-constructs</a>
+<div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/>
+<ul role="listbox" id="tsd-search-results"></ul>
+<div id="tsd-search-status" aria-live="polite" aria-atomic="true">
+<div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></header>
+<div class="container container-main">
+<div class="col-content">
+<div class="tsd-page-title">
+<h1>@nikovirtala/projen-constructs</h1></div>
+<div class="tsd-panel tsd-typography"><h1 id="nikovirtalaprojen-constructs" class="tsd-anchor-link">@nikovirtala/projen-constructs<a href="#nikovirtalaprojen-constructs" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1>
+<p>Opinionated projen project types that scaffold TypeScript, JSII and AWS CDK repositories with one shared config.</p>
+<p><a href="https://www.npmjs.com/package/@nikovirtala/projen-constructs"><img src="https://img.shields.io/npm/v/@nikovirtala/projen-constructs?label=npm" alt="npm version badge, latest release on npm"></a>
+<a href="https://github.com/nikovirtala/projen-constructs/actions/workflows/build.yml"><img src="https://img.shields.io/github/actions/workflow/status/nikovirtala/projen-constructs/build.yml?branch=main&amp;label=build" alt="build status badge from the GitHub Actions build workflow"></a>
+<a href="./LICENSE"><img src="https://img.shields.io/npm/l/@nikovirtala/projen-constructs?label=license" alt="license badge, Apache-2.0"></a>
+<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D26.13.0-informational?label=node" alt="supported Node.js version badge, requires Node.js 26.13.0 or newer"></a>
+<a href="https://projen.io"><img src="https://img.shields.io/badge/projen-%5E0.104.23-informational?label=projen" alt="projen peer dependency version badge, requires projen 0.104.23 or newer"></a></p>
+<h2 id="why-this-exists" class="tsd-anchor-link">Why this exists<a href="#why-this-exists" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<p>Projen gives you code-first project configuration, but wiring up a consistent setup across many
+TypeScript, JSII and AWS CDK repositories still means repeating the same choices. This library
+packages those choices into ready-made project types and reusable components, so every repository
+you generate shares the same package manager, Node.js and TypeScript versions, testing, linting and
+release tooling.</p>
+<p>It is for anyone in the projen and AWS CDK community who maintains more than one repository and wants
+them to behave the same way without hand-copying configuration between them.</p>
+<h2 id="when-not-to-use-this" class="tsd-anchor-link">When not to use this<a href="#when-not-to-use-this" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<p>Reach for plain projen instead when:</p>
+<ul>
+<li>you want unopinionated projen defaults and prefer to make each tooling choice yourself</li>
+<li>your setup is not pnpm-based or cannot run Node.js 26</li>
+<li>you build in languages beyond TypeScript, JSII and AWS CDK</li>
+</ul>
+<h2 id="status-and-supported-versions" class="tsd-anchor-link">Status and supported versions<a href="#status-and-supported-versions" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<p>Stability: <strong>stable</strong>. This library requires <code>projen</code> ^0.104.23, pnpm 12, and Node.js &gt;= 26.13.0.
+These values are maintained in <code>src/versions.json</code> and the project configuration; the numbers quoted
+across this documentation track those sources.</p>
+<h2 id="documentation" class="tsd-anchor-link">Documentation<a href="#documentation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<table>
+<thead>
+<tr>
+<th>Guide</th>
+<th>What it covers</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="media/configuration.md">Configuration</a></td>
+<td>Standard defaults, pnpm settings, the TypeScript configs, native TypeScript, and how to customize any option</td>
+</tr>
+<tr>
+<td><a href="media/components.md">Components</a></td>
+<td>Reference for every component: Vitest, TypeDoc, Mise, Homebrew, Colima, LocalStack, LambdaFunctionConstructGenerator, Bundler, and ProjectGenerator</td>
+</tr>
+<tr>
+<td><a href="media/migration.md">Migration</a></td>
+<td>Moving from the deprecated standalone packages, including the name mapping and behaviour changes</td>
+</tr>
+<tr>
+<td><a href="media/development.md">Development</a></td>
+<td>Development commands and the build process diagram</td>
+</tr>
+<tr>
+<td><a href="media/index.html">API reference</a></td>
+<td>Generated TypeDoc API documentation</td>
+</tr>
+</tbody>
+</table>
+<p>Quick links: <a href="#quick-start">Quick start</a> · <a href="#usage">Usage</a> · <a href="#features">Features</a>.</p>
+<h2 id="quick-start" class="tsd-anchor-link">Quick start<a href="#quick-start" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<p>Install the library alongside its <code>projen</code> and <code>constructs</code> peers:</p>
+<pre><code class="bash"><span class="hl-0">pnpm</span><span class="hl-1"> </span><span class="hl-2">add</span><span class="hl-1"> </span><span class="hl-3">-D</span><span class="hl-1"> </span><span class="hl-2">@nikovirtala/projen-constructs</span><span class="hl-1"> </span><span class="hl-2">projen</span><span class="hl-1"> </span><span class="hl-2">constructs</span>
+</code><button type="button">Copy</button></pre>
+
+<p>Create a <code>.projenrc.ts</code> that defines an AWS CDK construct library and synthesizes it:</p>
+<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">AwsCdkConstructLibraryProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@nikovirtala/projen-constructs&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">AwsCdkConstructLibraryProject</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">&quot;my-cdk-construct&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">author:</span><span class="hl-1"> </span><span class="hl-2">&quot;Your Name&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">authorAddress:</span><span class="hl-1"> </span><span class="hl-2">&quot;you@example.com&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">repositoryUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://github.com/your-org/my-cdk-construct.git&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">cdkVersion:</span><span class="hl-1"> </span><span class="hl-2">&quot;2.275.0&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
+</code><button type="button">Copy</button></pre>
+
+<p>Then run synthesis:</p>
+<pre><code class="bash"><span class="hl-0">pnpm</span><span class="hl-1"> </span><span class="hl-2">dlx</span><span class="hl-1"> </span><span class="hl-2">projen</span>
+</code><button type="button">Copy</button></pre>
+
+<p><strong>Expected output</strong>: projen reads <code>.projenrc.ts</code> and writes the generated project files into the
+working directory: <code>package.json</code>, <code>tsconfig.json</code>, <code>pnpm-workspace.yaml</code>, the GitHub Actions
+workflows, the Vitest and Biome configuration, <code>mise.toml</code>, and the source and test scaffolding for
+your construct library. Re-running the command after you edit <code>.projenrc.ts</code> updates those files in
+place.</p>
+<p>To start a project from scratch without writing <code>.projenrc.ts</code> yourself:</p>
+<pre><code class="bash"><span class="hl-0">pnpm</span><span class="hl-1"> </span><span class="hl-2">dlx</span><span class="hl-1"> </span><span class="hl-2">projen</span><span class="hl-1"> </span><span class="hl-2">new</span><span class="hl-1"> </span><span class="hl-3">--from</span><span class="hl-1"> </span><span class="hl-2">@nikovirtala/projen-constructs</span><span class="hl-1"> </span><span class="hl-2">aws_cdk_construct_library</span>
+</code><button type="button">Copy</button></pre>
+
+<h2 id="features" class="tsd-anchor-link">Features<a href="#features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<ul>
+<li><strong>Standard configuration</strong>: opinionated defaults for author, release branch, package manager,
+Node.js, TypeScript, and tooling</li>
+<li><strong>Automatic project type discovery</strong>: generates the <code>ProjectType</code> enum from projen's JSII manifest
+(<!-- generated:project-type-count-start -->21<!-- generated:project-type-count-end --> project types)</li>
+<li><strong>Component system</strong>: reusable components (Vitest, TypeDoc, Mise, Homebrew, Colima, LocalStack,
+Lambda bundling)</li>
+<li><strong>Code generation</strong>: <code>ProjectGenerator</code> creates project classes with standard configuration</li>
+<li><strong>ES modules</strong>: TypeScript and CDK app projects use ES modules (JSII uses CommonJS)</li>
+<li><strong>Code quality</strong>: Biome for formatting and linting</li>
+<li><strong>Testing</strong>: Vitest with coverage</li>
+<li><strong>Auto-merge</strong>: enabled with auto-approve</li>
+<li><strong>VSCode</strong>: recommended extensions and settings</li>
+<li><strong>mise</strong>: Node version management</li>
+</ul>
+<h2 id="usage" class="tsd-anchor-link">Usage<a href="#usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<p>Each project type applies the standard configuration and the shared components. See
+<a href="media/configuration.md">Configuration</a> for the defaults and how to override them, and
+<a href="media/components.md">Components</a> for the component reference.</p>
+<h3 id="aws-cdk-construct-library-project" class="tsd-anchor-link">AWS CDK construct library project<a href="#aws-cdk-construct-library-project" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">AwsCdkConstructLibraryProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@nikovirtala/projen-constructs&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">AwsCdkConstructLibraryProject</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">&quot;my-cdk-construct&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">author:</span><span class="hl-1"> </span><span class="hl-2">&quot;Your Name&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">authorAddress:</span><span class="hl-1"> </span><span class="hl-2">&quot;you@example.com&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">repositoryUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://github.com/nikovirtala/my-cdk-construct.git&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">cdkVersion:</span><span class="hl-1"> </span><span class="hl-2">&quot;2.275.0&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
+</code><button type="button">Copy</button></pre>
+
+<h3 id="aws-cdk-typescript-app-project" class="tsd-anchor-link">AWS CDK TypeScript app project<a href="#aws-cdk-typescript-app-project" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">AwsCdkTypeScriptAppProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@nikovirtala/projen-constructs&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">AwsCdkTypeScriptAppProject</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">&quot;my-cdk-app&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">repository:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://github.com/nikovirtala/my-cdk-app.git&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">cdkVersion:</span><span class="hl-1"> </span><span class="hl-2">&quot;2.275.0&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
+</code><button type="button">Copy</button></pre>
+
+<h3 id="jsii-project" class="tsd-anchor-link">JSII project<a href="#jsii-project" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">JsiiProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@nikovirtala/projen-constructs&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">JsiiProject</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">&quot;my-jsii-project&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">author:</span><span class="hl-1"> </span><span class="hl-2">&quot;Your Name&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">authorAddress:</span><span class="hl-1"> </span><span class="hl-2">&quot;you@example.com&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">repositoryUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://github.com/nikovirtala/my-jsii-project.git&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
+</code><button type="button">Copy</button></pre>
+
+<h3 id="typescript-project" class="tsd-anchor-link">TypeScript project<a href="#typescript-project" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
+<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">TypeScriptProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@nikovirtala/projen-constructs&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">TypeScriptProject</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">&quot;my-typescript-project&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">repository:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://github.com/nikovirtala/my-typescript-project.git&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
+</code><button type="button">Copy</button></pre>
+
+<h2 id="contributing" class="tsd-anchor-link">Contributing<a href="#contributing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<p>See <a href="media/development.md">Development</a> for the commands and the build process. Configuration
+changes belong in <code>.projenrc.ts</code>, never in the generated files.</p>
+<h2 id="license" class="tsd-anchor-link">License<a href="#license" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<p>Apache-2.0. See <a href="media/LICENSE">LICENSE</a>.</p>
+</div></div>
+<div class="col-sidebar">
+<div class="page-menu">
+<div class="tsd-navigation settings">
+<details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>
+<h3>Settings</h3></summary>
+<div class="tsd-accordion-details">
+<div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span>
+<ul id="tsd-filter-options">
+<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li>
+<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li>
+<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div>
+<div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div>
+<details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>
+<h3>On This Page</h3></summary>
+<div class="tsd-accordion-details"><a href="#nikovirtalaprojen-constructs"><span>@nikovirtala/projen-<wbr/>constructs</span></a>
+<ul>
+<li><a href="#why-this-exists"><span>Why this exists</span></a></li>
+<li><a href="#when-not-to-use-this"><span>When not to use this</span></a></li>
+<li><a href="#status-and-supported-versions"><span>Status and supported versions</span></a></li>
+<li><a href="#documentation"><span>Documentation</span></a></li>
+<li><a href="#quick-start"><span>Quick start</span></a></li>
+<li><a href="#features"><span>Features</span></a></li>
+<li><a href="#usage"><span>Usage</span></a></li>
+<li>
+<ul>
+<li><a href="#aws-cdk-construct-library-project"><span>AWS <wbr/>CDK construct library project</span></a></li>
+<li><a href="#aws-cdk-typescript-app-project"><span>AWS <wbr/>CDK <wbr/>Type<wbr/>Script app project</span></a></li>
+<li><a href="#jsii-project"><span>JSII project</span></a></li>
+<li><a href="#typescript-project"><span>Type<wbr/>Script project</span></a></li></ul></li>
+<li><a href="#contributing"><span>Contributing</span></a></li>
+<li><a href="#license"><span>License</span></a></li></ul></div></details></div>
+<div class="site-menu">
+<nav class="tsd-navigation"><a href="modules.html">@nikovirtala/projen-constructs</a>
+<ul class="tsd-small-nested-navigation" id="tsd-nav-container">
+<li>Loading...</li></ul></nav></div></div></div><footer>
+<p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer>
+<div class="overlay"></div></body></html>

package/docs/api/media/migration.md

@@ -0,0 +1,106 @@
+# Migrating from the standalone packages
+
+The components used to be published as separate packages. Those packages are deprecated and will not
+get new features or fixes. Every class, interface, enum and function they exported is exported from
+`@nikovirtala/projen-constructs` under the same name, except `AwsCdkApp` (see below).
+
+| Deprecated package | Replacement in `@nikovirtala/projen-constructs` |
+| --- | --- |
+| `@nikovirtala/projen-vitest` | `Vitest`, `VitestOptions`, `VitestConfigOptions`, `Environment`, `Pool`, `CoverageProvider`, `CoverageReporter` |
+| `@nikovirtala/projen-typedoc` | `TypeDoc`, `TypeDocOptions`, `TypeDocConfiguration` and its enums |
+| `@nikovirtala/projen-homebrew` | `Homebrew`, `HomebrewOptions` |
+| `@nikovirtala/projen-colima` | `Colima` |
+| `@nikovirtala/projen-localstack` | `LocalStack`, `LocalStackOptions` |
+| `@nikovirtala/projen-bundle-lambda-function-code` | `Bundler`, `LambdaFunctionCodeBundle`, `LambdaFunctionCodeBundler` and their options |
+| `@nikovirtala/projen-lambda-function-construct-generator` | `LambdaFunctionConstructGenerator`, `LambdaFunctionConstructGeneratorOptions` |
+| `@nikovirtala/projen-aws-cdk-app` | `AwsCdkTypeScriptAppProject`, `AwsCdkTypeScriptAppProjectOptions` |
+
+## Steps
+
+1. In `.projenrc.ts`, replace the old package in `devDeps` with `@nikovirtala/projen-constructs`, and
+   change the imports:
+
+   ```typescript
+   // before
+   import { Vitest } from "@nikovirtala/projen-vitest";
+   // after
+   import { Vitest } from "@nikovirtala/projen-constructs";
+   ```
+
+2. Check the peer dependencies. `@nikovirtala/projen-constructs` needs `projen` ^0.104.23, `constructs`
+   ^10 and `@mrgrain/cdk-esbuild` ^5. The standalone packages accepted older projen versions, so you
+   may have to upgrade projen in the same change.
+3. Install the new package, run `npx projen` and review the changes to the generated files.
+
+## Changes to expect
+
+These are the differences in behaviour or generated files between the standalone packages and this
+library.
+
+**Vitest**
+
+- `vitest.config.ts` imports `defineConfig` from
+  `@nikovirtala/projen-constructs/lib/vitest-define-config` instead of
+  `@nikovirtala/projen-vitest/lib/bundled-define-config`. Projen rewrites the file, so there is
+  nothing to change by hand.
+- The config is rendered as JSON, so its keys are quoted. The settings are the same.
+- `config.typecheckTsconfig` defaults to the project's development tsconfig (`test/tsconfig.json`
+  in current projen) instead of `tsconfig.dev.json`.
+- JSII and construct library projects exclude `vitest.config.ts` from the published package.
+- New: `extraTestConfig` and `extraConfig` for Vitest settings that `config` does not cover.
+
+**Homebrew and Colima**
+
+- Packages from a tap (`owner/tap/formula`) also add a `tap` line to the `Brewfile`, and the
+  `Brewfile` is sorted.
+- The `install:homebrew`, `homebrew:bundle` and `colima` tasks run in bash. `homebrew:bundle` also
+  finds a freshly installed `brew` that is not on the `PATH` yet.
+
+**LocalStack**
+
+- `imageTag` is applied: LocalStack starts with `localstack/localstack:<imageTag>`. It used to be
+  ignored.
+
+**Bundler / LambdaFunctionCodeBundler**
+
+- `LambdaFunctionCodeBundler.bundleOptions` applies to every discovered entrypoint. Its `entrypoint`
+  used to replace them all.
+
+**LambdaFunctionConstructGenerator**
+
+- The bundle task runs `tsx` with the project's development tsconfig instead of `tsconfig.dev.json`.
+
+**TypeDoc**: no changes.
+
+## From `AwsCdkApp` to `AwsCdkTypeScriptAppProject`
+
+```typescript
+// before
+import { AwsCdkApp } from "@nikovirtala/projen-aws-cdk-app";
+const project = new AwsCdkApp({ name: "my-app", cdkVersion: "2.221.0" });
+
+// after
+import { AwsCdkTypeScriptAppProject } from "@nikovirtala/projen-constructs";
+const project = new AwsCdkTypeScriptAppProject({ name: "my-app", cdkVersion: "2.221.0" });
+```
+
+Both are ES module apps using pnpm, Biome, Vitest and mise. The differences:
+
+- **Native TypeScript**: `.projenrc.ts` and the app run with `node` instead of `tsx`, and the
+  tsconfig sets `erasableSyntaxOnly` and `verbatimModuleSyntax` (see
+  [Native TypeScript](./configuration.md#native-typescript)).
+- **`nvm` is removed.** Use mise (on by default), which pins the Node.js version in `mise.toml`.
+- **Homebrew is on by default.** The project gets a `Brewfile`, and `npx projen` runs
+  `install:homebrew` (installs Homebrew if `brew` is missing) and `homebrew:bundle`. Set
+  `homebrew: false` to turn it off.
+- **cdk.json `app`** is `node src/main.ts` instead of `tsx --tsconfig tsconfig.json src/main.ts`.
+- **Defaults** come from this library: Node.js, TypeScript, CDK and pnpm versions (pnpm 12 instead
+  of 10), Dependabot off, auto-merge on, `auto-approve` and `auto-merge` labels on dependency
+  upgrade PRs, and auto-approval of PRs by `nikovirtala`. Any option you set explicitly still wins,
+  so set `autoApproveOptions` if you are not `nikovirtala`.
+- **tsconfig**: `noImplicitOverride` and `allowSyntheticDefaultImports` move from `tsconfig.json`
+  to the development tsconfig (`test/tsconfig.json`).
+- **Options removed from the interface**: `eslint`, `jest`, `prettier` (and their options),
+  `sampleCode` and `tsJestOptions`.
+- `vitestOptions` takes the `VitestOptions` of this library, and now also `homebrewOptions` and
+  `miseOptions`.