@ilo-org/typescript-config

TypeScript configuration for ILO Design System projects

This package provides sensible TypeScript compiler defaults that enforce strict type checking and modern JavaScript/TypeScript features. It's designed to work seamlessly with @ilo-org/eslint-config for a complete type-safe development experience.

Requirements

• TypeScript 4.x or higher
• Node.js with ES modules support

Installation

npm install -D @ilo-org/typescript-config
# or
pnpm add -D @ilo-org/typescript-config
# or
yarn add -D @ilo-org/typescript-config

Usage

Basic Usage

Create a tsconfig.json file in your project root and extend this configuration:

{
  "extends": "@ilo-org/typescript-config",
  "compilerOptions": {
    "outDir": "dist"
  }
}

Alternatively, you can reference the full path:

{
  "extends": "@ilo-org/typescript-config/tsconfig.json",
  "compilerOptions": {
    "outDir": "dist"
  }
}

Extending Configuration

You can override or add compiler options as needed:

{
  "extends": "@ilo-org/typescript-config",
  "compilerOptions": {
    "outDir": "lib",
    "declaration": true,
    "declarationDir": "lib/types"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Configuration Options

This configuration includes the following TypeScript compiler options:

Module System

| Option | Value | Description | | ------------------------------ | -------- | ------------------------------------------------------------- | | module | esnext | Use the latest ES module format | | moduleResolution | node | Use Node.js-style module resolution | | esModuleInterop | true | Enable interoperability between CommonJS and ES modules | | allowSyntheticDefaultImports | true | Allow default imports from modules with no default export | | isolatedModules | true | Ensure each file can be safely transpiled without other files | | resolveJsonModule | true | Allow importing JSON files as modules |

Language Features

| Option | Value | Description | | --------- | ------------ | --------------------------------------- | | target | es6 | Compile to ES6 (ES2015) | | lib | ["es2017"] | Include ES2017 library type definitions | | jsx | react-jsx | Use the new JSX transform (React 17+) | | allowJs | true | Allow JavaScript files to be included |

Type Checking

| Option | Value | Description | | ---------------------------------- | ------- | ---------------------------------------------------------------------- | | strict | true | Enable all strict type checking options | | alwaysStrict | true | Parse in strict mode and emit "use strict" | | noImplicitAny | true | Raise error on expressions and declarations with an implied any type | | strictBindCallApply | true | Enable stricter checking of bind, call, and apply methods | | strictFunctionTypes | false | Disable stricter checking of function types (allows bivariance) | | noUnusedLocals | true | Report errors on unused local variables | | noUnusedParameters | true | Report errors on unused parameters | | noFallthroughCasesInSwitch | true | Report errors for fallthrough cases in switch statements | | forceConsistentCasingInFileNames | true | Disallow inconsistently-cased references to the same file |

Emit Options

| Option | Value | Description | | -------------- | ------ | ------------------------------------------------------------ | | sourceMap | true | Generate corresponding .map files for debugging | | skipLibCheck | true | Skip type checking of declaration files (faster compilation) |

Excluded Files

The following directories are excluded by default:

• **/lib/* - Compiled output
• **/node_modules/* - Dependencies
• **/dist/* - Distribution files

Common Use Cases

Library Package

For a library that needs to emit declaration files:

{
  "extends": "@ilo-org/typescript-config",
  "compilerOptions": {
    "outDir": "lib",
    "declaration": true,
    "declarationDir": "lib/types"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "lib", "**/*.test.ts"]
}

React Application

For a React application with DOM types:

{
  "extends": "@ilo-org/typescript-config",
  "compilerOptions": {
    "jsx": "react-jsx",
    "lib": ["dom", "dom.iterable", "es2017"],
    "types": ["node"]
  },
  "include": ["./src", "./tests"],
  "exclude": ["node_modules", "dist"]
}

Build Configuration

For a separate build configuration (e.g., tsconfig.build.json):

{
  "extends": "@ilo-org/typescript-config",
  "compilerOptions": {
    "outDir": "lib",
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["**/lib/*", "**/node_modules/*", "**/*.test.ts"]
}

Then reference it in your main tsconfig.json:

{
  "extends": "./tsconfig.build.json",
  "compilerOptions": {
    "noEmit": true
  },
  "include": ["src/**/*", "tests/**/*"]
}

Monorepo Root

For a monorepo root configuration:

{
  "extends": "./config/typescript-config/tsconfig.json",
  "compilerOptions": {
    "baseUrl": ".",
    "noEmit": true
  },
  "include": ["**/src/*"],
  "exclude": ["**/lib/*", "**/node_modules/*", "**/dist/*"]
}

Integration with ESLint

This TypeScript configuration is designed to work seamlessly with @ilo-org/eslint-config, which uses TypeScript ESLint for type-aware linting. The ESLint config automatically resolves your tsconfig.json for type checking.

Why These Settings?

• Strict mode enabled - Catches more potential bugs at compile time
• ES2017 library - Provides modern JavaScript APIs while maintaining compatibility
• ES6 target - Good balance between modern features and browser support
• React JSX transform - Uses the modern JSX transform (no need to import React)
• Isolated modules - Ensures files can be safely transpiled independently (important for build tools)
• Source maps - Enables better debugging experience
• Skip lib check - Faster compilation by skipping type checking of declaration files

📝 License

Licensed under the Apache 2.0 License.