@icebreakers/monorepo-templates 1.2.0 → 1.3.0

package/templates/vitepress/tools/pnpm.md

@@ -1,15 +1,47 @@
 # pnpm
 
-pnpm owns workspace discovery, dependency installation, script execution, and versioning configuration.
+pnpm is the package manager used by repoctl workspaces. Its workspace protocol, content-addressable store, and filter syntax make it a practical fit for repositories with several packages and applications.
+
+## Install dependencies
 
 ```bash
 pnpm install
-pnpm --filter <package> build
-pnpm -r test
-pnpm change
-pnpm change status
+pnpm install --frozen-lockfile
 ```
 
-`pnpm-workspace.yaml` is the source of truth for package patterns and release groups. repoctl can diagnose missing patterns and synchronize recommended defaults, but pnpm remains the package manager.
+Use the frozen form in CI. It proves that `package.json` files and the lockfile describe the same dependency graph.
+
+## Work with one workspace
+
+```bash
+pnpm --filter repoctl build
+pnpm --filter @icebreakers/monorepo test
+pnpm --filter './packages/*' lint
+```
+
+Filters are a routing tool, not a replacement for repository scripts. Prefer an existing package script over an ad hoc command when a task should be repeatable.
+
+## Link local packages
+
+```json
+{
+  "dependencies": {
+    "@icebreakers/monorepo": "workspace:*"
+  }
+}
+```
+
+The `workspace:` protocol prevents accidentally resolving a local package from the public registry during development.
+
+## Operational guidance
+
+- Pin the package manager in the root `package.json`.
+- Commit `pnpm-lock.yaml` for applications and monorepos.
+- Use `pnpm exec` for binaries supplied by the current workspace.
+- Use `pnpm --filter` for a scoped package command and Turbo for graph-wide task orchestration.
+
+## Keep Reading
 
-Prefer exact workspace filters in automation and keep `packageManager` plus `engines.node` declared at the repository root.
+- [Turborepo](./turborepo.md)
+- [Managing A Monorepo](../monorepo/manage.md)
+- [repoctl Commands](../repoctl/commands.md)

package/templates/vitepress/tools/renovate.md

@@ -1,7 +1,31 @@
 # Renovate
 
-Renovate opens dependency update pull requests according to repository policy.
+Renovate keeps dependencies current through reviewable pull requests. It is most useful when the configuration groups compatible updates, lets CI prove the upgrade, and avoids mixing unrelated ecosystem changes.
 
-Group related tooling updates, respect pnpm workspace constraints, and let the normal build, lint, typecheck, tsd, and test matrix validate each update. Avoid combining unrelated runtime and tooling upgrades when separate review makes regressions easier to isolate.
+## Repository policy
 
-repoctl does not replace Renovate. It provides the diagnostic and verification commands that Renovate pull requests can run consistently.
+```json
+{
+  "extends": ["config:recommended", "group:allNonMajor"],
+  "rangeStrategy": "bump",
+  "automerge": true,
+  "automergeType": "pr"
+}
+```
+
+The repository groups compatible minor and patch updates. Cloudflare Workers tooling is grouped separately because Wrangler and its Vite plugin have a deliberate compatibility relationship.
+
+## Review an update
+
+1. Read the package release notes when the update changes build, test, or deployment tooling.
+2. Run the normal build and validation sequence against the updated lockfile.
+3. Check generated assets and package metadata for unexpected churn.
+4. Merge only after the configured checks prove the update is compatible.
+
+Do not rely on commit-message directives for a retired deployment provider. Deployment behavior belongs in the active platform configuration and CI settings.
+
+## Keep Reading
+
+- [pnpm](./pnpm.md)
+- [Workflows and CI](../repoctl/workflows.md)
+- [Troubleshooting](../repoctl/troubleshooting.md)

package/templates/vitepress/tools/turborepo.md

@@ -1,14 +1,40 @@
 # Turborepo
 
