@doikayt/typescript-build-config 0.1.15 → 0.1.16

package/README.md

@@ -111,33 +111,41 @@ small single-purpose scripts, and the check side mirrors the write side:
 | --- | --- |
 | `ci` | The release gate: `check-all-format` then `test` (plus `test:e2e` for UI). |
 | `build` | Compile TypeScript to `dist/` (`tsc`). |
-| `prepack` | Runs `build` before packing, so `changeset publish` ships compiled `dist/`. |
 | `test` | Unit / integration tests (`vitest run`). |
 | `test:e2e` | End-to-end tests (`playwright test`) — UI projects only. |
+| `prepack` | Runs `build` before packing, so `changeset publish` ships compiled `dist/` — **libraries only**. |
 | `update-all-format` | Reformat everything: code + markdown docs (write). |
 | `check-all-format` | Verify formatting: code + markdown docs (used by `ci`). |
 | `update-code-formatting` / `check-code-formatting` | Prettier write / check. |
 | `update-markdown-docs` / `check-markdown-docs` | Regenerate / verify generated markdown (TOC, UML, …). |
 
-Alongside the scripts, `init` sets the publish config a fresh package needs —
-`type: "module"`, `main` / `types` / `exports` pointing at `dist/index.js`, and
-`files: ["dist"]` — each only if you have not already set it. Combined with
-`prepack`, a brand-new project builds and publishes a compiled, typed ESM
-package on push with no extra wiring.
+`init` also asks whether the project is a **publishable library**, which sets the
+publish config accordingly (non-destructively):
+
+- **Library** — `main` / `types` / `exports` → `dist/index.js`, `files: ["dist"]`,
+  and `prepack`, so it publishes a compiled, typed ESM package on push.
+- **App / CLI** (the default) — marked `private: true`, so a release versions and
+  tags it but never publishes to npm.
+
+`type: "module"` and `build` are set either way. New to these terms (compiled
+`dist/`, publish fields, library vs app)? See
+[Packaging concepts](docs/packaging-concepts.md) for the background.
 
 ### Console / CLI project
 
 ```bash
 npm init -y                                            # if starting fresh
 npm install --save-dev @doikayt/typescript-build-config
-npx @doikayt/typescript-build-config init             # answer "n" to the Playwright prompt
+npx @doikayt/typescript-build-config init             # answer "n" to Playwright; "n" (app) or "y" (library)
 npm install                                            # fetch the declared devDependencies
 ```
 
 `init` writes the canonical scripts (`ci`, `build`, `test`, `update-all-format`,
-`check-all-format`, `prepack`, and their sub-tasks), sets the `dist/`-based
-publish config, declares `vitest` + `@doikayt/autogen-markdown-doc` +
-`typescript`, and seeds a commented `vitest.config.ts`.
+`check-all-format`, and their sub-tasks), declares `vitest` +
+`@doikayt/autogen-markdown-doc` + `typescript`, and seeds a commented
+`vitest.config.ts`. Answering the "publishable library?" prompt sets the publish
+config — `private` for an app, or `prepack` + the `dist/`-based fields for a
+library (see [The canonical script set](#the-canonical-script-set)).
 
 ### UI / web project (with Playwright e2e)
 
@@ -496,6 +504,10 @@ To auto-fix formatting before verifying:
 npm run update-all-format && npm run ci
 ```
 
+To verify end-to-end that `init` scaffolds and ships both a library and an app —
+by hand, with what to look for at each step — follow
+[docs/e2e-verification.md](docs/e2e-verification.md).
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doikayt/typescript-build-config",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Shared build configuration for TypeScript projects — ESLint, Prettier, tsconfig, and Playwright presets",
   "_comments": {
     "exports": "This block lists the config files that will be extended by files in in src/toplevel - which are copied to consuming project root folder. An example: eslint.config.js imports from '@doikayt/typescript-build-config/eslint'.",

package/src/canonical-scripts.js

@@ -1,10 +1,11 @@
 // The canonical npm-script set init writes into every consumer. package.json is
 // the single source of truth (it is always present); NX projects, if any, add
-// thin targets that delegate to `npm run <x>` — never the reverse. So this set
-// is identical regardless of orchestrator; only the UI/console distinction
-// changes it (Playwright e2e).
+// thin targets that delegate to `npm run <x>` — never the reverse. Two axes vary
+// the set: UI/console (Playwright e2e) and library/app. `build` is universal
+// (both archetypes compile); only a publishable library adds `prepack`, which
+// builds dist/ at publish time so `changeset publish` ships compiled output.
 
-export function canonicalScripts({ ui = false } = {}) {
+export function canonicalScripts({ ui = false, library = false } = {}) {
   const ci = ui
     ? "npm run check-all-format && npm run test && npm run test:e2e"
     : "npm run check-all-format && npm run test";
@@ -21,12 +22,10 @@ export function canonicalScripts({ ui = false } = {}) {
       "npm run check-code-formatting && npm run check-markdown-docs",
     "check-code-formatting": "prettier --check src/",
     "check-markdown-docs": "autogen-markdown-doc check",
-    // Build at publish time so `changeset publish` ships compiled dist/ without
-    // the release workflow needing a build step.
-    prepack: "npm run build",
   };
 
   if (ui) scripts["test:e2e"] = "doikayt-playwright-install && playwright test";
+  if (library) scripts.prepack = "npm run build";
 
   return scripts;
 }
@@ -37,21 +36,26 @@ export function devDependencyNames({ ui = false } = {}) {
   return names;
 }
 
-// Top-level package.json fields init sets (non-destructively) so a fresh project
-// builds to dist/ and publishes a compiled, importable ESM package. Assumes the
-// canonical src/index.ts entry point; a consumer that wants a different shape
-// sets these first and init leaves them untouched.
-export function packageFields() {
-  return {
-    type: "module",
-    main: "dist/index.js",
-    types: "dist/index.d.ts",
-    exports: {
+// Top-level package.json fields init sets (non-destructively). `type: "module"`
+// is universal. A publishable **library** also gets the dist/-based entry points
+// (main/types/exports) and the tarball allow-list (files), assuming the canonical
+// src/index.ts entry. An **app** is instead marked `private` so `changeset
+// publish` never publishes it — its release is a version bump + tag only. Either
+// way, fields a consumer already set are left untouched by the caller.
+export function packageFields({ library = false } = {}) {
+  const fields = { type: "module" };
+  if (library) {
+    fields.main = "dist/index.js";
+    fields.types = "dist/index.d.ts";
+    fields.exports = {
       ".": {
         types: "./dist/index.d.ts",
         default: "./dist/index.js",
       },
-    },
-    files: ["dist"],
-  };
+    };
+    fields.files = ["dist"];
+  } else {
+    fields.private = true;
+  }
+  return fields;
 }

