@integr8-media/config 1.0.0 → 1.1.0

package/README.md

@@ -29,9 +29,17 @@ npm install --save-dev typescript @biomejs/biome vitest @vitest/coverage-v8 tsdo
 
 ```jsonc
 // tsconfig.json
-{ "extends": "@integr8-media/config/tsconfig/react-library.json", "include": ["src"] }
+{
+  "extends": "@integr8-media/config/tsconfig/react-library.json",
+  "include": ["src"],
+  "exclude": ["**/*.config.ts", "playground/dist"]
+}
 ```
 
+`include` and `exclude` always go in the repo's own `tsconfig.json`. A preset can't carry them,
+because TypeScript resolves those paths relative to the preset file, which sits inside
+`node_modules`.
+
 | Preset | Use for |
 | --- | --- |
 | `@integr8-media/config/tsconfig/library.json` | Node or universal library: NodeNext, declarations, isolatedDeclarations |
@@ -63,10 +71,23 @@ Notes:
 - Linter: recommended rules, plus as errors: no default exports (allowed in `*.config.ts`),
   camelCase or PascalCase file names, no explicit `any`, `import type` for type-only imports,
   no non-null assertions. `console` is a warning.
-- Ignores `dist/`, `coverage/`, `playground/dist/` and Markdown files (Biome 2.6 formats
-  Markdown, which would rewrite docs such as `docs/SPEC.md`). Needs Biome 2.6 or newer.
+- Ignores `dist/`, `coverage/`, `playground/dist/`, `docs/api/` (TypeDoc output),
+  `test-results/` and `playwright-report/` (Playwright output), `.vscode/` and Markdown files
+  (Biome 2.6 formats Markdown, which would rewrite docs such as `docs/SPEC.md`). Needs Biome
+  2.6 or newer.
+- `vcs` is on (`clientKind: "git"`, `useIgnoreFile: true`), so Biome also skips everything in
+  `.gitignore`. Biome fails if there is no `.gitignore` in the folder where it runs, so every
+  repo needs one (any git repo has one already).
+- The CSS parser accepts Tailwind v4 directives (`@theme`, `@apply`, `@source`...). Repos
+  without Tailwind are not affected.
+- Overrides that turn rules off:
+  - `*.config.{ts,mts,js,mjs}`: `style.noDefaultExport`.
+  - `.size-limit.{js,mjs,ts}`: `style.noDefaultExport` and `style.useFilenamingConvention`
+    (size-limit needs a default export, and the file name starts with a dot).
+  - `playground/config.{js,mjs,ts}`: `style.noDefaultExport` (the Ladle config).
+  - `scripts/**`: `suspicious.noConsole` (build scripts print progress).
 - If your `biome.json` sets `files.includes`, Biome adds it to the preset's list, so list only
-  your extra ignores (for example `"!!.vscode"`) and don't repeat `"**"`.
+  your extra ignores (for example `"!!.idea"`) and don't repeat `"**"`.
 
 ### Vitest
 
@@ -74,12 +95,39 @@ Notes:
 // vitest.config.ts
 import { integr8Vitest } from '@integr8-media/config/vitest';
 
