@rtorcato/repo-tooling 2.59.0

package/tooling/semantic-release/github.mjs

@@ -0,0 +1,79 @@
+export default {
+	branches: [
+		'+([0-9])?(.{+([0-9]),x}).x',
+		'main', // → stable
+		'next',
+		'release',
+		'next-major', // → next-major branch = next-major tag
+		{ name: 'dev', prerelease: true }, // → dev branch = dev tag
+		{ name: 'beta', prerelease: true }, // → beta branch = beta tag
+		{ name: 'alpha', prerelease: true }, // → alpha branch = alpha tag
+	],
+	repositoryUrl: `https://github.com/${process.env.GITHUB_REPOSITORY}.git`,
+	plugins: [
+		[
+			'@semantic-release/commit-analyzer',
+			{
+				preset: 'conventionalcommits',
+				releaseRules: [
+					{ breaking: true, release: 'major' }, // Major release for breaking changes
+					{ type: 'feat', release: 'minor' }, // Minor release for features
+					{ type: 'fix', release: 'patch' }, // Patch release for bug fixes
+					{
+						type: 'docs', // Documentation changes
+						scope: 'README', // Specific scope for README changes
+						release: false, // no Patch release for README changes
+					},
+					// { type: 'chore', release: 'patch' }, // Chore changes
+					{ type: 'update', release: 'patch' },
+					{ type: 'refactor', release: 'patch' },
+					{ type: 'revert', release: 'patch' },
+					{ type: 'style', release: false },
+					{ type: 'test', release: false },
+				],
+				parserOpts: {
+					noteKeywords: ['BREAKING CHANGE', 'BREAKING CHANGES', 'BREAKING'],
+				},
+			},
+		],
+		'@semantic-release/release-notes-generator',
+		// Release notes generator plugin to generate release notes
+		[
+			'@semantic-release/github',
+			{
+				assets: ['CHANGELOG.md', 'package.json', 'README.md'],
+				message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+			},
+		],
+		[
+			'@semantic-release/changelog',
+			{
+				changelogFile: 'CHANGELOG.md',
+			},
+		],
+		// npm publishing goes through OIDC trusted publishing — no NPM_TOKEN. The
+		// release job runs with `id-token: write` and npm (>=11.5.1) authenticates
+		// via the GitHub Actions trusted publisher configured on the package, and
+		// gets provenance for free. Private packages are skipped automatically by
+		// @semantic-release/npm; a public repo that only wants GitHub releases can
+		// opt out with NPM_PUBLISH=false (the version in package.json is still bumped).
+		['@semantic-release/npm', { npmPublish: process.env.NPM_PUBLISH !== 'false', pkgRoot: '.' }],
+		[
+			'@semantic-release/git',
+			{
+				assets: ['package.json', 'CHANGELOG.md'],
+				message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+				// Skip hooks by disabling Husky
+				skipCommitHooks: true,
+				prepareCmd: 'pnpm exec biome format package.json',
+			},
+		],
+	],
+}
+
+// [
+// 	'@semantic-release/exec',
+// 	{
+// 		prepareCmd: 'pnpm exec biome format',
+// 	},
+// ],

package/tooling/semantic-release/index.d.mts

@@ -0,0 +1,4 @@
+import type { Options } from 'semantic-release'
+
+declare const config: Options
+export default config

package/tooling/semantic-release/index.mjs