-Turborepo runs the monorepo task graph and caches repeatable work.
+Turborepo turns package scripts into a dependency-aware task graph. repoctl workspaces use it for the repository-wide work that should be cached and run in dependency order.
+
+## Define task boundaries
+
+```json
+{
+  "tasks": {
+    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
+    "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] },
+    "typecheck": { "dependsOn": ["^typecheck"], "outputs": [] }
+  }
+}
+```
+
+`^build` means that a package must build its workspace dependencies before its own build starts. Declare outputs accurately so the cache can restore useful artifacts and ignore transient files.
+
+## Run graph-aware tasks
 
 ```bash
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm test
+pnpm turbo run build
+pnpm turbo run test --filter=repoctl
+pnpm turbo run lint typecheck
 ```
 
-Root scripts delegate to `turbo run`. Package scripts define the actual build, lint, typecheck, and test commands; `turbo.json` defines dependencies, inputs, outputs, and cache behavior.
+Use root scripts for the common entrypoints. The root script is the stable command people and CI should remember; Turbo remains the graph executor beneath it.
+
+## Cache with care
+
+- Include configuration files that materially affect output in task inputs.
+- Keep secrets out of cached output.
+- Set `outputs: []` for validation-only tasks.
+- Use `--force` only when diagnosing cache behavior.
+
+## Keep Reading
 
-Mark generated artifacts as task outputs and declare upstream dependencies such as `build` before tests that consume built packages.
+- [pnpm](./pnpm.md)
+- [Verification](../repoctl/checks.md)
+- [Managing A Monorepo](../monorepo/manage.md)

package/templates/vitepress/tsconfig.json

@@ -9,6 +9,13 @@
     "skipLibCheck": true
   },
   "include": [
+    ".vitepress/home/**/*.ts",
+    ".vitepress/navigation/**/*.ts",
+    ".vitepress/seo.ts",
+    ".vitepress/theme/**/*.ts",
+    ".vitepress/theme/**/*.vue",
+    ".vitepress/env.d.ts",
+    "scripts/**/*.ts",
     "why/examples/2.npm-basic-package/src/**/*.ts",
     "why/examples/3.npm-basic-package/src/**/*.ts"
   ]

package/templates/vitepress/why/examples/2.npm-basic-package/README.md

@@ -1 +1 @@
-https://repo.icebreaker.top/
+https://repoctl.icebreaker.top/

package/templates/vitepress/why/examples/3.npm-basic-package/README.md

@@ -1 +1 @@
-https://repo.icebreaker.top/
+https://repoctl.icebreaker.top/

package/templates/vitepress/why/how-to-reuse-js-code.md

@@ -1,9 +1,39 @@
-# Reusing JavaScript Code
+# Reusing JavaScript
 
-JavaScript code can be shared through source modules, workspace packages, or published npm packages. The right boundary depends on ownership and consumers.
+Reuse source code through an explicit package boundary. Copying files between applications is fast once and expensive every time the shared behavior changes; a local workspace package makes ownership, versioning, and tests visible.
 
-- Use a local module for code owned by one package.
-- Use a workspace package when multiple projects in the same repository share versioned behavior.
-- Publish an npm package when external repositories need a stable public API.
+## Start with a workspace package
 
-In a pnpm workspace, declare internal dependencies with the `workspace:` protocol and let the package build produce explicit runtime and type entrypoints.
+```json
+{
+  "dependencies": {
+    "@example/shared": "workspace:*"
+  }
+}
+```
+
+The workspace protocol uses the local package during development and protects the repository from accidentally resolving an unrelated registry version.
+
+## Export a narrow API
+
+```ts
+export function normalizeName(value: string) {
+  return value.trim().toLowerCase()
+}
+```
+
+Keep the public entry point small. A shared package should expose behavior that has a real consumer, not a collection of unrelated helpers that happen to be nearby.
+
+## Choose the right reuse level
+
+| Need                         | Better boundary                        |
+| ---------------------------- | -------------------------------------- |
+| Shared runtime behavior      | A versioned package                    |
+| Shared build and lint policy | A preset package or managed asset      |
+| Shared application feature   | A feature package with clear ownership |
+| One-off project setup        | A template, not a dependency           |
+
+## Keep Reading
+
+- [What Is An npm Package?](./what-is-npm-package.md)
+- [Template Systems](../monorepo/templates.md)

