@codefast/typescript-config 0.3.10 → 0.3.11-canary.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @codefast/typescript-config
 
+## 0.3.11-canary.0
+
+### Patch Changes
+
+- [`135c6be`](https://github.com/codefastlabs/codefast/commit/135c6bed9d1bc1e96bad3173adab1bf32d74322f) Thanks [@thevuong](https://github.com/thevuong)! - chore: update linting and formatting scripts in package.json
+
+- [`610cf7a`](https://github.com/codefastlabs/codefast/commit/610cf7a7f9b6e5b37be21e7675ea363ef1020639) Thanks [@thevuong](https://github.com/thevuong)! - fix(hooks): handle missing `navigator.clipboard.writeText` gracefully
+
+- [`3e90474`](https://github.com/codefastlabs/codefast/commit/3e90474fbbb9f8ac626c5949bfdbac2eaf1cb3e8) Thanks [@thevuong](https://github.com/thevuong)! - chore: update project configuration and dependencies
+
+- [`5c09d4c`](https://github.com/codefastlabs/codefast/commit/5c09d4ce2df564dc7ac6727b00cfa668164a1af4) Thanks [@thevuong](https://github.com/thevuong)! - refactor(config): rename `check-types` to `typecheck` and update usage
+
 ## 0.3.10
 
 ### Patch Changes

package/README.md

@@ -1,13 +1,45 @@
-# TypeScript Config
-
-Shared TypeScript configuration presets for the CodeFast monorepo, providing standardized TypeScript settings for different project types including React applications, Next.js projects, libraries, and base configurations.
-
-![NPM Version](https://img.shields.io/npm/v/@codefast/typescript-config.svg)
+# @codefast/typescript-config
+
+Shared TypeScript configuration presets providing standardized compiler settings for different project types including base projects, libraries, React applications, and Next.js.
+
+[![CI](https://github.com/codefastlabs/codefast/actions/workflows/release.yml/badge.svg)](https://github.com/codefastlabs/codefast/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/@codefast/typescript-config.svg)](https://www.npmjs.com/package/@codefast/typescript-config)
+[![npm downloads](https://img.shields.io/npm/dm/@codefast/typescript-config.svg)](https://www.npmjs.com/package/@codefast/typescript-config)
+[![license](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Base Configuration](#base-configuration)
+  - [Library Configuration](#library-configuration)
+  - [React Configuration](#react-configuration)
+  - [Next.js Configuration](#nextjs-configuration)
+- [Configurations](#configurations)
+- [API Reference](#api-reference)
+- [Compatibility](#compatibility)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+- [Changelog](#changelog)
+
+## Overview
+
+`@codefast/typescript-config` provides opinionated, strict TypeScript presets that can be extended in any project. Each preset is tuned for a specific project type, so you get the right compiler options without manual configuration.
+
+**Key features:**
+
+- **Strict Type Checking** -- Enables all strict options for maximum type safety.
+- **Modern JavaScript** -- Targets ESNext with full ESNext lib support.
+- **Bundler Module Resolution** -- Optimized for modern bundlers (Vite, Turbopack, esbuild).
+- **JavaScript Support** -- Allows `.js` files alongside TypeScript.
+- **JSON Support** -- Resolves JSON modules natively.
+- **Isolated Modules** -- Transpile each file separately for faster builds.
 
 ## Installation
 
-Install the package via pnpm (recommended):
-
 ```bash
 pnpm add -D @codefast/typescript-config
 ```
@@ -18,14 +50,14 @@ Or using npm:
 npm install --save-dev @codefast/typescript-config
 ```
 
-**Requirements**:
+**Requirements:**
 
-- Node.js version 20.0.0 or higher
-- TypeScript version 5.0.0 or higher
+- Node.js >= 24.0.0 (LTS)
+- TypeScript >= 5.0.0
 
 ## Quick Start
 
-Create a `tsconfig.json` file in your project and extend from the appropriate configuration:
+Create a `tsconfig.json` in your project root and extend from the appropriate preset:
 
 ```json
 {
@@ -37,7 +69,7 @@ Create a `tsconfig.json` file in your project and extend from the appropriate co
 
 ### Base Configuration
 
-Basic configuration for all TypeScript projects:
+For general TypeScript projects:
 
 ```json
 {
@@ -52,7 +84,7 @@ Basic configuration for all TypeScript projects:
 
 ### Library Configuration
 
-For developing libraries and packages:
+For NPM packages and shared libraries (no DOM libs):
 
 ```json
 {
@@ -88,184 +120,200 @@ For Next.js applications:
 ```json
 {
   "extends": "@codefast/typescript-config/next.json",
-  "include": [
-    "next-env.d.ts",
-    "**/*.ts",
-    "**/*.tsx",
-    ".next/types/**/*.ts"
-  ],
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
   "exclude": ["node_modules"]
 }
 ```
 
 ## Configurations
 
-### Available Configurations
+### Available Presets
+
+| Configuration  | Extends     | Description                                      | Use Case                       |
+| -------------- | ----------- | ------------------------------------------------ | ------------------------------ |
+| `base.json`    | --          | Strict base configuration with ESNext target     | All TypeScript projects        |
+| `library.json` | `base.json` | ESNext-only libs (no DOM)                        | NPM packages, shared libraries |
+| `react.json`   | `base.json` | Adds `react-jsx` transform                       | React components and apps      |
+| `next.json`    | `base.json` | Incremental builds, JSX preserve, Next.js plugin | Next.js applications           |
 
-| Configuration | Description | Use Case |
-|---------------|-------------|----------|
-| `base.json` | Basic configuration with strict settings | Base for all projects |
-| `library.json` | Extends base, adds library-specific options | NPM packages, shared libraries |
-| `react.json` | Extends base, adds React JSX support | React components and apps |
-| `next.json` | Extends base, optimized for Next.js | Next.js applications |
+### Base Configuration Details
 
-### Base Configuration Features
+| Option              | Value                       | Purpose                                  |
+| ------------------- | --------------------------- | ---------------------------------------- |
+| `strict`            | `true`                      | Enables all strict type-checking options |
+| `target`            | `ESNext`                    | Latest JavaScript features               |
+| `module`            | `ESNext`                    | ESM module system                        |
+| `moduleResolution`  | `bundler`                   | Optimized for modern bundlers            |
+| `lib`               | `DOM, DOM.Iterable, ESNext` | Browser and ESNext APIs                  |
+| `isolatedModules`   | `true`                      | File-level transpilation                 |
+| `noEmit`            | `true`                      | Lets the bundler handle output           |
+| `allowJs`           | `true`                      | JavaScript file support                  |
+| `resolveJsonModule` | `true`                      | JSON import support                      |
+| `esModuleInterop`   | `true`                      | CommonJS/ESM interop                     |
+| `skipLibCheck`      | `true`                      | Skip type checking of declaration files  |
 
-- **Strict Type Checking**: Enables all strict options
-- **Modern JavaScript**: Targets ESNext with full ESNext lib support
-- **Module Resolution**: Node-style resolution with ESNext modules
-- **Developer Experience**: Force consistent casing, no unused variables/parameters
-- **JSON Support**: Resolve JSON modules
-- **Isolated Modules**: Transpile each file separately
+### Library Configuration Details
 
-### Library Configuration Features
+Extends `base.json` with:
 
-- **Declaration Generation**: Automatically generates `.d.ts` files
-- **Source Maps**: Generate source maps for debugging
-- **Strip Internal**: Remove internal declarations from output
-- **ESNext Only**: Does not include DOM libs
+| Option | Value    | Purpose                                                       |
+| ------ | -------- | ------------------------------------------------------------- |
+| `lib`  | `ESNext` | No DOM libs -- library code should not depend on browser APIs |
 
-### React Configuration Features
+### React Configuration Details
 
-- **Modern JSX Transform**: Uses `react-jsx` transform
-- **React Import Source**: Automatically import React when needed
-- **DOM Support**: Full DOM and DOM.Iterable libs
+Extends `base.json` with:
 
-### Next.js Configuration Features
+| Option | Value       | Purpose                                         |
+| ------ | ----------- | ----------------------------------------------- |
+| `jsx`  | `react-jsx` | Modern JSX transform (no `import React` needed) |
 
-- **JavaScript Support**: Allow `.js` files
-- **Incremental Compilation**: Faster subsequent builds
-- **JSX Preserve**: Let Next.js handle JSX transform
-- **Bundler Resolution**: Optimized for bundler
-- **No Emit**: Next.js handles compilation
-- **Next.js Plugin**: TypeScript plugin support
+### Next.js Configuration Details
+
+Extends `base.json` with:
+
+| Option        | Value                  | Purpose                               |
+| ------------- | ---------------------- | ------------------------------------- |
+| `incremental` | `true`                 | Faster subsequent builds              |
+| `jsx`         | `preserve`             | Let Next.js handle JSX transformation |
+| `plugins`     | `[{ "name": "next" }]` | Next.js TypeScript plugin             |
 
 ## API Reference
 
-### Configuration Files
-
-#### `base.json`
-
-Base configuration with essential compiler options:
-
-```typescript
-interface BaseConfig {
-  compilerOptions: {
-    allowSyntheticDefaultImports: true;
-    declaration: true;
-    esModuleInterop: true;
-    forceConsistentCasingInFileNames: true;
-    isolatedModules: true;
-    lib: ["DOM", "DOM.Iterable", "ESNext"];
-    module: "ESNext";
-    moduleDetection: "force";
-    moduleResolution: "node";
-    noEmitOnError: true;
-    noFallthroughCasesInSwitch: true;
-    noImplicitOverride: true;
-    noImplicitReturns: true;
-    noUnusedLocals: true;
-    noUnusedParameters: true;
-    resolveJsonModule: true;
-    skipLibCheck: true;
-    strict: true;
-    target: "ESNext";
-    useDefineForClassFields: true;
-  };
+### base.json
+
+```json
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ESNext"
+  }
+}
+```
+
+### library.json
+
+```json
+{
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"]
+  }
 }
 ```
 
-#### `library.json`
+### react.json
+
+```json
+{
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}
+```
 
-Library-specific configuration extending base:
+### next.json
 
-```typescript
-interface LibraryConfig extends BaseConfig {
-  compilerOptions: BaseConfig["compilerOptions"] & {
-    declaration: true;
-    lib: ["ESNext"];
-    sourceMap: true;
-    stripInternal: true;
-  };
+```json
+{
+  "extends": "./base.json",
+  "compilerOptions": {
+    "incremental": true,
+    "jsx": "preserve",
+    "plugins": [{ "name": "next" }]
+  }
 }
 ```
 
-#### `react.json`
+## Compatibility
+
+| Technology | Minimum Version | Notes                                |
+| ---------- | --------------- | ------------------------------------ |
+| TypeScript | 5.0.0           | Required                             |
+| Node.js    | 24.0.0          | Required                             |
+| React      | 18.0.0+         | When using `react.json`              |
+| Next.js    | 14.0.0+         | When using `next.json`               |
+| Vite       | 5.0.0+          | Works with bundler module resolution |
+| Turbopack  | Any             | Works with bundler module resolution |
+| esbuild    | 0.19+           | Works with bundler module resolution |
+
+## Troubleshooting
+
+### Cannot find module or type declarations
+
+When extending from `@codefast/typescript-config`, make sure the package is installed as a dev dependency and your `tsconfig.json` is at the project root:
+
+```bash
+pnpm add -D @codefast/typescript-config
+```
+
+### Conflicting `lib` settings
 
-React-specific configuration:
+If you need DOM types in a library project, override the `lib` option in your local `tsconfig.json`:
 
-```typescript
-interface ReactConfig extends BaseConfig {
-  compilerOptions: BaseConfig["compilerOptions"] & {
-    jsx: "react-jsx";
-    jsxImportSource: "react";
-  };
+```json
+{
+  "extends": "@codefast/typescript-config/library.json",
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ESNext"]
+  }
 }
 ```
 
-#### `next.json`
+### Path aliases not resolving
 
-Next.js-specific configuration:
+When using path aliases, add them to both `tsconfig.json` and your bundler configuration:
 
-```typescript
-interface NextConfig extends BaseConfig {
-  compilerOptions: BaseConfig["compilerOptions"] & {
-    allowJs: true;
-    incremental: true;
-    jsx: "preserve";
-    moduleResolution: "bundler";
-    noEmit: true;
-    plugins: [{ name: "next" }];
-  };
+```json
+{
+  "extends": "@codefast/typescript-config/base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
 }
 ```
 
-## Contributing
+### Incremental build issues with Next.js
 
-We welcome all contributions! To start developing:
+If you encounter stale type errors, delete the `.tsbuildinfo` file and rebuild:
 
-### Environment Setup
+```bash
+rm -f tsconfig.tsbuildinfo
+pnpm build
+```
+
+## Contributing
 
-1. Fork this repository.
-2. Clone to your machine: `git clone <your-fork-url>`
-3. Install dependencies: `pnpm install`
-4. Create a new branch: `git checkout -b feature/feature-name`
+We welcome contributions! Please see the [contributing guide](../../README.md#contributing) in the root of this repository for detailed instructions.
 
-### Development Workflow
+For package-specific development:
 
 ```bash
 # Build all packages
 pnpm build:packages
 
-# Development mode for typescript-config
-pnpm dev --filter=@codefast/typescript-config
-
-# Run tests
-pnpm test --filter=@codefast/typescript-config
-
-# Lint and format
-pnpm lint:fix
+# Lint and format (from repo root)
+pnpm lint
 pnpm format
 ```
 
-5. Commit and submit pull request.
-
 ## License
 
-Distributed under the MIT License. See [LICENSE](../../LICENSE) for more information.
-
-## Contact
-
-- npm: [@codefast/typescript-config](https://www.npmjs.com/package/@codefast/typescript-config)
-- GitHub: [codefastlabs/codefast](https://github.com/codefastlabs/codefast)
-- Issues: [GitHub Issues](https://github.com/codefastlabs/codefast/issues)
-- Documentation: [TypeScript Config Docs](https://github.com/codefastlabs/codefast/tree/main/packages/typescript-config)
-
-## Compatibility
+Distributed under the MIT License. See [LICENSE](../../LICENSE) for more details.
 
-This package is compatible with:
+## Changelog
 
-- **TypeScript**: 5.0.0+
-- **Node.js**: 20.0.0+
-- **React**: 18.0.0+ (when using react.json)
-- **Next.js**: 14.0.0+ (when using next.json)
+See [CHANGELOG.md](./CHANGELOG.md) for a complete list of changes and version history.

package/package.json

@@ -1,41 +1,41 @@
 {
   "name": "@codefast/typescript-config",
-  "version": "0.3.10",
+  "version": "0.3.11-canary.0",
   "description": "Shared TypeScript configuration for the monorepo",
   "keywords": [
-    "typescript",
-    "tsconfig",
+    "browser",
     "configuration",
+    "library",
     "monorepo",
-    "react",
     "next",
     "node",
-    "browser",
-    "library"
+    "react",
+    "tsconfig",
+    "typescript"
   ],
   "homepage": "https://github.com/codefastlabs/codefast/tree/main/packages/typescript-config#readme",
   "bugs": {
     "url": "https://github.com/codefastlabs/codefast/issues"
   },
+  "license": "MIT",
+  "author": "Vuong Phan <mr.thevuong@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/codefastlabs/codefast.git",
     "directory": "packages/typescript-config"
   },
-  "license": "MIT",
-  "author": "Vuong Phan <mr.thevuong@gmail.com>",
-  "exports": {
-    "./base.json": "./base.json",
-    "./library.json": "./library.json",
-    "./next.json": "./next.json",
-    "./react.json": "./react.json"
-  },
   "files": [
     "*.json",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
+  "exports": {
+    "./base.json": "./base.json",
+    "./library.json": "./library.json",
+    "./next.json": "./next.json",
+    "./react.json": "./react.json"
+  },
   "publishConfig": {
     "access": "public"
   }