-export default integr8Vitest({ environment: 'node', coverageThreshold: 80 });
+export default integr8Vitest({
+  environment: 'node',
+  coverageThreshold: 80,
+  setupFiles: './test/setup.ts', // optional: string or list of strings
+});
 ```
 
 v8 coverage on `src/**` (tests, `src/index.ts` and `playground/` excluded). The run fails when
-line coverage is below the threshold. `environment: 'jsdom'` needs `jsdom` installed. To add
-your own settings, wrap it with `mergeConfig` from `vitest/config`.
+line coverage is below the threshold. `environment: 'jsdom'` needs `jsdom` installed.
+
+- `setupFiles` goes to `test.setupFiles` (for example a Testing Library setup file). It takes a
+  non-empty string or a non-empty list of non-empty strings; anything else throws
+  `ConfigError` with `INVALID_OPTION`.
+- Test collection excludes Vitest's defaults plus `playground/**`, so Playwright specs such as
+  `playground/smoke.spec.ts` are not run by `vitest run`.
+
+For settings the preset doesn't have, wrap it with `mergeConfig` from `vitest/config`:
+
+```ts
+// vitest.config.ts
+import { integr8Vitest } from '@integr8-media/config/vitest';
+import { defineConfig, mergeConfig } from 'vitest/config';
+
+export default mergeConfig(
+  integr8Vitest({ environment: 'jsdom', setupFiles: './test/setup.ts' }),
+  defineConfig({
+    test: {
+      // Process CSS files that tests import with ?raw.
+      css: { include: [/\.css$/] },
+    },
+  }),
+);
+```
 
 ### tsdown
 
@@ -100,15 +148,34 @@ dependencies stay external. Files are always named `.mjs` / `.d.mts`, so point `
 }
 ```
 
-### size-limit
+Option `unbundle?: boolean` (default `false`): with `true`, every source file is built as its own
+output file instead of one bundle. Use it for React libraries whose files start with
+`'use client'`. Each file keeps its own directive, so a Next.js server component can import the
+non-client exports from the same package. Rolldown warns `MODULE_LEVEL_DIRECTIVE` for every such
+file; with `unbundle: true` the preset hides that warning, because the directive is kept. With
+`false` the warning stays, because it is real there. A value that is not a boolean throws
+`ConfigError` with `INVALID_OPTION`.
 
 ```ts
-// .size-limit.ts
+export default integr8Tsdown({
+  entry: ['src/index.ts', 'src/Button.tsx'],
+  platform: 'browser',
+  unbundle: true,
+});
+```
+
+### size-limit
+
+```js
+// .size-limit.mjs
 import { integr8SizeLimit } from '@integr8-media/config/size-limit';
 
 export default integr8SizeLimit([{ path: 'dist/index.mjs', limit: '10 kB' }]);
 ```
 
+Use `.size-limit.mjs`: it loads without a TypeScript loader, and the Biome preset has an override
+for it (a default export and a dotted file name).
+
 Each entry takes `path`, `limit`, and optionally `name` and `import`. size-limit needs a
 plugin: `@size-limit/file` measures built files; `@size-limit/esbuild` is needed for `import`.
 
@@ -121,8 +188,22 @@ extends:
 ```
 
 - pre-commit: `biome check --write` on staged files, fixes re-staged.
-- pre-push, in order, stopping at the first failure: `typecheck`, `test:coverage`, `build`, and
-  `playground:smoke` when that script exists.
+- pre-push, in order, stopping at the first failure: `typecheck`, `test:coverage`, `build`.
+
+`playground:smoke` is not in the base: it builds the whole playground and runs Playwright, which
+is too slow for every push. A repo that wants it adds it back in its own `lefthook.yml`; the
+base's `piped: true` then runs it last:
+
+```yaml
+# lefthook.yml
+extends:
+  - node_modules/@integr8-media/config/lefthook/base.yml
+pre-push:
+  commands:
+    playground-smoke:
+      priority: 4
+      run: npm run playground:smoke
+```
 
 Add `"prepare": "lefthook install"` to your scripts so hooks are installed after `npm install`.
 
@@ -136,8 +217,9 @@ Add `"prepare": "lefthook install"` to your scripts so hooks are installed after
   "test": "vitest run",
   "test:coverage": "vitest run --coverage",
   "build": "tsdown",
-  "playground": "ladle serve",
-  "playground:smoke": "playwright test",
+  "playground": "ladle serve --config playground",
+  "playground:build": "ladle build --config playground --outDir playground/dist",
+  "playground:smoke": "npm run playground:build && playwright test",
   "size": "size-limit",
   "check:exports": "publint && attw --pack --profile esm-only"
 }
@@ -146,9 +228,14 @@ Add `"prepare": "lefthook install"` to your scripts so hooks are installed after
 `--profile esm-only` tells attw not to report the CommonJS problems that every ESM-only package
 has.
 
+A package that exports CSS files must exclude them from attw, which only knows JavaScript and
+types: `attw --pack --profile esm-only --exclude-entrypoints ./styles.css`.
+
 ### GitHub Actions
 
-The workflows live in this GitHub repo, not in the npm package. Because the repo is private, its
+The workflows live in this GitHub repo, not in the npm package. Until a `v1` tag exists, point
+callers at `@main` (`.../pr-checks.yml@main`); once it exists, switch them to `@v1`. The examples
+below show `@v1`. Because the repo is private, its
 **Settings → Actions → General → Access** must allow access from your other repositories.
 
 ```yaml
@@ -168,13 +255,14 @@ jobs:
 on:
   push:
     tags: ["v*.*.*"]
+permissions:
+  contents: read
+  id-token: write # npm Trusted Publishing
 jobs:
   publish:
     uses: <owner>/integr8-config/.github/workflows/publish.yml@v1
     with:
-      provenance: false # true only for public repos (then also grant id-token: write)
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      provenance: false # true only for public repos
 ```
 
 - `pr-checks.yml`: install, lint, typecheck, test:coverage, build, size, check:exports.
@@ -182,6 +270,27 @@ jobs:
 - `publish.yml`: checks the tag is `vX.Y.Z`, is on main and matches `package.json`; then
   install, build, test and `npm publish --access public`.
 
+#### Publishing with npm Trusted Publishing
+
+No npm token is stored in GitHub. The first version of a package has to be published by hand
+(`npm publish --access public`), because npm only offers Trusted Publishing for existing
+packages. Then, once per package:
+
+1. On npmjs.com open the package → **Settings → Trusted Publisher → GitHub Actions**.
+2. Enter the GitHub owner, the repo, and the workflow file the tag starts (`release.yml`).
+3. After one release works, set **Publishing access** to "Require two-factor authentication
+   and disallow tokens".
+
+To release: bump `version` in `package.json` by hand, merge to `main`, then push the tag:
+
+```sh
+git tag v1.0.1
+git push origin v1.0.1
+```
+
+A package without Trusted Publishing can still pass `secrets: { NPM_TOKEN: ... }` to
+`publish.yml`.
+
 ## API
 
 | Import | Exports |

package/biome/biome.json

@@ -1,6 +1,26 @@
 {
   "files": {
-    "includes": ["**", "!**/dist", "!**/coverage", "!**/playground/dist", "!**/*.md"]
+    "includes": [
+      "**",
+      "!**/dist",
+      "!**/coverage",
+      "!**/playground/dist",
+      "!**/docs/api",
+      "!**/test-results",
+      "!**/playwright-report",
+      "!**/.vscode",
+      "!**/*.md"
+    ]
+  },
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
   },
   "formatter": {
     "enabled": true,
@@ -56,6 +76,37 @@
           }
         }
       }