package/templates/vitepress/why/js-cjs-mjs.md

@@ -1,12 +1,34 @@
-# JavaScript Module Extensions
+# JavaScript, CommonJS, and ESM Files
 
-Node.js uses file extensions and the nearest `package.json` `type` field to determine module format.
+File extensions tell Node which module loader should read a file. Use them deliberately when a package publishes both module formats or when a script must work independently of the nearest `package.json`.
 
-| Extension       | Meaning                                       |
-| --------------- | --------------------------------------------- |
-| `.mjs`          | Always ES module                              |
-| `.cjs`          | Always CommonJS                               |
-| `.js`           | Depends on `package.json` `type`              |
-| `.mts` / `.cts` | TypeScript source with explicit module intent |
+## Extension rules
 
-For published libraries, make the package `exports` map explicit and test both import and require paths when both formats are supported.
+| Extension | Module format                                         |
+| --------- | ----------------------------------------------------- |
+| `.mjs`    | ESM in every package                                  |
+| `.cjs`    | CommonJS in every package                             |
+| `.js`     | Determined by the nearest `package.json` `type` field |
+
+```json
+{
+  "type": "module"
+}
+```
+
+With this declaration, `.js` files are ESM. Use `.cjs` for CommonJS output such as a compatibility build or an older tooling configuration file.
+
+## Avoid ambiguous output
+
+```text
+dist/index.js     ESM output
+dist/index.cjs    CommonJS output
+dist/index.d.ts   Type declarations
+```
+
+Connect these files through `exports`; do not ask consumers to infer a `dist` layout. A clear output layout also makes package tarball checks easier.
+
+## Keep Reading
+
+- [ESM vs CommonJS](./modern/esm-vs-cjs.md)
+- [Package Entry Points](./modern/package-entry-points.md)

package/templates/vitepress/why/js-keywords.md

@@ -1,7 +1,36 @@
-# ESM and CommonJS Runtime Globals
+# JavaScript Runtime Keywords
 
-CommonJS provides `require`, `module`, `exports`, `__filename`, and `__dirname`. ES modules use `import`, `export`, `import.meta.url`, and `createRequire` when interoperability is required.
+Modern JavaScript modules have different runtime globals depending on whether Node loads them as CommonJS or ESM. Know the boundary before copying code between build tools, scripts, and package entry points.
 
-Avoid assuming CommonJS globals exist inside ESM. Resolve file paths with `fileURLToPath(import.meta.url)` and prefer static imports so bundlers and type checkers can understand dependencies.
+## CommonJS values
 
-See [ESM vs CommonJS](./modern/esm-vs-cjs.md) for package-level guidance.
+```js
+console.log(__filename)
+console.log(__dirname)
+console.log(require.main)
+```
+
+These values are available in CommonJS modules. They are not automatically present in ESM files.
+
+## ESM equivalents
+
+```js
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+```
+
+Use `import.meta.url` as the starting point for resolving files relative to an ESM module. Prefer explicit Node built-in imports such as `node:path` so bundlers and readers can identify runtime-only dependencies.
+
+## Keep code portable
+
+- Keep filesystem access behind a small module when browser builds share source code.
+- Do not use CommonJS globals in a package that declares `type: module`.
+- Test generated ESM and CommonJS outputs independently when both are published.
+
+## Keep Reading
+
+- [JavaScript, CommonJS, and ESM Files](./js-cjs-mjs.md)
+- [Reusing JavaScript](./how-to-reuse-js-code.md)

