@foundrykit/typescript-config

TypeScript configuration for the FoundryKit ecosystem. Provides consistent TypeScript settings and compiler options across all FoundryKit packages and applications.

Features

• Consistent configuration - Standardized TypeScript settings across projects
• Multiple presets - Configurations for different project types
• Strict typing - Comprehensive type checking and safety
• Modern features - Latest TypeScript features and optimizations
• Extensible - Easy to extend and customize for specific needs

Installation

pnpm add -D @foundrykit/typescript-config

Available Configurations

Base Configuration

The base configuration includes common TypeScript settings:

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/base.json"
}

Next.js Configuration

Configuration optimized for Next.js applications:

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/nextjs.json"
}

React Library Configuration

Configuration for React component libraries:

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/react-library.json"
}

Usage

Basic Setup

1. Install the package:

pnpm add -D @foundrykit/typescript-config

2. Create TypeScript configuration:

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

3. Add scripts to package.json:

{
  "scripts": {
    "type-check": "tsc --noEmit",
    "build": "tsc",
    "dev": "tsc --watch"
  }
}

Next.js Project

For Next.js applications:

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/nextjs.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

React Library

For React component libraries:

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/react-library.json",
  "compilerOptions": {
    "outDir": "./dist",
    "declaration": true,
    "declarationMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx"]
}

Custom Configuration

Extend the base configuration with custom settings:

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/base.json",
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  },
  "include": ["src/**/*", "types/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

Configuration Details

Base Configuration

The base configuration includes:

• Modern JavaScript features - ES2022 target and module resolution
• Strict type checking - Comprehensive type safety
• Path mapping - Module resolution configuration
• Declaration files - Type declaration generation

Next.js Configuration

Extends base configuration with:

• Next.js specific settings - Optimized for Next.js applications
• JSX support - React JSX compilation
• Path aliases - Next.js path mapping
• Incremental compilation - Faster builds

React Library Configuration

Extends base configuration with:

• Library settings - Optimized for component libraries
• Declaration generation - Type declaration files
• External dependencies - Proper dependency handling
• Bundle optimization - Tree-shaking support

Compiler Options

Strict Type Checking

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

Module Resolution

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "moduleDetection": "force",
    "verbatimModuleSyntax": true
  }
}

Path Mapping

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/utils/*": ["./src/utils/*"]
    }
  }
}

Customization

Override Options

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/base.json",
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true
  }
}

Environment-Specific Configurations

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/base.json",
  "compilerOptions": {
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
  "references": [{ "path": "./tsconfig.test.json" }]
}

// tsconfig.test.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "types": ["jest", "node"]
  },
  "include": ["src/**/*", "tests/**/*"],
  "exclude": ["node_modules", "dist"]
}

Project References

For monorepos with multiple packages:

// tsconfig.json
{
  "extends": "@foundrykit/typescript-config/base.json",
  "files": [],
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" },
    { "path": "./apps/web" }
  ]
}

Integration

Build Tools

tsup

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
  external: ['react', 'react-dom'],
});

Vite

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': '/src',
    },
  },
});

Webpack

// webpack.config.js
const path = require('path');

module.exports = {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'],
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
};

IDE Configuration

VS Code

// .vscode/settings.json
{
  "typescript.preferences.includePackageJsonAutoImports": "on",
  "typescript.suggest.autoImports": true,
  "typescript.updateImportsOnFileMove.enabled": "always"
}

WebStorm

// .idea/codeStyles/Project.xml
<component name="ProjectCodeStyleConfiguration">
  <code_scheme name="Project" version="173">
    <TypeScriptCodeStyleSettings version="0">
      <option name="USE_SEMICOLON_AFTER_STATEMENT" value="true" />
      <option name="USE_DOUBLE_QUOTES" value="false" />
    </TypeScriptCodeStyleSettings>
  </code_scheme>
</component>

Troubleshooting

Common Issues

Module resolution errors:

# Check module resolution
npx tsc --traceResolution

Path mapping issues:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Declaration file generation:

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist"
  }
}

Performance Optimization

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./node_modules/.cache/.tsbuildinfo",
    "skipLibCheck": true
  }
}

Best Practices

Configuration Organization

// ✅ Good - Clear, organized configuration
{
  "extends": "@foundrykit/typescript-config/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

Strict Type Checking

// ✅ Good - Comprehensive type safety
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "noImplicitReturns": true
  }
}

Module Resolution

// ✅ Good - Modern module resolution
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true
  }
}

Contributing

When contributing to the TypeScript configuration:

1. Follow TypeScript best practices
2. Test configurations thoroughly
3. Document option changes
4. Maintain backward compatibility
5. Update this README

License

MIT