@@ -0,0 +1,80 @@
+export default {
+	branches: [
+		'+([0-9])?(.{+([0-9]),x}).x',
+		'main', // → stable
+		'next',
+		'release',
+		'next-major', // → next-major branch = next-major tag
+		{ name: 'dev', prerelease: true }, // → dev branch = dev tag
+		{ name: 'beta', prerelease: true }, // → beta branch = beta tag
+		{ name: 'alpha', prerelease: true }, // → alpha branch = alpha tag
+	],
+	repositoryUrl: `https://gitlab-ci-token:${process.env.GITLAB_TOKEN}@gitlab.com/${process.env.CI_PROJECT_NAMESPACE}/${process.env.CI_PROJECT_NAME}.git`,
+	plugins: [
+		[
+			'@semantic-release/commit-analyzer',
+			{
+				preset: 'conventionalcommits',
+				releaseRules: [
+					{ breaking: true, release: 'major' }, // Major release for breaking changes
+					{ type: 'feat', release: 'minor' }, // Minor release for features
+					{ type: 'fix', release: 'patch' }, // Patch release for bug fixes
+					{
+						type: 'docs', // Documentation changes
+						scope: 'README', // Specific scope for README changes
+						release: false, // no Patch release for README changes
+					},
+					// { type: 'chore', release: 'patch' }, // Chore changes
+					{ type: 'update', release: 'patch' },
+					{ type: 'refactor', release: 'patch' },
+					{ type: 'revert', release: 'patch' },
+					{ type: 'style', release: false },
+					{ type: 'test', release: false },
+				],
+				parserOpts: {
+					noteKeywords: ['BREAKING CHANGE', 'BREAKING CHANGES', 'BREAKING'],
+				},
+			},
+		],
+		'@semantic-release/release-notes-generator',
+		// Release notes generator plugin to generate release notes
+		[
+			'@semantic-release/gitlab',
+			{
+				assets: ['dist/*.js', 'dist/*.js.map', 'CHANGELOG.md', 'package.json', 'README.md'],
+				message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+				gitlabUrl: 'https://gitlab.com',
+			},
+		],
+		[
+			'@semantic-release/changelog',
+			{
+				changelogFile: 'CHANGELOG.md',
+			},
+		],
+		// npm publishing goes through OIDC trusted publishing — no NPM_TOKEN. The
+		// release job runs with `id-token: write` and npm (>=11.5.1) authenticates
+		// via the CI trusted publisher configured on the package, and gets
+		// provenance for free. Private packages are skipped automatically by
+		// @semantic-release/npm; a repo that only wants VCS releases can opt out
+		// with NPM_PUBLISH=false (the version in package.json is still bumped).
+		['@semantic-release/npm', { npmPublish: process.env.NPM_PUBLISH !== 'false', pkgRoot: '.' }],
+		[
+			'@semantic-release/git',
+			{
+				assets: ['package.json', 'CHANGELOG.md'],
+				message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+				// Skip hooks by disabling Husky
+				skipCommitHooks: true,
+				prepareCmd: 'pnpm exec biome format package.json',
+			},
+		],
+	],
+}
+
+// [
+// 	'@semantic-release/exec',
+// 	{
+// 		prepareCmd: 'pnpm exec biome format',
+// 	},
+// ],

package/tooling/swift/periphery.yml

@@ -0,0 +1,4 @@
+# Periphery dead-code scan. `retain_public: true` keeps a library's public API
+# from being reported as unused — for a SwiftPM package the public surface is
+# the product, not dead code.
+retain_public: true

package/tooling/swift/swiftlint.yml

@@ -0,0 +1,23 @@
+disabled_rules:
+  - weak_delegate
+  - cyclomatic_complexity
+  - force_unwrapping
+  - function_body_length
+  - type_name
+  - line_length
+  - identifier_name
+  - trailing_whitespace
+
+excluded:
+  - .build
+  - .swiftpm
+  - DerivedData
+
+file_length:
+  warning: 500
+  error: 1200
+
+nesting:
+  type_level:
+    warning: 3
+    error: 6

package/tooling/tests/exports-resolution.d.mts

@@ -0,0 +1,14 @@
+export interface ExportsResolutionTestOptions {
+	/** Absolute path to the package.json whose `exports` map will be validated. */
+	packageJsonPath: string
+	/** Absolute path to the source directory whose subfolders are cross-checked. */
+	srcDir: string
+	/** Folder names under `srcDir` to skip (e.g., `'tests'`, `'common'`). */
+	excludeDirs?: string[]
+}
+
+/**
+ * Asserts that a package.json `exports` map stays in sync with its source folders.
+ * Call from a Vitest test file; generates one describe block plus one it per folder.
+ */
+export function runExportsResolutionTest(options: ExportsResolutionTestOptions): void

package/tooling/tests/exports-resolution.mjs