package/templates/vitepress/why/modern/bundlers.md

@@ -1,5 +1,40 @@
 # Bundlers
 
-Library bundlers turn source modules into publishable runtime and declaration artifacts. The repository's TypeScript library asset uses [tsdown](https://github.com/sonofmagic/repoctl/tree/main/templates/tsdown), while the Vue library asset adds Vue-specific build and type checking.
+Choose a bundler by the package boundary you need to ship. A library build needs reliable entry points and declarations; a component library also needs framework and CSS handling; an application build needs an optimized browser bundle.
 
-Configure entrypoints, external dependencies, output formats, source maps, and declarations according to the package contract. Applications and libraries have different goals: application builds optimize deployment; library builds preserve reusable public boundaries.
+## Current choices
+
+| Tool       | Good fit                                        | Notes                                             |
+| ---------- | ----------------------------------------------- | ------------------------------------------------- |
+| `tsdown`   | TypeScript libraries and tooling                | Produces modern library output with declarations  |
+| `vite`     | Applications and component libraries            | Strong development server and library mode        |
+| `rolldown` | Toolchains that need Rollup-compatible behavior | Evaluate ecosystem compatibility before migration |
+
+The repoctl generic library template uses `tsdown`. Vue component libraries continue to use Vite library mode.
+
+## tsdown library configuration
+
+:::code-group
+
+```ts [tsdown.config.ts]
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  clean: true,
+  target: 'node18',
+})
+```
+
+:::
+
+## Retired defaults
+
+`tsup` and `unbuild` are not recommended for new repoctl templates. Existing projects can migrate when their build behavior and published artifacts are covered by tests. Do not rewrite a working package merely to follow a tooling trend.
+
+## Keep Reading
+
+- [TypeScript](./typescript.md)
+- [Package Entry Points](./package-entry-points.md)

package/templates/vitepress/why/modern/dts.md

@@ -1,7 +1,48 @@
 # Type Declarations
 
-Type declarations are part of a TypeScript package's public API.
+Type declarations describe the public TypeScript contract of a JavaScript package. They must be generated from the same source and exported through the same public entry points as the runtime code.
 
-Generate `.d.ts` files from the same source revision as runtime output, point `types` and export conditions at files included in the tarball, and use `tsd` tests for important inference and error behavior.
+## Emit declarations
 
