@dimensional-innovations/tool-config 4.0.0 → 5.0.1

package/src/tools/typescript/README.md

@@ -1,665 +0,0 @@
-# TypeScript Configuration
-
-Zero-config TypeScript type checking for modern JavaScript/TypeScript projects.
-
-## Features
-
-- **Auto-detection** of framework, environment, and TypeScript setup
-- **Modern tooling** with tsgo (10x faster than tsc)
-- **Framework-specific** configurations for React, Vue, Svelte, Solid, Astro, Angular, Vanilla, and Node.js
-- **Strict mode** enabled by default with opt-out
-- **Smart checker selection** - tsgo → vue-tsc → tsc fallback chain
-- **Zero config** - works out of the box with sensible defaults
-
-## Installation
-
-```bash
-yarn add --save-dev @dimensional-innovations/tool-config typescript
-```
-
-For modern performance with tsgo:
-
-```bash
-yarn add --save-dev @typescript/native-preview
-```
-
-For Vue projects, also install:
-
-```bash
-yarn add --save-dev vue-tsc
-```
-
-## Quick Start
-
-Create `tsconfig.json` in your project root:
-
-```json
-{
-  "extends": "./tsconfig.base.json",
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}
-```
-
-Create `tsconfig.base.json` using the package:
-
-```javascript
-// tsconfig.base.json
-import { createConfig } from '@dimensional-innovations/tool-config'
-
-export default await createConfig('typescript', { framework: 'auto' })
-```
-
-Add type checking script to `package.json`:
-
-```json
-{
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "typecheck:watch": "tsc --noEmit --watch"
-  }
-}
-```
-
-If you have tsgo installed, the package will auto-generate the appropriate command.
-
-## Configuration Options
-
-### Basic Options
-
-```javascript
-createConfig('typescript', {
-  framework: 'auto', // 'auto', 'react', 'vue', 'svelte', 'solid', 'astro', 'angular', 'vanilla', 'node'
-  environment: 'auto', // 'auto', 'browser', 'node', 'universal'
-  checker: 'auto', // 'auto', 'modern' (tsgo), 'legacy' (tsc/vue-tsc)
-  strict: true, // Enable strict type checking
-  cwd: process.cwd() // Working directory for detection
-})
-```
-
-### Compiler Options Override
-
-```javascript
-createConfig('typescript', {
-  framework: 'react',
-  compilerOptions: {
-    target: 'ES2020',
-    outDir: './dist',
-    rootDir: './src',
-    baseUrl: '.',
-    paths: {
-      '@/*': ['src/*']
-    }
-  }
-})
-```
-
-## Framework-Specific Setup
-
-### React
-
-Auto-detected from `react` in dependencies.
-
-**Default configuration:**
-
-- JSX: `react-jsx` (modern React 17+ runtime)
-- Libraries: ES2022, DOM, DOM.Iterable
-- Target: ES2020
-
-**Example tsconfig.base.json:**
-
-```javascript
-export default await createConfig('typescript', { framework: 'react' })
-```
-
-**Type checking:**
-
-```bash
-yarn add --save-dev @types/react @types/react-dom
-yarn typecheck
-```
-
-### Vue
-
-Auto-detected from `vue`, `vue-router`, or `pinia` in dependencies.
-
-**Default configuration:**
-
-- JSX: `preserve` (Vue compiler handles it)
-- JSX Import Source: `vue`
-- Libraries: ES2022, DOM, DOM.Iterable
-- Types: `vite/client`
-- Vue compiler options included
-
-**Example tsconfig.base.json:**
-
-```javascript
-export default await createConfig('typescript', { framework: 'vue' })
-```
-
-**Type checking:**
-
-```bash
-yarn add --save-dev vue-tsc
-yarn typecheck
-```
-
-**Note:** Vue projects should use `vue-tsc` instead of `tsc` for proper .vue file support.
-
-### Svelte
-
-Auto-detected from `svelte` in dependencies.
-
-**Default configuration:**
-
-- Libraries: ES2022, DOM, DOM.Iterable
-- Types: `svelte`
-
-**Example tsconfig.base.json:**
-
-```javascript
-export default await createConfig('typescript', { framework: 'svelte' })
-```
-
-**Type checking:**
-
-```bash
-yarn add --save-dev @sveltejs/vite-plugin-svelte
-yarn typecheck
-```
-
-### Solid
-
-Auto-detected from `solid-js` in dependencies.
-
-**Default configuration:**
-
-- JSX: `preserve`
-- JSX Import Source: `solid-js`
-- Libraries: ES2022, DOM, DOM.Iterable
-
-**Example tsconfig.base.json:**
-
-```javascript
-export default await createConfig('typescript', { framework: 'solid' })
-```
-
-### Astro
-
-Auto-detected from `astro` in dependencies.
-
-**Default configuration:**
-
-- JSX: `react-jsx`
-- Libraries: ES2022, DOM, DOM.Iterable
-- Types: `astro/client`
-
-**Example tsconfig.base.json:**
-
-```javascript
-export default await createConfig('typescript', { framework: 'astro' })
-```
-
-### Angular
-
-Auto-detected from `@angular/core` in dependencies.
-
-**Default configuration:**
-
-- Decorators: enabled
-- Emit decorator metadata: enabled
-- Libraries: ES2022, DOM, DOM.Iterable
-
-**Example tsconfig.base.json:**
-
-```javascript
-export default await createConfig('typescript', { framework: 'angular' })
-```
-
-### Node.js
-
-Auto-detected from `type: "module"` without frontend frameworks.
-
-**Default configuration:**
-
-- Module: `NodeNext`
-- Module Resolution: `NodeNext`
-- Libraries: ES2022 (no DOM)
-- Types: `node`
-
-**Example tsconfig.base.json:**
-
-```javascript
-export default await createConfig('typescript', { framework: 'node' })
-```
-
-**Type checking:**
-
-```bash
-yarn add --save-dev @types/node
-yarn typecheck
-```
-
-### Vanilla JavaScript
-
-Default when no framework detected.
-
-**Default configuration:**
-
-- Libraries: ES2022, DOM, DOM.Iterable
-- Target: ES2020
-
-**Example tsconfig.base.json:**
-
-```javascript
-export default await createConfig('typescript', { framework: 'vanilla' })
-```
-
-## Type Checker Selection
-
-The package automatically selects the best type checker for your project:
-
-1. **Vue projects:** Prefers `vue-tsc` for .vue file support
-2. **Modern projects:** Uses `tsgo` when installed (10x faster)
-3. **Fallback:** Standard `tsc` for compatibility
-
-### Using tsgo (Recommended)
-
-tsgo is a Go port of the TypeScript compiler that is 10x faster than tsc.
-
-**Installation:**
-
-```bash
-yarn add --save-dev @typescript/native-preview
-```
-
-**Usage:**
-
-```bash
-yarn tsgo --noEmit
-```
-
-The package will automatically detect tsgo and use it when available.
-
-### Forcing Checker Preference
-
-```javascript
-// Always use tsgo (modern)
-createConfig('typescript', { checker: 'modern' })
-
-// Always use tsc/vue-tsc (legacy)
-createConfig('typescript', { checker: 'legacy' })
-
-// Auto-detect (default)
-createConfig('typescript', { checker: 'auto' })
-```
-
-## Environment Detection
-
-The package detects three environment types:
-
-### Browser
-
-**Auto-detected from:**
-
-- Frontend framework presence (React, Vue, Svelte, etc.)
-- `type: "module"` without backend indicators
-
-**Configuration:**
-
-- Target: ES2020
-- Libraries: ES2022, DOM, DOM.Iterable
-
-### Node.js
-
-**Auto-detected from:**
-
-- `type: "module"` without frontend frameworks
-- Backend-only setup
-
-**Configuration:**
-
-- Target: ES2022
-- Libraries: ES2022 (no DOM)
-- Types: `node`
-
-### Universal
-
-**Auto-detected from:**
-
-- SSR frameworks (Next.js, Nuxt, SvelteKit, Astro)
-- Both browser and Node.js indicators
-
-**Configuration:**
-
-- Target: ES2020 (browser compatibility)
-- Libraries: ES2022, DOM, DOM.Iterable
-- Types: `node` (for SSR)
-
-## Strict Mode
-
-Strict mode is enabled by default for better type safety.
-
-**Includes:**
-
-- `strict: true`
-- `noImplicitAny: true`
-- `strictNullChecks: true`
-- `strictFunctionTypes: true`
-- `strictBindCallApply: true`
-- `strictPropertyInitialization: true`
-- `noImplicitThis: true`
-- `alwaysStrict: true`
-- `noUnusedLocals: true`
-- `noUnusedParameters: true`
-- `noImplicitReturns: true`
-- `noFallthroughCasesInSwitch: true`
-
-**Disable strict mode:**
-
-```javascript
-createConfig('typescript', { strict: false })
-```
-
-This disables `strict`, `noImplicitAny`, `strictNullChecks`, and other strict-related options while keeping quality checks like `noUnusedLocals`.
-
-## Advanced Configuration
-
-### Path Aliases
-
-```javascript
-createConfig('typescript', {
-  compilerOptions: {
-    baseUrl: '.',
-    paths: {
-      '@/*': ['src/*'],
-      '@components/*': ['src/components/*'],
-      '@utils/*': ['src/utils/*']
-    }
-  }
-})
-```
-
-### Custom Output Directory
-
-```javascript
-createConfig('typescript', {
-  compilerOptions: {
-    outDir: './dist',
-    rootDir: './src',
-    declarationDir: './types'
-  }
-})
-```
-
-### Monorepo Setup
-
-```javascript
-createConfig('typescript', {
-  compilerOptions: {
-    composite: true,
-    declarationMap: true,
-    incremental: true,
-    tsBuildInfoFile: './dist/.tsbuildinfo'
-  }
-})
-```
-
-### Custom Include/Exclude
-
-The base configuration includes sensible defaults:
-
-```json
-{
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "build", "out", "coverage", ".nyc_output"]
-}
-```
-
-Override these in your `tsconfig.json`:
-
-```json
-{
-  "extends": "./tsconfig.base.json",
-  "include": ["src/**/*", "tests/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
-}
-```
-
-## Helper Functions
-
-### detectTypeChecker
-
-Get the recommended type checker for your project:
-
-```javascript
-import { detectTypeChecker } from '@dimensional-innovations/tool-config/src/tools/typescript/checker-detection.js'
-
-const checker = detectTypeChecker('vue', 'auto')
-console.log(checker) // 'vue-tsc', 'tsgo', or 'tsc'
-```
-
-### getTypeCheckCommand
-
-Generate the appropriate type check command:
-
-```javascript
-import { getTypeCheckCommand } from '@dimensional-innovations/tool-config/src/tools/typescript/checker-detection.js'
-
-const cmd = getTypeCheckCommand('tsgo', { watch: true })
-console.log(cmd) // 'tsgo --noEmit --watch'
-```
-
-### getTypeCheckCommandWithFallback
-
-Generate a command with fallback to tsc/vue-tsc:
-
-```javascript
-import { getTypeCheckCommandWithFallback } from '@dimensional-innovations/tool-config/src/tools/typescript/checker-detection.js'
-
-const cmd = getTypeCheckCommandWithFallback('tsgo', 'vue')
-console.log(cmd) // 'tsgo --noEmit || vue-tsc --noEmit'
-```
-
-## Troubleshooting
-
-### "Cannot find module" errors
-
-**Problem:** TypeScript can't find type definitions for dependencies.
-
-**Solution:** Install the @types package:
-
-```bash
-yarn add --save-dev @types/node @types/react @types/react-dom
-```
-
-### Vue .vue files not type checking
-
-**Problem:** `.vue` files showing type errors or not being checked.
-
-**Solution:** Install and use vue-tsc:
-
-```bash
-yarn add --save-dev vue-tsc
-yarn vue-tsc --noEmit
-```
-
-### tsgo not found
-
-**Problem:** Package detects tsgo but it's not installed.
-
-**Solution:** Install @typescript/native-preview:
-
-```bash
-yarn add --save-dev @typescript/native-preview
-```
-
-### Slow type checking
-
-**Problem:** Type checking is slow in large projects.
-
-**Solutions:**
-
-1. Install tsgo for 10x faster checking
-2. Enable incremental mode in your tsconfig.json:
-
-```json
-{
-  "compilerOptions": {
-    "incremental": true,
-    "tsBuildInfoFile": "./dist/.tsbuildinfo"
-  }
-}
-```
-
-### Path alias not resolving
-
-**Problem:** Import aliases like `@/components` not working.
-
-**Solution:** Add path mapping to your config:
-
-```javascript
-createConfig('typescript', {
-  compilerOptions: {
-    baseUrl: '.',
-    paths: {
-      '@/*': ['src/*']
-    }
-  }
-})
-```
-
-Also ensure your build tool (Vite, webpack, etc.) is configured to resolve the same aliases.
-
-### Strict mode too restrictive
-
-**Problem:** Too many type errors in existing codebase.
-
-**Solution:** Gradually adopt strict mode:
-
-```javascript
-// Disable strict mode initially
-createConfig('typescript', { strict: false })
-
-// Or selectively enable strict checks
-createConfig('typescript', {
-  strict: false,
-  compilerOptions: {
-    strictNullChecks: true, // Enable only null checks
-    noImplicitAny: true // Enable only implicit any checks
-  }
-})
-```
-
-## Performance Tips
-
-1. **Use tsgo** - Install `@typescript/native-preview` for 10x faster type checking
-2. **Enable incremental** - Set `incremental: true` and `tsBuildInfoFile` in tsconfig
-3. **Use composite projects** - For monorepos, enable `composite: true`
-4. **Skip lib check** - Already enabled by default with `skipLibCheck: true`
-5. **Use project references** - For multi-package repos, use TypeScript project references
-
-## Integration with Other Tools
-
-### ESLint
-
-This package includes ESLint support. Use both together:
-
-```javascript
-// eslint.config.js
-import { createConfig } from '@dimensional-innovations/tool-config'
-export default await createConfig('eslint', { framework: 'auto' })
-
-// tsconfig.base.json
-export default await createConfig('typescript', { framework: 'auto' })
-```
-
-### Prettier
-
-Format TypeScript files with Prettier:
-
-```javascript
-// prettier.config.js
-import { createConfig } from '@dimensional-innovations/tool-config'
-export default createConfig('prettier', { framework: 'auto' })
-```
-
-### Vitest
-
-TypeScript works automatically with Vitest. Add to your config:
-
-```javascript
-// vitest.config.js
-import { defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node'
-  }
-})
-```
-
-## Examples
-
-See the [examples directory](../../../examples) for complete TypeScript setup examples:
-
-- [React App](../../../examples/react-app)
-- [Vue App](../../../examples/vue-app)
-- [Svelte App](../../../examples/svelte-app)
-- [Solid App](../../../examples/solid-app)
-- [Astro App](../../../examples/astro-app)
-- [Angular App](../../../examples/angular-app)
-- [Vanilla JavaScript](../../../examples/vanilla-js)
-- [Node.js Backend](../../../examples/node-backend)
-
-## API Reference
-
-### createConfig('typescript', options)
-
-**Parameters:**
-
-| Option            | Type    | Default         | Description                                    |
-| ----------------- | ------- | --------------- | ---------------------------------------------- |
-| `framework`       | string  | `'auto'`        | Framework type or 'auto' for detection         |
-| `environment`     | string  | `'auto'`        | Environment type or 'auto' for detection       |
-| `checker`         | string  | `'auto'`        | Checker preference: 'auto', 'modern', 'legacy' |
-| `strict`          | boolean | `true`          | Enable strict type checking                    |
-| `compilerOptions` | object  | `{}`            | Override compiler options                      |
-| `cwd`             | string  | `process.cwd()` | Working directory for detection                |
-
-**Returns:** TypeScript configuration object with metadata
-
-**Example:**
-
-```javascript
-const config = await createConfig('typescript', {
-  framework: 'react',
-  environment: 'browser',
-  checker: 'modern',
-  strict: true,
-  compilerOptions: {
-    target: 'ES2020',
-    baseUrl: '.'
-  }
-})
-
-console.log(config)
-// {
-//   compilerOptions: { ... },
-//   include: ['src/**/*'],
-//   exclude: ['node_modules', 'dist', ...],
-//   _meta: {
-//     framework: 'react',
-//     environment: 'browser',
-//     checker: 'tsgo',
-//     experimental: true,
-//     generatedBy: '@dimensional-innovations/tool-config'
-//   }
-// }
-```
-
-## License
-
-MIT