@integr8-media/config 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mina Louis Leon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,331 @@
-# Temporary Holding Version
+# @integr8-media/config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared tooling presets for every `@integr8-media` repo: TypeScript, Biome, Vitest, tsdown, Lefthook,
+size-limit and publint, plus reusable GitHub Actions workflows. No runtime code.
+
+The full spec is in [docs/SPEC.md](docs/SPEC.md).
+
+## Requirements
+
+- Node 24 LTS
+- TypeScript 5.7 or newer (the presets target ES2024, which TypeScript added in 5.7)
+
+## Install
+
+```sh
+npm install --save-dev @integr8-media/config
+```
+
+Then install the tools you use (all are optional peer dependencies):
+
+```sh
+npm install --save-dev typescript @biomejs/biome vitest @vitest/coverage-v8 tsdown lefthook \
+  size-limit @size-limit/file publint @arethetypeswrong/cli @types/node
+```
+
+## Set up a new package repo
+
+### TypeScript
+
+```jsonc
+// tsconfig.json
+{
+  "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 |
+| `@integr8-media/config/tsconfig/react-library.json` | React library: Bundler resolution, DOM types, react-jsx, isolatedDeclarations |
+| `@integr8-media/config/tsconfig/node-app.json` | Node application: NodeNext, no declarations, Node types |
+| `@integr8-media/config/tsconfig/react-app.json` | React application: Bundler, DOM, noEmit |
+
+All presets use ES2024, `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`,
+`noImplicitOverride`, `noFallthroughCasesInSwitch`, `verbatimModuleSyntax`,
+`resolveJsonModule`, `forceConsistentCasingInFileNames` and `skipLibCheck`.
+
+Notes:
+
+- `node-app.json` loads Node's types (`"types": ["node"]`), so install `@types/node`. A Node
+  library that needs Node's types adds `"compilerOptions": { "types": ["node"] }` itself;
+  `library.json` leaves them out so it also works for universal libraries.
+- With `isolatedDeclarations`, keep `*.config.ts` files out of `include` (their
+  `export default someCall()` has no explicit type).
+
+### Biome
+
+```jsonc
+// biome.json
+{ "extends": ["@integr8-media/config/biome"] }
+```
+
+- Formatter: 2-space indent, line width 100, single quotes in TS, double quotes in JSX,
+  semicolons always, trailing commas everywhere.
+- 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/`, `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 `"!!.idea"`) and don't repeat `"**"`.
+
+### Vitest
+
+```ts
+// vitest.config.ts
+import { integr8Vitest } from '@integr8-media/config/vitest';
+
+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.
+
+- `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
+
+```ts
+// tsdown.config.ts
+import { integr8Tsdown } from '@integr8-media/config/tsdown';
+
+export default integr8Tsdown({ entry: 'src/index.ts', platform: 'browser' });
+```
+
+ESM only, `.d.ts` generation (fast through isolatedDeclarations), no source maps, clean output,
+tree-shaking. Target `node24` for `platform: 'node'`, `es2024` otherwise. Dependencies and peer
+dependencies stay external. Files are always named `.mjs` / `.d.mts`, so point `exports` there:
+
+```json
+"exports": {
+  ".": { "types": "./dist/index.d.mts", "default": "./dist/index.mjs" }
+}
+```
+
+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
+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`.
+
+### Lefthook
+
+```yaml
+# lefthook.yml
+extends:
+  - node_modules/@integr8-media/config/lefthook/base.yml
+```
+
+- pre-commit: `biome check --write` on staged files, fixes re-staged.
+- 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`.
+
+### Standard scripts
+
+```json
+"scripts": {
+  "lint": "biome check",
+  "format": "biome format --write",
+  "typecheck": "tsc --noEmit",
+  "test": "vitest run",
+  "test:coverage": "vitest run --coverage",
+  "build": "tsdown",
+  "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"
+}
+```
+
+`--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. 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
+# .github/workflows/ci.yml
+on:
+  pull_request:
+    branches: [dev]
+jobs:
+  checks:
+    uses: <owner>/integr8-config/.github/workflows/pr-checks.yml@v1
+    with:
+      os-matrix: false
+```
+
+```yaml
+# .github/workflows/release.yml
+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
+```
+
+- `pr-checks.yml`: install, lint, typecheck, test:coverage, build, size, check:exports.
+  `os-matrix: true` runs on Linux, macOS and Windows.
+- `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 |
+| --- | --- |
+| `@integr8-media/config/vitest` | `integr8Vitest(options?)`, `ConfigError` |
+| `@integr8-media/config/tsdown` | `integr8Tsdown(options)`, `ConfigError` |
+| `@integr8-media/config/size-limit` | `integr8SizeLimit(entries)`, `ConfigError` |
+
+Invalid options throw `ConfigError` with `code: 'INVALID_OPTION'`. The API reference is
+generated from TSDoc with `npm run docs` (output in `docs/api/`).
+
+## Non-goals
+
+- No runtime code and nothing app-specific
+- No ESLint or Prettier presets
+- No versioning tool (versions are bumped by hand)
+
+## Working on this repo
+
+```sh
+npm install
+npm run lint
+npm run typecheck
+npm run test:coverage   # unit tests + integration tests that run each tool on fixtures/
+npm run build
+npm run size
+npm run check:exports
+```
+
+- Unit tests sit next to the code in `src/`.
+- `test/` holds integration tests that run tsc, Biome, tsdown, Vitest, publint, attw and
+  Lefthook against `fixtures/`. They need `git` on the PATH, and on Windows Lefthook needs Git
+  Bash's `sh`.
+- The React fixtures use a small JSX type stub instead of installing React.
+
+## License
+
+MIT