-Declaration bundling can simplify public output, but it must preserve module augmentation, generics, and referenced types. Always inspect the packed artifact rather than testing source imports alone.
+```json
+{
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "outDir": "./dist"
+  }
+}
+```
+
+Bundlers such as tsdown can emit declaration files alongside runtime output. The important rule is that declaration paths are stable and match the package exports map.
+
+## Link types to exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  }
+}
+```
+
+The top-level `types` field is useful for simple packages. Per-entry `types` declarations are necessary when a package exposes subpaths or format-specific output.
+
+## Test the public contract
+
+```bash
+pnpm tsd
+pnpm pack --dry-run
+```
+
+Type tests should import from the package name, not a source file. That proves the declarations consumers receive are compatible with the documented API.
+
+## Keep Reading
+
+- [Package Entry Points](./package-entry-points.md)
+- [TypeScript](./typescript.md)

package/templates/vitepress/why/modern/esm-vs-cjs.md

@@ -1,7 +1,42 @@
 # ESM vs CommonJS
 
-ES modules are the preferred format for new packages. CommonJS remains relevant when consumers or toolchains still require `require()`.
+Node supports two JavaScript module systems. ESM uses `import` and `export`; CommonJS uses `require` and `module.exports`. A package can support both, but it must state how each consumer reaches the correct file.
 
-Choose ESM-only when your supported runtime matrix allows it. Publish dual formats only when the compatibility benefit justifies duplicate builds and interop testing.
+## Identify the format
 
-For dual packages, map `import`, `require`, and `types` conditions explicitly and test each consumer path. Avoid exporting different logical module instances from the two formats.
+| Signal                          | Meaning             |
+| ------------------------------- | ------------------- |
+| `.mjs`                          | Always ESM          |
+| `.cjs`                          | Always CommonJS     |
+| `.js` with `"type": "module"`   | ESM                 |
+| `.js` without that package type | CommonJS by default |
+
+Avoid guessing from syntax alone. Node resolves a `.js` file from its extension and the nearest package boundary.
+
+## Publish both formats
+
+```json
+{
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  }
+}
+```
+
+Use an exports map rather than asking consumers to reach into `dist`. It gives each module system an intentional entry point and prevents accidental private imports becoming a public API.
+
+## Interoperability rules
+
+- Keep the package API identical across formats where possible.
+- Test both `import` and `require` from a consumer fixture.
+- Do not publish TypeScript source as the runtime entry point.
+- Use `.cjs` for CommonJS output when the package itself declares `type: module`.
+
+## Keep Reading
+
+- [Package Entry Points](./package-entry-points.md)
+- [Type Declarations](./dts.md)

package/templates/vitepress/why/modern/index.md

@@ -1,14 +1,38 @@
 # Modern Package Guide
 
-Modern packages should expose a small, explicit API and generate artifacts that match their declared contract.
+A publishable package is more than a source folder. Consumers depend on its runtime format, type declarations, entry points, files list, and compatibility policy. This guide explains the decisions that keep those contracts explicit.
 
-## Checklist
+## Start with the consumer
 
-- Choose ESM-only or intentional dual-package support.
-- Declare every public subpath in `exports`.
-- Emit and test type declarations.
-- Keep development-only files out of the package tarball.
-- Validate the supported Node and bundler matrix.
-- Record public changes through repository versioning.
+Before choosing a bundler or module format, answer these questions:
 
-Start with [ESM vs CommonJS](./esm-vs-cjs.md), then review [entry points](./package-entry-points.md) and [declarations](./dts.md).
+- Will consumers load the package through ESM, CommonJS, or both?
+- Does the package ship runtime code, types, a CLI, or generated assets?
+- Which Node versions must work?
+- Should consumers import one public entry point or several intentional subpaths?
+
+The answers define the package boundary. Tooling should implement that boundary, not invent it.
+
+## Recommended shape
+
+```text
+src/          source code
+dist/         generated ESM, CommonJS, and declaration files
+package.json  public metadata and exports map
+README.md     installation and usage contract
+```
+
+Use `files` to publish only the built output and deliberately included documentation. Run `npm pack --dry-run` before publishing to inspect the actual package tarball.
+
+## Topics
+
+- [ESM vs CommonJS](./esm-vs-cjs.md)
+- [Type Declarations](./dts.md)
+- [Package Entry Points](./package-entry-points.md)
+- [Bundlers](./bundlers.md)
+- [TypeScript](./typescript.md)
+
+## Keep Reading
+
+- [What Is An npm Package?](../what-is-npm-package.md)
+- [Publishing A Package](../publish-basic-npm-package.md)

package/templates/vitepress/why/modern/package-entry-points.md

@@ -1,17 +1,46 @@
 # Package Entry Points
 
-Use the `exports` field to define the package's supported public paths.
+The `exports` field is the public map of a package. It selects files for ESM, CommonJS, types, and intentional subpath imports while preventing consumers from coupling to internal folders.
+
+## Define one primary entry
 
 ```json
 {
+  "name": "example-package",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  }
+}
+```
+
+Consumers can now use `import { feature } from 'example-package'` or `require('example-package')` without knowing your output layout.
+
+## Add a deliberate subpath
+
+```json
+{
+  "exports": {
+    ".": "./dist/index.js",
+    "./cli": "./dist/cli.js",
     "./package.json": "./package.json"
   }
 }
 ```
 
-Do not rely on consumers reaching into undeclared internal files. Every exported path should have runtime output, types where applicable, and a compatibility test.
+Each subpath is a public promise. Add one only when it has a stable purpose, documentation, and tests. Do not expose `./dist/*` as a shortcut around API design.
+
+## Verify consumers
+
+- Test the root import and every documented subpath.
+- Verify both ESM and CommonJS branches when both are published.
+- Check `npm pack --dry-run` includes every exported file.
+- Treat removing or changing a public subpath as a breaking change.
+
+## Keep Reading
+
+- [ESM vs CommonJS](./esm-vs-cjs.md)
+- [Type Declarations](./dts.md)

package/templates/vitepress/why/modern/typescript.md

@@ -1,7 +1,43 @@
-# TypeScript Packages
+# TypeScript
 
-Use TypeScript to validate source and to publish a precise consumer contract.
+TypeScript gives a package one source language for implementation and public types. Build output should remain JavaScript plus declarations so consumers do not need your development compiler configuration.
 
-Keep the source typecheck separate from artifact generation, enable strict settings appropriate for libraries, and avoid path aliases that cannot be resolved by consumers. Vue packages should run `vue-tsc`; non-Vue TypeScript packages should run `tsc`.
+## Start with a strict package config
 
-Public type behavior belongs in `tsd` tests. Runtime tests should import built output so module resolution matches delivery.
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+```
+
+Use a separate configuration only when an output format genuinely needs different compiler behavior. Prefer a bundler configuration for output strategy and keep the TypeScript configuration focused on source checking and declaration generation.
+
+## Build and test from artifacts
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm tsd
+```
+
+Run type tests against the generated package contract. A source-only test can pass while the published declaration path or exports map is broken.
+
+## Runtime execution
+
+For local scripts, `tsx` can run TypeScript without creating a development `dist` directory. That is convenient for tooling, but it is not a replacement for building libraries before testing the package that consumers install.
+
+## Keep Reading
+
+- [Type Declarations](./dts.md)
+- [Bundlers](./bundlers.md)
+- [Publishing A Package](../publish-basic-npm-package.md)

package/templates/vitepress/why/publish-basic-npm-package.md

@@ -1,19 +1,43 @@
-# Publishing An npm Package
+# Publishing A Package
 
-1. Define explicit runtime and type entrypoints.
-2. Build the package and run tests against built artifacts.
-3. Inspect `pnpm pack` output.
-4. Record a change intent and verify the version plan.
-5. Publish with provenance and the intended access level.
+Publishing is the point where the repository's package contract becomes public. Build first, test the built artifacts, inspect the tarball, and publish only after the version intent and changelog describe the consumer-visible change.
+
+## Prepare the package
+
+```bash
+pnpm --filter example-package build
+pnpm --filter example-package typecheck
+pnpm --filter example-package test
+pnpm --filter example-package tsd
+pnpm --filter example-package pack --pack-destination ../../artifacts
+```
+
+Run the package commands against generated output where possible. A source-only test does not prove that `exports`, files, or declarations will resolve after installation.
+
+## Verify package metadata
+
+```json
+{
+  "name": "example-package",
+  "version": "1.0.0",
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" }
+}
+```
+
+Use `npm pack --dry-run` to see what users receive. Confirm the runtime entry point, declaration files, README, and license are present.
+
+## Release through the repository workflow
 
 ```bash
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm tsd
-pnpm test
-pnpm pack
 pnpm change
+pnpm version -r
+pnpm publish -r
 ```
 
-Never publish template source workspaces that are intentionally marked `private: true`.
+The version ledger preserves why the release exists. Do not manually edit a package version to bypass fixed-group or changelog rules.
+
+## Keep Reading
+
+- [pnpm Versioning](../tools/changeset.md)
+- [Modern Package Guide](./modern/)