+    },
+    {
+      "includes": ["**/.size-limit.js", "**/.size-limit.mjs", "**/.size-limit.ts"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noDefaultExport": "off",
+            "useFilenamingConvention": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/playground/config.js", "**/playground/config.mjs", "**/playground/config.ts"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noDefaultExport": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["**/scripts/**"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noConsole": "off"
+          }
+        }
+      }
     }
   ]
 }

package/dist/tsdown.d.mts

@@ -10,19 +10,32 @@ interface Integr8TsdownOptions {
   entry: Integr8TsdownEntry;
   /** Target platform. `node` builds for `node24`; the others build for `es2024`. */
   platform: Integr8TsdownPlatform;
+  /**
+   * Build every source file as its own output file instead of one bundle. Defaults to `false`.
+   *
+   * Use it for React libraries whose files start with `'use client'`: each file is built on its
+   * own, so the directive stays on it and a Next.js server component can import the
+   * non-client exports from the same package. The preset then hides rolldown's
+   * `MODULE_LEVEL_DIRECTIVE` warning, which is only noise in that mode. With `false` the
+   * warning stays on, because there it points at a directive that the bundle drops.
+   */
+  unbundle?: boolean;
 }
 /**
  * Builds the shared tsdown config: ESM only, `.d.ts` generation (fast path through
  * isolatedDeclarations), no source maps, a clean output folder and tree-shaking.
  *
+ * With `unbundle: true` each source file becomes its own output file (see
+ * {@link Integr8TsdownOptions.unbundle}).
+ *
  * Output files always use `.mjs` and `.d.mts`, whatever the platform, so a package's
  * `exports` map is the same everywhere. Dependencies and peer dependencies stay external
  * (tsdown's default).
  *
- * @param options - Entry points and target platform.
+ * @param options - Entry points, target platform and the optional `unbundle` switch.
  * @returns A tsdown config to default-export from `tsdown.config.ts`.
- * @throws {@link ConfigError} with code `INVALID_OPTION` for an empty entry or an unknown
- * platform.
+ * @throws {@link ConfigError} with code `INVALID_OPTION` for an empty entry, an unknown
+ * platform or an `unbundle` that is not a boolean.
  *
  * @example
  * ```ts

package/dist/tsdown.mjs

@@ -9,14 +9,17 @@ const PLATFORMS = [
 * Builds the shared tsdown config: ESM only, `.d.ts` generation (fast path through
 * isolatedDeclarations), no source maps, a clean output folder and tree-shaking.
 *
+* With `unbundle: true` each source file becomes its own output file (see
+* {@link Integr8TsdownOptions.unbundle}).
+*
 * Output files always use `.mjs` and `.d.mts`, whatever the platform, so a package's
 * `exports` map is the same everywhere. Dependencies and peer dependencies stay external
 * (tsdown's default).
 *
-* @param options - Entry points and target platform.
+* @param options - Entry points, target platform and the optional `unbundle` switch.
 * @returns A tsdown config to default-export from `tsdown.config.ts`.
-* @throws {@link ConfigError} with code `INVALID_OPTION` for an empty entry or an unknown
-* platform.
+* @throws {@link ConfigError} with code `INVALID_OPTION` for an empty entry, an unknown
+* platform or an `unbundle` that is not a boolean.
 *
 * @example
 * ```ts
@@ -29,6 +32,8 @@ function integr8Tsdown(options) {
 	if (typeof options !== "object" || options === null) throw new ConfigError("INVALID_OPTION", "integr8Tsdown: options are required.");
 	const { platform } = options;
 	if (!PLATFORMS.includes(platform)) throw new ConfigError("INVALID_OPTION", `integr8Tsdown: "platform" must be one of ${PLATFORMS.join(", ")}; got ${String(platform)}.`);
+	const { unbundle = false } = options;
+	if (typeof unbundle !== "boolean") throw new ConfigError("INVALID_OPTION", `integr8Tsdown: "unbundle" must be a boolean; got ${String(unbundle)}.`);
 	return {
 		entry: copyEntry(options.entry),
 		platform,
@@ -38,9 +43,17 @@ function integr8Tsdown(options) {
 		dts: true,
 		sourcemap: false,
 		clean: true,
-		treeshake: true
+		treeshake: true,
+		...unbundle ? {
+			unbundle: true,
+			inputOptions: { onLog: dropDirectiveWarning }
+		} : {}
 	};
 }
+function dropDirectiveWarning(...[level, log, defaultHandler]) {
+	if (log.code === "MODULE_LEVEL_DIRECTIVE") return;
+	defaultHandler(level, log);
+}
 function copyEntry(entry) {
 	if (typeof entry === "string") {
 		if (entry.trim() === "") throw invalidEntry();

package/dist/vitest.d.mts

@@ -8,15 +8,22 @@ interface Integr8VitestOptions {
   environment?: Integr8VitestEnvironment;
   /** Minimum line coverage in percent (0–100). Defaults to `80`. */
   coverageThreshold?: number;
