@reasonabletech/config-typescript 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @reasonabletech/config-typescript
+
+[![npm version](https://img.shields.io/npm/v/@reasonabletech/config-typescript.svg)](https://www.npmjs.com/package/@reasonabletech/config-typescript)
+[![npm downloads](https://img.shields.io/npm/dm/@reasonabletech/config-typescript.svg)](https://www.npmjs.com/package/@reasonabletech/config-typescript)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+
+`@reasonabletech/config-typescript` provides shared `tsconfig` presets for applications, libraries, tooling, and extension packages. All presets build on a strict base that enables `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, and modern `Bundler` module resolution — options that catch more bugs at compile time than TypeScript's default settings.
+
+## Installation
+
+```bash
+pnpm add -D @reasonabletech/config-typescript typescript
+```
+
+## Requirements
+
+| Dependency | Version   | Required |
+| ---------- | --------- | -------- |
+| typescript | >= 5.0    | Yes      |
+
+This package provides TypeScript configuration presets and requires TypeScript 5.0+ for full compatibility with modern `compilerOptions` and module resolution settings.
+
+## Exported Entry Points
+
+This package exports JSON presets via subpath imports:
+
+- `@reasonabletech/config-typescript/<preset>.json`
+
+## Usage
+
+### Application Example
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/app.json"
+}
+```
+
+### Library Example
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/library.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  }
+}
+```
+
+## Available Presets
+
+| Preset                                                    | Intended Use                                             |
+| --------------------------------------------------------- | -------------------------------------------------------- |
+| `@reasonabletech/config-typescript/base.json`             | Base strict TypeScript defaults for NodeNext projects    |
+| `@reasonabletech/config-typescript/app.json`              | General application projects with `@/*` path alias       |
+| `@reasonabletech/config-typescript/library.json`          | Libraries that emit declarations only                    |
+| `@reasonabletech/config-typescript/browser-library.json`  | Browser-targeted libraries with DOM libs                 |
+| `@reasonabletech/config-typescript/platform-library.json` | Platform libraries with React/Next-related ambient types |
+| `@reasonabletech/config-typescript/react-app.json`        | React applications with JSX and `noEmit`                 |
+| `@reasonabletech/config-typescript/react-library.json`    | React libraries with JSX settings                        |
+| `@reasonabletech/config-typescript/nextjs.json`           | Next.js applications with bundler module resolution      |
+| `@reasonabletech/config-typescript/server.json`           | Server applications with decorators and `@/*` path alias |
+| `@reasonabletech/config-typescript/chrome-extension.json` | Chrome extension packages                                |
+| `@reasonabletech/config-typescript/vscode-extension.json` | VS Code extension packages                               |
+| `@reasonabletech/config-typescript/tooling.json`          | Tooling scripts and build utilities                      |
+| `@reasonabletech/config-typescript/eslint.json`           | TypeScript settings for ESLint integration               |
+| `@reasonabletech/config-typescript/strict.json`           | Additional strictness beyond `base.json`                 |
+| `@reasonabletech/config-typescript/docs.json`             | Documentation-focused TypeScript settings                |
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+This package follows [Semantic Versioning](https://semver.org/). Breaking changes are documented with migration guides when applicable.
+
+## Additional References
+
+- [Usage Guide](./docs/guides/usage-guide.md)
+- [Package Docs](./docs/README.md)
+- [Base Config Details](./docs/api/base-config.md)

package/docs/README.md

@@ -0,0 +1,18 @@
+# @reasonabletech/config-typescript Documentation
+
+Reference documentation for shared TypeScript presets in the core-utils monorepo.
+
+## Start Here
+
+- [Usage Guide](./guides/usage-guide.md)
+
+## API Reference
+
+- [Base Configuration](./api/base-config.md)
+
+## Monorepo Context
+
+- [Package README](../README.md)
+- [Architecture](../../../docs/architecture.md) — How packages relate
+- [Tooling](../../../docs/tooling.md) — Turbo, Changesets details
+- [Contributing](../../../CONTRIBUTING.md)

package/docs/api/base-config.md

@@ -0,0 +1,79 @@
+# TypeScript Presets API Reference
+
+This package publishes TypeScript presets as JSON config files.
+
+## How To Use
+
+Use one preset in your `tsconfig.json` `extends`:
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/base.json"
+}
+```
+
+All presets are exported with a `.json` suffix.
+
+## Preset Catalog
+
+| Preset | Extends | Highlights |
+| --- | --- | --- |
+| `base.json` | — | ES2022 target, `module: NodeNext`, strict mode, declaration/source maps, incremental builds |
+| `app.json` | `base.json` | App-friendly path alias default: `@/* -> src/*` |
+| `library.json` | `base.json` | Library default `emitDeclarationOnly: true` |
+| `react-app.json` | `base.json` | React app defaults (`jsx: react-jsx`, DOM libs, `noEmit: true`) |
+| `react-library.json` | `base.json` | React library defaults (DOM libs, JSX transform/import source) |
+| `nextjs.json` | `base.json` | Next.js defaults (`module: ESNext`, `moduleResolution: bundler`, Next plugin, `noEmit: true`) |
+| `server.json` | `base.json` | Node service defaults with decorator metadata and app-style path alias |
+| `browser-library.json` | `base.json` | Browser lib target (`ES2023`, DOM libs) |
+| `platform-library.json` | `base.json` | Platform package baseline with React/Next/Node type sets |
+| `chrome-extension.json` | `base.json` | Chrome extension type surface (`chrome`, `node`) |
+| `vscode-extension.json` | `base.json` | VS Code extension type surface (`vscode`, `node`) |
+| `eslint.json` | `base.json` | ESLint authoring preset (`emitDeclarationOnly`, include/exclude defaults) |
+| `docs.json` | `base.json` | Documentation-focused preset (`skipLibCheck: false`) |
+| `tooling.json` | `base.json` | Tooling/script projects with base strict defaults |
+| `strict.json` | `base.json` | Extra strictness (`exactOptionalPropertyTypes`, indexed-access checks, override guards) |
+
+## Common Usage Patterns
+
+### Application
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/app.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+### Library
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/library.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+### Strict Variant
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/strict.json"
+}
+```
+
+## Source of Truth
+
+Preset implementations live under:
+
+- `packages/config-typescript/lib/base.json`
+- `packages/config-typescript/lib/*.json`
+
+Review those files for exact compiler option values.

package/docs/guides/migration.md

@@ -0,0 +1,47 @@
+# Migration Guide
+
+This guide documents breaking changes and how to migrate between major versions of @reasonabletech/config-typescript.
+
+## Current Version
+
+The current major version is **0.x** (pre-1.0). The API is stabilizing but may have breaking changes before 1.0.
+
+## Future Migration Notes
+
+_No breaking changes documented yet. This section will be updated when breaking changes are released._
+
+---
+
+## Migration Template
+
+When documenting a breaking change, use this structure:
+
+### Migrating from X.x to Y.0
+
+#### Breaking Changes
+
+1. **Change description** - Brief explanation of what changed
+   
+   **Before:**
+   ```typescript
+   // Old usage
+   ```
+   
+   **After:**
+   ```typescript
+   // New usage
+   ```
+
+2. **Another change** - Description
+
+#### Deprecations
+
+- `oldFunction()` is deprecated in favor of `newFunction()`
+
+#### New Features
+
+- Feature description
+
+---
+
+_Last updated: [date]_

package/docs/guides/usage-guide.md

@@ -0,0 +1,87 @@
+# @reasonabletech/config-typescript Usage Guide
+
+This guide covers canonical setup for TypeScript presets in greenfield packages and apps.
+
+## Installation
+
+```bash
+pnpm add -D @reasonabletech/config-typescript typescript
+```
+
+## Quick Start
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/base.json"
+}
+```
+
+## Choose the Right Preset
+
+### Application Presets
+
+- `@reasonabletech/config-typescript/app.json`
+- `@reasonabletech/config-typescript/react-app.json`
+- `@reasonabletech/config-typescript/nextjs.json`
+- `@reasonabletech/config-typescript/server.json`
+
+### Library Presets
+
+- `@reasonabletech/config-typescript/library.json`
+- `@reasonabletech/config-typescript/react-library.json`
+- `@reasonabletech/config-typescript/browser-library.json`
+- `@reasonabletech/config-typescript/platform-library.json`
+
+### Specialized Presets
+
+- `@reasonabletech/config-typescript/chrome-extension.json`
+- `@reasonabletech/config-typescript/vscode-extension.json`
+- `@reasonabletech/config-typescript/tooling.json`
+- `@reasonabletech/config-typescript/eslint.json`
+- `@reasonabletech/config-typescript/strict.json`
+- `@reasonabletech/config-typescript/docs.json`
+
+## Configuration Examples
+
+### React App
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/react-app.json",
+  "compilerOptions": {
+    "baseUrl": "."
+  },
+  "include": ["src"]
+}
+```
+
+### Library
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/library.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}
+```
+
+## Troubleshooting
+
+### `extends` cannot be resolved
+
+Ensure the package is installed in the same workspace/project where `tsconfig.json` is evaluated.
+
+### Incompatible runtime module resolution
+
+Use the preset aligned with your runtime:
+
+- Node/Bun style runtimes: `base.json`, `app.json`, `server.json`
+- Next.js app router projects: `nextjs.json`
+
+## Related Documentation
+
+- [Package Docs Index](../README.md)
+- [Base Config Details](../api/base-config.md)
+- [Package README](../../README.md)

package/examples/README.md

@@ -0,0 +1,60 @@
+# @reasonabletech/config-typescript Examples
+
+These examples show practical `tsconfig` setups using exported `.json` presets.
+
+## Files In This Directory
+
+- [base-config.ts](./base-config.ts): baseline TypeScript project examples
+- [react-app-config.ts](./react-app-config.ts): React and Next.js app-oriented examples
+
+## Installation
+
+```bash
+pnpm add -D typescript @reasonabletech/config-typescript
+```
+
+## Quick Start
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/base.json",
+  "include": ["src/**/*"]
+}
+```
+
+## Preset Path Format
+
+Use package subpaths with `.json`:
+
+- `@reasonabletech/config-typescript/base.json`
+- `@reasonabletech/config-typescript/react-app.json`
+- `@reasonabletech/config-typescript/react-library.json`
+- `@reasonabletech/config-typescript/nextjs.json`
+- `@reasonabletech/config-typescript/server.json`
+- `@reasonabletech/config-typescript/strict.json`
+
+## Example: App + Test Config Split
+
+`tsconfig.json`:
+
+```json
+{
+  "extends": "@reasonabletech/config-typescript/app.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+`tsconfig.test.json`:
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["vitest/globals", "node"]
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}
+```

package/examples/base-config.ts

@@ -0,0 +1,46 @@
+/**
+ * Base configuration examples for projects that consume
+ * @reasonabletech/config-typescript.
+ */
+
+const baseTsConfig = {
+  extends: "@reasonabletech/config-typescript/base.json",
+  compilerOptions: {
+    outDir: "./dist",
+    rootDir: "./src",
+    baseUrl: ".",
+    paths: {
+      "@/*": ["src/*"],
+      "@/utils/*": ["src/utils/*"],
+    },
+  },
+  include: ["src/**/*"],
+  exclude: ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"],
+};
+
+const strictTsConfig = {
+  extends: "@reasonabletech/config-typescript/strict.json",
+  compilerOptions: {
+    outDir: "./dist",
+  },
+  include: ["src/**/*"],
+};
+
+const libraryTsConfig = {
+  extends: "@reasonabletech/config-typescript/library.json",
+  compilerOptions: {
+    outDir: "./dist",
+    rootDir: "./src",
+  },
+  include: ["src/**/*"],
+};
+
+const serverTsConfig = {
+  extends: "@reasonabletech/config-typescript/server.json",
+  compilerOptions: {
+    outDir: "./dist",
+  },
+  include: ["src/**/*"],
+};
+
+export { baseTsConfig, strictTsConfig, libraryTsConfig, serverTsConfig };

package/examples/react-app-config.ts

@@ -0,0 +1,64 @@
+/**
+ * React-oriented configuration examples.
+ */
+
+const reactAppTsConfig = {
+  extends: "@reasonabletech/config-typescript/react-app.json",
+  compilerOptions: {
+    baseUrl: ".",
+    paths: {
+      "@/*": ["src/*"],
+      "@/components/*": ["src/components/*"],
+      "@/hooks/*": ["src/hooks/*"],
+    },
+    types: ["vite/client", "node"],
+  },
+  include: ["src/**/*", "vite-env.d.ts"],
+  exclude: ["node_modules", "dist"],
+};
+
+const reactLibraryTsConfig = {
+  extends: "@reasonabletech/config-typescript/react-library.json",
+  compilerOptions: {
+    outDir: "./dist",
+    rootDir: "./src",
+  },
+  include: ["src/**/*"],
+  exclude: ["**/*.test.tsx", "**/*.spec.tsx"],
+};
+
+const nextJsTsConfig = {
+  extends: "@reasonabletech/config-typescript/nextjs.json",
+  compilerOptions: {
+    baseUrl: ".",
+    paths: {
+      "@/*": ["src/*"],
+    },
+  },
+  include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+};
+
+const reactTestTsConfig = {
+  extends: "./tsconfig.json",
+  compilerOptions: {
+    types: ["vitest/globals", "jsdom", "@testing-library/jest-dom"],
+  },
+  include: ["src/**/*", "tests/**/*", "**/*.test.ts", "**/*.test.tsx"],
+};
+
+const reactPackageScripts = {
+  scripts: {
+    dev: "vite",
+    build: "tsc --noEmit && vite build",
+    typecheck: "tsc --noEmit",
+    test: "vitest",
+  },
+};
+
+export {
+  reactAppTsConfig,
+  reactLibraryTsConfig,
+  nextJsTsConfig,
+  reactTestTsConfig,
+  reactPackageScripts,
+};

package/lib/app.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/lib/base.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "inlineSources": false,
+    "isolatedModules": true,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "customConditions": ["source"],
+    "allowImportingTsExtensions": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "preserveWatchOutput": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": false,
+    "strictNullChecks": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "noImplicitReturns": false,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": false,
+    "noUncheckedIndexedAccess": false,
+    "useUnknownInCatchVariables": true,
+    "incremental": true,
+    "types": ["node"]
+  }
+}

package/lib/browser-library.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2023", "DOM", "DOM.Iterable"]
+  }
+}

package/lib/chrome-extension.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["chrome", "node"]
+  }
+}

package/lib/docs.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "skipLibCheck": false
+  }
+}

package/lib/eslint.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "ESLint Config",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "emitDeclarationOnly": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/lib/library.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "emitDeclarationOnly": true
+  }
+}

package/lib/nextjs.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowJs": true,
+    "jsx": "preserve",
+    "jsxImportSource": "react",
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "noEmit": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  }
+}

package/lib/platform-library.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+    "types": ["next", "react", "react-dom", "node"]
+  }
+}

package/lib/react-app.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "allowJs": true,
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "emitDeclarationOnly": false,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"]
+  }
+}

package/lib/react-library.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "react"
+  }
+}

package/lib/server.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/lib/strict.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "allowUnusedLabels": false,
+    "allowUnreachableCode": false
+  }
+}

package/lib/tooling.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json"
+}

package/lib/vscode-extension.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "downlevelIteration": true,
+    "types": ["vscode", "node"]
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@reasonabletech/config-typescript",
+  "version": "0.1.0",
+  "description": "Shared TypeScript configuration presets",
+  "keywords": [
+    "reasonabletech",
+    "config",
+    "typescript",
+    "tsconfig",
+    "typescript-config",
+    "typescript-preset",
+    "compiler-options"
+  ],
+  "type": "module",
+  "files": [
+    "lib/**/*.json",
+    "docs/**/*",
+    "examples/**/*"
+  ],
+  "exports": {
+    "./base.json": "./lib/base.json",
+    "./app.json": "./lib/app.json",
+    "./library.json": "./lib/library.json",
+    "./browser-library.json": "./lib/browser-library.json",
+    "./chrome-extension.json": "./lib/chrome-extension.json",
+    "./eslint.json": "./lib/eslint.json",
+    "./nextjs.json": "./lib/nextjs.json",
+    "./platform-library.json": "./lib/platform-library.json",
+    "./react-app.json": "./lib/react-app.json",
+    "./react-library.json": "./lib/react-library.json",
+    "./server.json": "./lib/server.json",
+    "./strict.json": "./lib/strict.json",
+    "./tooling.json": "./lib/tooling.json",
+    "./vscode-extension.json": "./lib/vscode-extension.json",
+    "./docs.json": "./lib/docs.json"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "Reasonable Tech Company",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ReasonableTech/core-utils.git",
+    "directory": "packages/config-typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/ReasonableTech/core-utils/issues"
+  },
+  "homepage": "https://github.com/ReasonableTech/core-utils/tree/main/packages/config-typescript",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "echo 'No build needed for configuration package'",
+    "clean": "rm -rf .turbo node_modules tsconfig.tsbuildinfo",
+    "lint": "echo \"No lint target for config-only package\"",
+    "lint:check": "echo \"No lint target for config-only package\"",
+    "test": "echo 'No tests for configuration package'",
+    "typecheck": "echo 'No TypeScript files to check in configuration package'",
+    "verify:release": "pnpm typecheck && pnpm lint:check && pnpm test && pnpm build"
+  }
+}