package/biome/biome.json

@@ -0,0 +1,112 @@
+{
+  "files": {
+    "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,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "jsxQuoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "style": {
+        "noDefaultExport": "error",
+        "noNonNullAssertion": "error",
+        "useImportType": "error",
+        "useFilenamingConvention": {
+          "level": "error",
+          "options": {
+            "filenameCases": ["camelCase", "PascalCase"],
+            "requireAscii": true
+          }
+        }
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noConsole": "warn"
+      }
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.config.ts", "**/*.config.mts", "**/*.config.js", "**/*.config.mjs"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noDefaultExport": "off"
+          }
+        }
+      }
+    },
+    {
+      "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/configError-Cap5gwBB.mjs

@@ -0,0 +1,31 @@
+// src/errors/configError.ts
+/**
+* Thrown by the preset functions when they receive options they cannot turn into a config.
+*
+* @example
+* ```ts
+* try {
+*   integr8Vitest({ coverageThreshold: 120 });
+* } catch (error) {
+*   if (error instanceof ConfigError && error.code === 'INVALID_OPTION') {
+*     // handle it
+*   }
+* }
+* ```
+*/
+var ConfigError = class extends Error {
+	/** Always `'ConfigError'`. */
+	name = "ConfigError";
+	/** Machine-readable reason for the error. */
+	code;
+	/**
+	* @param code - Machine-readable reason for the error.
+	* @param message - Human-readable description.
+	* @param options - Standard error options, such as `cause`.
+	*/
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+	}
+};
+export { ConfigError as t };

package/dist/configError-DPT5pJ9Z.d.mts

@@ -0,0 +1,34 @@
+/**
+ * Codes carried by {@link ConfigError}.
+ *
+ * - `INVALID_OPTION`: an option passed to a preset function is missing, has the wrong type,
+ *   or is out of range.
+ */
+type ConfigErrorCode = "INVALID_OPTION";
+/**
+ * Thrown by the preset functions when they receive options they cannot turn into a config.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   integr8Vitest({ coverageThreshold: 120 });
+ * } catch (error) {
+ *   if (error instanceof ConfigError && error.code === 'INVALID_OPTION') {
+ *     // handle it
+ *   }
+ * }
+ * ```
+ */
+declare class ConfigError extends Error {
+  /** Always `'ConfigError'`. */
+  override readonly name: "ConfigError";
+  /** Machine-readable reason for the error. */
+  readonly code: ConfigErrorCode;
+  /**
+   * @param code - Machine-readable reason for the error.
+   * @param message - Human-readable description.
+   * @param options - Standard error options, such as `cause`.
+   */
+  constructor(code: ConfigErrorCode, message: string, options?: ErrorOptions);
+}
+export { ConfigErrorCode as n, ConfigError as t };

package/dist/sizeLimit.d.mts

@@ -0,0 +1,34 @@
+import { n as ConfigErrorCode, t as ConfigError } from "./configError-DPT5pJ9Z.mjs";
+import { SizeLimitConfig } from "size-limit";
+/** One file (or group of files) to measure. */
+interface Integr8SizeLimitEntry {
+  /** Built file(s) to measure, for example `'dist/index.mjs'`. */
+  path: string | string[];
+  /** Largest allowed size, for example `'5 kB'`. */
+  limit: string;
+  /** Label in the report. Defaults to the path. */
+  name?: string;
+  /**
+   * Named imports to measure instead of the whole file (tree-shaking check), for example
+   * `'{ Button }'`. Needs a bundler plugin such as `@size-limit/esbuild`.
+   */
+  import?: string | Record<string, string>;
+}
+/**
+ * Builds size-limit checks from a short list of entries. Each entry gets a readable name
+ * (the path when none is given) and is validated before size-limit runs.
+ *
+ * @param entries - Files to measure and their limits. At least one is required.
+ * @returns size-limit checks to default-export from `.size-limit.js` (or `.size-limit.ts`).
+ * @throws {@link ConfigError} with code `INVALID_OPTION` for an empty list, a missing path or
+ * an invalid limit.
+ *
+ * @example
+ * ```ts
+ * // .size-limit.ts
+ * import { integr8SizeLimit } from '@integr8-media/config/size-limit';
+ * export default integr8SizeLimit([{ path: 'dist/index.mjs', limit: '10 kB' }]);
+ * ```
+ */
+export declare function integr8SizeLimit(entries: readonly Integr8SizeLimitEntry[]): SizeLimitConfig;
+export { ConfigError, type ConfigErrorCode, type Integr8SizeLimitEntry };

package/dist/sizeLimit.mjs

@@ -0,0 +1,39 @@
+import { t as ConfigError } from "./configError-Cap5gwBB.mjs";
+// src/sizeLimit/integr8SizeLimit.ts
+const LIMIT_PATTERN = /^\d+(\.\d+)?\s*[a-z]+$/i;
+/**
+* Builds size-limit checks from a short list of entries. Each entry gets a readable name
+* (the path when none is given) and is validated before size-limit runs.
+*
+* @param entries - Files to measure and their limits. At least one is required.
+* @returns size-limit checks to default-export from `.size-limit.js` (or `.size-limit.ts`).
+* @throws {@link ConfigError} with code `INVALID_OPTION` for an empty list, a missing path or
+* an invalid limit.
+*
+* @example
+* ```ts
+* // .size-limit.ts
+* import { integr8SizeLimit } from '@integr8-media/config/size-limit';
+* export default integr8SizeLimit([{ path: 'dist/index.mjs', limit: '10 kB' }]);
+* ```
+*/
+function integr8SizeLimit(entries) {
+	if (!Array.isArray(entries) || entries.length === 0) throw new ConfigError("INVALID_OPTION", "integr8SizeLimit: \"entries\" must be a non-empty list.");
+	return entries.map((entry, index) => toCheck(entry, index));
+}
+function toCheck(entry, index) {
+	const where = `integr8SizeLimit: entry ${index}`;
+	if (typeof entry !== "object" || entry === null) throw new ConfigError("INVALID_OPTION", `${where} must be an object.`);
+	const paths = typeof entry.path === "string" ? [entry.path] : entry.path;
+	if (!Array.isArray(paths) || paths.length === 0 || !paths.every((path) => typeof path === "string" && path.trim() !== "")) throw new ConfigError("INVALID_OPTION", `${where}: "path" must be a non-empty path or list of paths.`);
+	if (typeof entry.limit !== "string" || !LIMIT_PATTERN.test(entry.limit.trim())) throw new ConfigError("INVALID_OPTION", `${where}: "limit" must look like "10 kB"; got ${String(entry.limit)}.`);
+	if (entry.name !== void 0 && (typeof entry.name !== "string" || entry.name.trim() === "")) throw new ConfigError("INVALID_OPTION", `${where}: "name" must be a non-empty string.`);
+	const check = {
+		name: entry.name ?? paths.join(", "),
+		path: typeof entry.path === "string" ? entry.path : [...paths],
+		limit: entry.limit.trim()
+	};
+	if (entry.import !== void 0) check.import = typeof entry.import === "string" ? entry.import : { ...entry.import };
+	return check;
+}
+export { ConfigError, integr8SizeLimit };

package/dist/tsdown.d.mts

@@ -0,0 +1,48 @@
+import { n as ConfigErrorCode, t as ConfigError } from "./configError-DPT5pJ9Z.mjs";
+import { UserConfig } from "tsdown";
+/** Platforms the tsdown preset can build for. */
+type Integr8TsdownPlatform = "node" | "browser" | "neutral";
+/** Entry points: one path, a list of paths, or a map of output name to path. */
+type Integr8TsdownEntry = string | string[] | Record<string, string>;
+/** Options for {@link integr8Tsdown}. */
+interface Integr8TsdownOptions {
+  /** Entry file(s) to build. */
+  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, 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, an unknown
+ * platform or an `unbundle` that is not a boolean.
+ *
+ * @example
+ * ```ts
+ * // tsdown.config.ts
+ * import { integr8Tsdown } from '@integr8-media/config/tsdown';
+ * export default integr8Tsdown({ entry: 'src/index.ts', platform: 'browser' });
+ * ```
+ */
+export declare function integr8Tsdown(options: Integr8TsdownOptions): UserConfig;
+export { ConfigError, type ConfigErrorCode, type Integr8TsdownEntry, type Integr8TsdownOptions, type Integr8TsdownPlatform };

package/dist/tsdown.mjs

@@ -0,0 +1,79 @@
+import { t as ConfigError } from "./configError-Cap5gwBB.mjs";
+// src/tsdown/integr8Tsdown.ts
+const PLATFORMS = [
+	"node",
+	"browser",
+	"neutral"
+];
+/**
+* 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, 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, an unknown
+* platform or an `unbundle` that is not a boolean.
+*
+* @example
+* ```ts
+* // tsdown.config.ts
+* import { integr8Tsdown } from '@integr8-media/config/tsdown';
+* export default integr8Tsdown({ entry: 'src/index.ts', platform: 'browser' });
+* ```
+*/
+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,
+		target: platform === "node" ? "node24" : "es2024",
+		format: "esm",
+		fixedExtension: true,
+		dts: true,
+		sourcemap: false,
+		clean: 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();
+		return entry;
+	}
+	if (Array.isArray(entry)) {
+		if (entry.length === 0 || !entry.every(isNonEmptyString)) throw invalidEntry();
+		return [...entry];
+	}
+	if (typeof entry === "object" && entry !== null) {
+		const values = Object.values(entry);
+		if (values.length === 0 || !values.every(isNonEmptyString)) throw invalidEntry();
+		return { ...entry };
+	}
+	throw invalidEntry();
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+function invalidEntry() {
+	return new ConfigError("INVALID_OPTION", "integr8Tsdown: \"entry\" must be a non-empty path, a non-empty list of paths, or a non-empty map of name to path.");
+}
+export { ConfigError, integr8Tsdown };

package/dist/vitest.d.mts

@@ -0,0 +1,36 @@
+import { n as ConfigErrorCode, t as ConfigError } from "./configError-DPT5pJ9Z.mjs";
+import { ViteUserConfig } from "vitest/config";
+/** Test environments the Vitest preset supports. */
+type Integr8VitestEnvironment = "node" | "jsdom";
+/** Options for {@link integr8Vitest}. */
+interface Integr8VitestOptions {
+  /** Test environment. Defaults to `'node'`. `'jsdom'` needs the `jsdom` package installed. */
+  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. Test collection
+ * skips `playground/**` too, so Playwright specs there are not run by Vitest.
+ *
+ * @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, or for `setupFiles` that is not a non-empty string or a non-empty
+ * list of non-empty strings.
+ *
+ * @example
+ * ```ts
+ * // vitest.config.ts
+ * import { integr8Vitest } from '@integr8-media/config/vitest';
+ * export default integr8Vitest({ environment: 'jsdom' });
+ * ```
+ */
+export declare function integr8Vitest(options?: Integr8VitestOptions): ViteUserConfig;
+export { ConfigError, type ConfigErrorCode, type Integr8VitestEnvironment, type Integr8VitestOptions };

package/dist/vitest.mjs

@@ -0,0 +1,57 @@
+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. Test collection
+* skips `playground/**` too, so Playwright specs there are not run by Vitest.
+*
+* @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, or for `setupFiles` that is not a non-empty string or a non-empty
+* list of non-empty strings.
+*
+* @example
+* ```ts
+* // vitest.config.ts
+* import { integr8Vitest } from '@integr8-media/config/vitest';
+* export default integr8Vitest({ environment: 'jsdom' });
+* ```
+*/
+function integr8Vitest(options = {}) {
+	const environment = options.environment ?? "node";
+	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}"],
+			exclude: [
+				"src/**/*.test.ts",
+				"src/**/*.test.tsx",
+				"src/**/*.d.ts",
+				"src/index.ts",
+				"playground/**"
+			],
+			thresholds: { lines: coverageThreshold }
+		}
+	} };
+}
+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