package/src/init.js

@@ -66,13 +66,18 @@ export async function runInit({
     "Is this a UI project that needs Playwright (e2e)? [y/N] ",
   );
 
-  const scripts = canonicalScripts({ ui });
+  const library = await prompt(
+    "Is this a publishable library (published to npm)? Apps/CLIs answer No and\n" +
+      "are marked private so they are never published. [y/N] ",
+  );
+
+  const scripts = canonicalScripts({ ui, library });
   const devDependencies = resolveDevVersions(devDependencyNames({ ui }));
 
   const { text, added, skipped } = applyToPackageJson(raw, {
     scripts,
     devDependencies,
-    fields: packageFields(),
+    fields: packageFields({ library }),
   });
   writeFileSync(pkgPath, text);
 
@@ -111,7 +116,7 @@ export async function runInit({
 async function maybeScaffoldDemo({ cwd, prompt, log }) {
   const wantDemo = await prompt(
     "Scaffold a starter demo (minimal src module + README + project.json) so you\n" +
-      "can build, test, and publish immediately? Existing files are never\n" +
+      "can build, test, and release immediately? Existing files are never\n" +
       "overwritten. [y/N] ",
   );
   if (!wantDemo) {

package/src/templates/demo/README.md

@@ -38,5 +38,5 @@ Mermaid diagrams inline from the fenced blocks.
 npm install                 # fetch the dev deps init declared
 npm test                    # the seeded vitest test passes
 npm run update-all-format   # fills the doc blocks above
-git commit -am "feat: initial version" && git push   # feat:/fix: trigger a publish
+git commit -am "feat: initial version" && git push   # feat:/fix: cut a release (npm publish if a library)
 ```