+  /**
+   * Setup file(s) run before each test file, passed to `test.setupFiles` (for example
+   * `'./test/setup.ts'` for Testing Library). Non-empty strings only.
+   */
+  setupFiles?: string | string[];
 }
 /**
  * Builds the shared Vitest config: v8 coverage on `src/**` (tests, `src/index.ts` and
- * `playground/` excluded) that fails when line coverage is below the threshold.
+ * `playground/` excluded) that fails when line coverage is below the threshold. Test collection
+ * skips `playground/**` too, so Playwright specs there are not run by Vitest.
  *
- * @param options - Environment and coverage threshold.
+ * @param options - Environment, coverage threshold and setup files.
  * @returns A Vitest config to default-export from `vitest.config.ts`.
  * @throws {@link ConfigError} with code `INVALID_OPTION` for an unknown environment or a
- * threshold outside 0–100.
+ * threshold outside 0–100, or for `setupFiles` that is not a non-empty string or a non-empty
+ * list of non-empty strings.
  *
  * @example
  * ```ts

package/dist/vitest.mjs

@@ -1,15 +1,18 @@
 import { t as ConfigError } from "./configError-Cap5gwBB.mjs";
+import { configDefaults } from "vitest/config";
 // src/vitest/integr8Vitest.ts
 const ENVIRONMENTS = ["node", "jsdom"];
 const DEFAULT_COVERAGE_THRESHOLD = 80;
 /**
 * Builds the shared Vitest config: v8 coverage on `src/**` (tests, `src/index.ts` and
-* `playground/` excluded) that fails when line coverage is below the threshold.
+* `playground/` excluded) that fails when line coverage is below the threshold. Test collection
+* skips `playground/**` too, so Playwright specs there are not run by Vitest.
 *
-* @param options - Environment and coverage threshold.
+* @param options - Environment, coverage threshold and setup files.
 * @returns A Vitest config to default-export from `vitest.config.ts`.
 * @throws {@link ConfigError} with code `INVALID_OPTION` for an unknown environment or a
-* threshold outside 0–100.
+* threshold outside 0–100, or for `setupFiles` that is not a non-empty string or a non-empty
+* list of non-empty strings.
 *
 * @example
 * ```ts
@@ -23,8 +26,11 @@ function integr8Vitest(options = {}) {
 	const coverageThreshold = options.coverageThreshold ?? DEFAULT_COVERAGE_THRESHOLD;
 	if (!ENVIRONMENTS.includes(environment)) throw new ConfigError("INVALID_OPTION", `integr8Vitest: "environment" must be one of ${ENVIRONMENTS.join(", ")}; got ${String(environment)}.`);
 	if (typeof coverageThreshold !== "number" || !Number.isFinite(coverageThreshold) || coverageThreshold < 0 || coverageThreshold > 100) throw new ConfigError("INVALID_OPTION", `integr8Vitest: "coverageThreshold" must be a number from 0 to 100; got ${String(coverageThreshold)}.`);
+	const setupFiles = copySetupFiles(options.setupFiles);
 	return { test: {
 		environment,
+		exclude: [...configDefaults.exclude, "playground/**"],
+		...setupFiles === void 0 ? {} : { setupFiles },
 		coverage: {
 			provider: "v8",
 			include: ["src/**/*.{ts,tsx}"],
@@ -39,4 +45,13 @@ function integr8Vitest(options = {}) {
 		}
 	} };
 }
+function copySetupFiles(setupFiles) {
+	if (setupFiles === void 0) return;
+	if (isNonEmptyString(setupFiles)) return setupFiles;
+	if (Array.isArray(setupFiles) && setupFiles.length > 0 && setupFiles.every(isNonEmptyString)) return [...setupFiles];
+	throw new ConfigError("INVALID_OPTION", "integr8Vitest: \"setupFiles\" must be a non-empty path or a non-empty list of non-empty paths.");
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
 export { ConfigError, integr8Vitest };

package/lefthook/base.yml

@@ -23,6 +23,3 @@ pre-push:
     build:
       priority: 3
       run: npm run build
-    playground-smoke:
-      priority: 4
-      run: npm run playground:smoke --if-present

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integr8-media/config",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Shared tooling presets for every @integr8-media repo: TypeScript, Biome, Vitest, tsdown, Lefthook and size-limit.",
   "license": "MIT",
   "author": "Mina Louis Leon",