@@ -0,0 +1,25 @@
+# @integr8-media/config Lefthook base.
+# Use it from a repo's lefthook.yml:
+#   extends:
+#     - node_modules/@integr8-media/config/lefthook/base.yml
+
+pre-commit:
+  commands:
+    biome:
+      glob: "*.{js,jsx,mjs,cjs,ts,tsx,mts,cts,json,jsonc,css}"
+      run: npx --no biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
+      stage_fixed: true
+
+pre-push:
+  # piped: run in order and stop at the first failure.
+  piped: true
+  commands:
+    typecheck:
+      priority: 1
+      run: npm run typecheck
+    test-coverage:
+      priority: 2
+      run: npm run test:coverage
+    build:
+      priority: 3
+      run: npm run build

package/package.json

@@ -1,6 +1,116 @@
 {
   "name": "@integr8-media/config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MinaLouisLeon/integr8-config.git"
+  },
+  "homepage": "https://github.com/MinaLouisLeon/integr8-config#readme",
+  "bugs": {
+    "url": "https://github.com/MinaLouisLeon/integr8-config/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "tsconfig",
+    "biome",
+    "lefthook"
+  ],
+  "exports": {
+    "./tsconfig/library.json": "./tsconfig/library.json",
+    "./tsconfig/react-library.json": "./tsconfig/react-library.json",
+    "./tsconfig/node-app.json": "./tsconfig/node-app.json",
+    "./tsconfig/react-app.json": "./tsconfig/react-app.json",
+    "./biome": "./biome/biome.json",
+    "./vitest": {
+      "types": "./dist/vitest.d.mts",
+      "default": "./dist/vitest.mjs"
+    },
+    "./tsdown": {
+      "types": "./dist/tsdown.d.mts",
+      "default": "./dist/tsdown.mjs"
+    },
+    "./lefthook/base.yml": "./lefthook/base.yml",
+    "./size-limit": {
+      "types": "./dist/sizeLimit.d.mts",
+      "default": "./dist/sizeLimit.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "biome check",
+    "format": "biome format --write",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "build": "tsdown",
+    "size": "size-limit",
+    "check:exports": "publint && attw --pack --profile esm-only --entrypoints ./vitest ./tsdown ./size-limit",
+    "docs": "typedoc",
+    "prepare": "lefthook install"
+  },
+  "peerDependencies": {
+    "@arethetypeswrong/cli": ">=0.17.0",
+    "@biomejs/biome": ">=2.6.0 <3",
+    "@vitest/coverage-v8": ">=4.0.0",
+    "lefthook": ">=1.10.0",
+    "publint": ">=0.3.0",
+    "size-limit": ">=11.0.0",
+    "tsdown": ">=0.23.0",
+    "typescript": ">=5.7.0",
+    "vitest": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@arethetypeswrong/cli": {
+      "optional": true
+    },
+    "@biomejs/biome": {
+      "optional": true
+    },
+    "@vitest/coverage-v8": {
+      "optional": true
+    },
+    "lefthook": {
+      "optional": true
+    },
+    "publint": {
+      "optional": true
+    },
+    "size-limit": {
+      "optional": true
+    },
+    "tsdown": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.6.5",
+    "@size-limit/file": "^14.3.0",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^5.1.0",
+    "lefthook": "^2.2.2",
+    "publint": "^0.3.25",
+    "size-limit": "^14.3.0",
+    "tsdown": "^0.23.5",
+    "typedoc": "^0.28.20",
+    "typescript": "~6.0.0",
+    "vitest": "^5.1.0"
+  }
+}

package/tsconfig/base.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "@integr8-media/config base",
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024"],
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  }
+}

package/tsconfig/library.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "@integr8-media/config library (Node or universal)",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "isolatedDeclarations": true,
+    "declarationMap": false
+  }
+}

package/tsconfig/node-app.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "@integr8-media/config Node application",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "declaration": false
+  }
+}

package/tsconfig/react-app.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "@integr8-media/config React application",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "noEmit": true
+  }
+}

package/tsconfig/react-library.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "@integr8-media/config React library",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "declaration": true,
+    "isolatedDeclarations": true,
+    "declarationMap": false
+  }
+}