@@ -0,0 +1,68 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Asserts that a package.json `exports` map stays in sync with its source folders.
+ *
+ * For every folder under `srcDir` (excluding `excludeDirs`), the package.json must
+ * expose a matching `./<name>` subpath export. Conversely, every subpath in the
+ * `exports` map (other than `.`) must point at a folder that exists in `srcDir`.
+ *
+ * Call this from a Vitest test file; it generates one `describe` block plus one
+ * `it` per folder, so failures pinpoint the drift.
+ *
+ * @example
+ * ```ts
+ * // src/tests/exports-resolution.test.ts
+ * import { fileURLToPath } from 'node:url'
+ * import { runExportsResolutionTest } from '@rtorcato/repo-tooling/tests/exports-resolution'
+ *
+ * runExportsResolutionTest({
+ * 	packageJsonPath: fileURLToPath(new URL('../../package.json', import.meta.url)),
+ * 	srcDir: fileURLToPath(new URL('../', import.meta.url)),
+ * 	excludeDirs: ['tests'],
+ * })
+ * ```
+ *
+ * @param {object} options
+ * @param {string} options.packageJsonPath Absolute path to the package.json under test.
+ * @param {string} options.srcDir Absolute path to the source folder whose subdirectories should be cross-checked.
+ * @param {string[]} [options.excludeDirs] Folder names under `srcDir` to skip (e.g., `tests`, `common`).
+ */
+export function runExportsResolutionTest({ packageJsonPath, srcDir, excludeDirs = [] }) {
+	const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+
+	if (!pkg.exports || typeof pkg.exports !== 'object') {
+		throw new Error(`exports-resolution: package.json at ${packageJsonPath} has no exports map`)
+	}
+
+	const exportSubpaths = new Set(
+		Object.keys(pkg.exports)
+			.filter((k) => k !== '.')
+			.map((k) => k.replace(/^\.\//, ''))
+	)
+
+	const excluded = new Set(excludeDirs)
+	const moduleDirs = readdirSync(srcDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !excluded.has(d.name))
+		.map((d) => d.name)
+		.sort()
+
+	describe('package.json exports map', () => {
+		it('has at least one module', () => {
+			expect(moduleDirs.length).toBeGreaterThan(0)
+		})
+
+		for (const dir of moduleDirs) {
+			it(`exposes ./${dir}`, () => {
+				expect(exportSubpaths.has(dir)).toBe(true)
+			})
+		}
+
+		it('has no exports entries pointing at missing src/ folders', () => {
+			const moduleDirSet = new Set(moduleDirs)
+			const orphans = [...exportSubpaths].filter((k) => !moduleDirSet.has(k))
+			expect(orphans).toEqual([])
+		})
+	})
+}

package/tooling/tests/ssr-safety.d.mts

@@ -0,0 +1,14 @@
+export interface SsrSafetyTestOptions {
+	/** Absolute path to the source directory. */
+	srcDir: string
+	/** Folder names under `srcDir` to skip (e.g., `'tests'`, `'common'`). */
+	excludeDirs?: string[]
+	/** Entry filename inside each folder. Default: `'index.ts'`. */
+	moduleEntry?: string
+}
+
+/**
+ * Asserts that every module folder under `srcDir` can be imported in a Node
+ * environment without throwing. Call from a Vitest test file.
+ */
+export function runSsrSafetyTest(options: SsrSafetyTestOptions): void

package/tooling/tests/ssr-safety.mjs

@@ -0,0 +1,53 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Asserts that every module folder under `srcDir` can be imported in a Node
+ * environment without throwing (no DOM, no `window`, no `document`).
+ *
+ * For each folder under `srcDir` (excluding `excludeDirs`), the helper resolves
+ * `<srcDir>/<name>/<moduleEntry>` and `await import(...)` it. If the import
+ * throws or the module accesses a missing global at top level, the test fails.
+ *
+ * Use this as a contract test for libraries that promise SSR safety — i.e., that
+ * importing a module is always safe even when its underlying API isn't available.
+ *
+ * @example
+ * ```ts
+ * // src/tests/ssr-safety.test.ts (run with vitest --environment node)
+ * import { fileURLToPath } from 'node:url'
+ * import { runSsrSafetyTest } from '@rtorcato/repo-tooling/tests/ssr-safety'
+ *
+ * runSsrSafetyTest({
+ * 	srcDir: fileURLToPath(new URL('../', import.meta.url)),
+ * 	excludeDirs: ['tests'],
+ * })
+ * ```
+ *
+ * @param {object} options
+ * @param {string} options.srcDir Absolute path to the source folder.
+ * @param {string[]} [options.excludeDirs] Folder names under `srcDir` to skip.
+ * @param {string} [options.moduleEntry] Entry filename inside each folder. Default: `'index.ts'`.
+ */
+export function runSsrSafetyTest({ srcDir, excludeDirs = [], moduleEntry = 'index.ts' }) {
+	const excluded = new Set(excludeDirs)
+	const moduleDirs = readdirSync(srcDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !excluded.has(d.name))
+		.map((d) => d.name)
+		.sort()
+
+	describe('SSR safety', () => {
+		it('has at least one module', () => {
+			expect(moduleDirs.length).toBeGreaterThan(0)
+		})
+
+		for (const dir of moduleDirs) {
+			it(`imports ./${dir}/${moduleEntry} without throwing`, async () => {
+				const moduleUrl = pathToFileURL(join(srcDir, dir, moduleEntry)).href
+				await expect(import(moduleUrl)).resolves.toBeDefined()
+			})
+		}
+	})
+}

package/tooling/tsup/index.d.mts

@@ -0,0 +1,8 @@
+import type { Options } from 'tsup'
+import type { defineConfig } from 'tsup'
+
+export type DefineConfig = ReturnType<typeof defineConfig>
+
+export declare const getConfig: (customOptions: Options, env: string) => DefineConfig
+
+export declare const baseOptions: (options: Options, env: string) => Options

package/tooling/tsup/index.mjs

@@ -0,0 +1,33 @@
+import { defineConfig } from 'tsup'
+
+export const getConfig = (customOptions, env) => {
+	// tsup invokes this callback with its own CLI options, so `customOptions`
+	// must be merged in explicitly — a `(options = customOptions)` default is
+	// bypassed and silently drops the consumer's config (e.g. `entry`). Layer
+	// only the DEFINED CLI overrides on top so flags like `--watch` still win
+	// without an absent `entry: undefined` clobbering the consumer's entry.
+	return defineConfig((cliOptions) => {
+		const overrides = Object.fromEntries(
+			Object.entries(cliOptions ?? {}).filter(([, value]) => value !== undefined)
+		)
+		return baseOptions({ ...customOptions, ...overrides }, env)
+	})
+}
+
+export const baseOptions = (options, env) => {
+	const opts = {
+		treeshake: true,
+		splitting: true,
+		format: ['cjs', 'esm'], // generate cjs and esm files
+		// Default to all of src EXCEPT tests, so a consumer that doesn't pass an
+		// explicit entry never ships compiled *.test.* / *.spec.* files in dist.
+		entry: ['src/**/*.ts', '!src/**/*.test.ts', '!src/**/*.spec.ts'],
+		skipNodeModulesBundle: true, // Skips building dependencies for node modules
+		minify: !options.watch && env === 'production',
+		bundle: false,
+		clean: true, // clean up the dist folder
+		dts: true, // generate dts file for main module
+		...options,
+	}
+	return opts
+}

package/tooling/typedoc/typedoc.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "excludePrivate": true,
+  "excludeExternals": true,
+  "includeVersion": true,
+  "out": "docs"
+}

package/tooling/typescript/README.md

@@ -0,0 +1,49 @@
+# `tsconfig`
+
+These are base shared `tsconfig.json` files from which all other `tsconfig.json`'s inherit.
+
+## Usage
+
+1. **Install this package** (if published as a package):
+   ```sh
+   pnpm add -D @your-org/tsconfig
+   # or
+   npm install --save-dev @your-org/tsconfig
+   # or
+   yarn add -D @your-org/tsconfig
+   ```
+
+2. **Extend the relevant config in your project `tsconfig.json`:**
+   ```jsonc
+   {
+     "extends": "./path/to/tooling/typescript/tsconfig.base.json", // or tsconfig.react.jsonc, etc.
+     // ...your overrides
+   }
+   ```
+   Replace the path with the config that matches your project type:
+   - `tsconfig.base.jsonc`: General base config
+   - `tsconfig.build.jsonc`: For npm package/library builds
+   - `tsconfig.react.jsonc`: For React apps
+   - `tsconfig.next.jsonc`: For Next.js apps
+   - `tsconfig.node.jsonc`: For Node.js/Express APIs
+   - `tsconfig.express.jsonc`: (If used) For Express APIs
+
+3. **Customizing:**
+   You can override or add any settings in your own `tsconfig.json` as needed.
+
+## Example
+
+```jsonc
+{
+  "extends": "../tooling/typescript/tsconfig.react.json",
+  // `~/*` and `@/*` → `./src/*` are inherited from the preset, anchored to this
+  // project via ${configDir} — no `baseUrl`/`paths` needed (baseUrl is deprecated
+  // in TS 5.9, removed in TS 7.0).
+  "include": ["src"]
+}
+```
+
+## Notes
+- These configs are meant to be shared and extended, not used directly.
+- Pick the config that matches your project type for best results.
+

package/tooling/typescript/reset.d.ts

@@ -0,0 +1,9 @@
+// Do not add any other lines of code to this file!
+import '@total-typescript/ts-reset'
+
+// https://www.totaltypescript.com/ts-reset
+// With ts-reset:
+// 👍 .json (in fetch) and JSON.parse both return unknown
+// ✅ .filter(Boolean) behaves EXACTLY how you expect
+// 🥹 array.includes is widened to be more ergonomic
+// 🚀 And several more changes!

package/tooling/typescript/tsconfig.base.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    // 🔧 Output & Module Resolution
+    "moduleResolution": "bundler",
+    "module": "esnext",
+    "target": "esnext",
+    // "module": "esnext", // 
+    // "moduleResolution": "node", // Prefer "bundler" if you're using Vite, esbuild, etc.
+    // "target": "esnext", // 
+    "lib": ["ES2022"], // Specify library files to be included in the compilation
+    "rootDir": "src",
+    "outDir": "dist",
+
+    
+    // 🔍 JavaScript Support
+    "allowJs": true, // Allow JavaScript files to be compiled
+    "checkJs": true, // Enable type checking on JavaScript files
+    "resolveJsonModule": true,  // Allow importing JSON files
+    "isolatedModules": true, // Ensure that each file can be safely transpiled independently
+    "esModuleInterop": true, // Enables emit interoperability between CommonJS and ES Modules
+    "allowSyntheticDefaultImports": true, // recommend enabling this for smoother interop
+
+    // ⚙️ Module Detection
+    "moduleDetection": "force", // Force module detection
+
+    // 📈 Performance
+    "skipLibCheck": true, // Skip type checking of declaration files
+    "incremental": true, // Enable incremental compilation
+    // Pin the build-info location so downstream emit tools (e.g. tsup's `dts`
+    // build) don't hit TS5074 from inheriting `incremental` without a file.
+    // ${configDir} resolves to the consuming project's dir (TS 5.5+).
+    "tsBuildInfoFile": "${configDir}/node_modules/.cache/tsconfig.tsbuildinfo",
+    "disableSourceOfProjectReferenceRedirect": true, // Disable source of project reference redirect
+
+    // 🚨 Strict Type Checking
+    "strict": true, // Enable all strict type checking options
+    "noUncheckedIndexedAccess": true, // Disallow accessing an index signature with an arbitrary key
+    "noImplicitAny": true, // Disallow implicit any type
+    "noImplicitReturns": true, // Disallow functions that do not return a value
+    "noImplicitOverride": true, // Ensure override keyword is used
+    "noImplicitThis": true, // Disallow 'this' with an implicit any type
+    "noPropertyAccessFromIndexSignature": true, // Disallow property access from index signature
+
+    // 🧹 Lint-Like Settings
+    "noUnusedLocals": true, // Disallow unused locals
+    "noUnusedParameters": true, // Disallow unused parameters
+    "noFallthroughCasesInSwitch": true, // Disallow fallthrough cases in switch statements
+
+    // 📦 Types & Declarations
+    "types": ["node", "vitest"], // Specify type declaration files to be included in the compilation
+    "declaration": false, // Do not generate .d.ts files
+    "declarationMap": false, // Do not generate sourcemaps for d.ts files
+
+    // 🛑 Emit Settings
+    "noEmit": true, // Do not emit output files
+    "sourceMap": true, // Generate sourcemaps for .ts files
+    
+    // ${configDir} anchors paths to the consuming project (TS 5.5+), so
+    // downstream repos no longer need `baseUrl` + a redeclared `paths` block
+    // (baseUrl is deprecated in TS 5.9, removed in TS 7.0). Refs: https://aka.ms/ts6
+    "paths": { // Path mapping for module resolution
+      "~/*": ["${configDir}/src/*"],
+      "@/*": ["${configDir}/src/*"]
+    }
+  },
+  "include": ["src/**/*", "index.d.ts"], // Include files in the src directory and index.d.ts
+  "exclude": [
+    "node_modules",
+    "build",
+    "dist",
+    ".next",
+    ".expo",
+    "OLD",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    ".turbo",
+    "out",
+    "not-used",
+    "vitest.config.ts"
+  ] // Exclude directories from compilation
+}

package/tooling/typescript/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false, // Emit output files
+    "emitDeclarationOnly": true, // Emit JS and .d.ts files
+    "declaration": true, // Generate .d.ts files
+    "declarationMap": true, // (optional) Generate sourcemaps for d.ts files
+    "outDir": "dist" // Output directory for build
+  },
+  "exclude": ["dist", "node_modules", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"]
+}

package/tooling/typescript/tsconfig.bun.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "types": ["bun"]
+  },
+  "include": ["src", "index.d.ts"],
+  "exclude": ["node_modules", "dist", "build", "test", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tooling/typescript/tsconfig.express.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022"], // Only include ES libs, no DOM
+    "types": ["node", "express", "vitest"], // Add express types for API development
+  },
+  "include": ["src", "index.d.ts"],
+  "exclude": ["node_modules", "dist", "build", "test", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tooling/typescript/tsconfig.next.json

@@ -0,0 +1,20 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "preserve", // Let Next.js handle JSX transformation
+    "lib": ["DOM", "DOM.Iterable", "ESNext"], // Include DOM types for browser APIs
+    "module": "esnext", // Next.js expects ESNext modules
+    "moduleResolution": "bundler", // Modern module resolution for Next.js
+    "allowJs": true, // Allow JavaScript files
+    "esModuleInterop": true, // Interop for CommonJS/ESM
+    "types": ["react", "tailwindcss", "vitest"],
+    "plugins": [ { "name": "next" } ], // Next.js plugin for TypeScript
+    // ${configDir} anchors paths to the consuming project (drops deprecated baseUrl)
+    "paths": {
+      "~/*": ["${configDir}/src/*"],
+      "@/*": ["${configDir}/src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "src", "pages", "app", "components", "types", "index.d.ts"],
+  "exclude": ["node_modules", "dist", ".next", "build", "out"]
+}

package/tooling/typescript/tsconfig.node.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022"],
+    "types": ["node", "vitest"]
+  },
+  "include": ["src", "index.d.ts"],
+  "exclude": ["node_modules", "dist", "build", "test", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tooling/typescript/tsconfig.react.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx", // Use the new JSX transform for React 17+
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],// Include DOM types for browser APIs
+    "types": ["react", "react-dom", "tailwindcss", "vitest"],
+    // ${configDir} anchors paths to the consuming project (drops deprecated baseUrl)
+    "paths": {
+      "~/*": ["${configDir}/src/*"],
+      "@/*": ["${configDir}/src/*"]
+    }
+  },
+  "include": ["src", "index.d.ts", "types"],
+  "exclude": ["node_modules", "dist", "build", "out", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tooling/typescript/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node", "vitest"]
+  },
+  "include": ["src", "tests", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"]
+}