@gtalumni-la/typescript

Shared TypeScript configuration for Georgia Tech Alumni Association projects. This package provides a standardized TypeScript setup that ensures consistency across all packages in the design system monorepo.

📦 Installation

npm install --save-dev @gtalumni-la/typescript
# or
yarn add --dev @gtalumni-la/typescript
# or
pnpm add --save-dev @gtalumni-la/typescript

🚀 Usage

Basic Setup

Create a tsconfig.json in your project root:

{
  "extends": "@gtalumni-la/typescript/base",
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

For React Projects

If your project uses React, extend the React-specific configuration:

{
  "extends": "@gtalumni-la/typescript/react",
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "build"]
}

For Library Projects

For packages that will be published as libraries:

{
  "extends": "@gtalumni-la/typescript/library",
  "include": ["src/**/*"],
  "exclude": [
    "node_modules",
    "dist",
    "__test__",
    "**/*.test.ts",
    "**/*.test.tsx"
  ]
}

📚 Available Configurations

Base Configuration (base.json)

The foundation configuration that other configs extend from:

• Target: ES2020 for modern browser support
• Module: ESNext for optimal bundling
• Strict Mode: Enabled for maximum type safety
• Source Maps: Enabled for debugging
• Declaration Files: Generated for library consumption

Key settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["DOM", "DOM.Iterable", "ES2020"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "declaration": true,
    "sourceMap": true,
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

React Configuration (react.json)

Extends base configuration with React-specific settings:

• JSX: React JSX transform
• React Types: Included DOM types
• Import Helpers: Optimized for React builds

Additional settings:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "lib": ["DOM", "DOM.Iterable", "ES2020"],
    "types": ["react", "react-dom"]
  }
}

Library Configuration (library.json)

Extends base configuration optimized for publishable packages:

• Declaration Maps: For better IDE support
• Composite: Enables project references
• Output Directory: Standardized dist folder

Additional settings:

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

🎯 Features

Strict Type Checking

All configurations enable strict mode and additional strict checks:

• strict: true - Enables all strict type checking options
• noUncheckedIndexedAccess: true - Prevents accessing array/object properties without checking
• exactOptionalPropertyTypes: true - Distinguishes between undefined and missing properties

Modern JavaScript Support

• ES2020 target for modern browser features
• ESNext modules for optimal tree-shaking
• Latest DOM types for web APIs

Development Experience

• Source maps for debugging
• Declaration files for IntelliSense
• Consistent casing enforcement
• Skip lib check for faster builds

Monorepo Optimization

• Project references support
• Incremental compilation
• Composite projects for better build performance

🔧 Customization

Extending Configurations

You can extend our configurations and add your own customizations:

{
  "extends": "@gtalumni-la/typescript/base",
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"],
      "@components/*": ["components/*"]
    }
  },
  "include": ["src/**/*", "types/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.*"]
}

Path Mapping

For projects that need path aliases:

{
  "extends": "@gtalumni-la/typescript/base",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@gtalumni-la/tokens": ["../tokens/src"],
      "@gtalumni-la/react": ["../react/src"]
    }
  }
}

Multiple Configurations

For projects that need different configs for different environments:

// tsconfig.json (development)
{
  "extends": "@gtalumni-la/typescript/base",
  "include": ["src/**/*", "**/*.test.*"]
}

// tsconfig.build.json (production builds)
{
  "extends": "./tsconfig.json",
  "exclude": ["**/*.test.*", "**/*.spec.*", "__test__"]
}

🛠️ Integration

With Build Tools

Vite

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

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.ts',
      formats: ['es', 'cjs'],
    },
  },
});

Rollup

// rollup.config.js
import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/index.ts',
  plugins: [
    typescript({
      tsconfig: './tsconfig.json',
    }),
  ],
};

With Testing

Vitest

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

export default defineConfig({
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/__test__/setup.ts'],
  },
});

With Linting

Works seamlessly with @gtalumni-la/eslint:

// .eslintrc.json
{
  "extends": ["@gtalumni-la/eslint/typescript"],
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}

📁 Package Structure

src/
├── base.json          # Base TypeScript configuration
├── react.json         # React-specific configuration
└── library.json       # Library-specific configuration

package.json           # Package metadata and exports
README.md             # This documentation

🎯 Best Practices

Project Setup

1. Choose the Right Config: Use base for general projects, react for React apps, library for packages
2. Include/Exclude Properly: Be specific about what files to compile
3. Use Project References: For monorepo projects, set up project references

Type Safety

1. Enable Strict Mode: Always use our strict configurations
2. Avoid any: Use proper types or unknown when needed
3. Use Type Guards: For runtime type checking

Performance

1. Use skipLibCheck: Skip type checking of declaration files (already enabled)
2. Incremental Compilation: Use composite projects for large codebases
3. Project References: Set up proper dependencies between packages

🔄 Migration Guide

From Other Configs

If migrating from other TypeScript configurations:

1. Install this package: pnpm add -D @gtalumni-la/typescript
2. Update your tsconfig.json to extend our config
3. Remove redundant options that are already in our base config
4. Test your build to ensure everything works

Common Issues

Module Resolution: If you have import issues, make sure moduleResolution is set to "bundler" (already in our config).

React JSX: For React projects, use our react config which includes proper JSX settings.

Strict Checks: Our configs are strict by default. You may need to fix type errors when migrating.

🤝 Contributing

See the main CONTRIBUTING.md for development guidelines.

Adding New Configurations

1. Create a new JSON file in the root directory
2. Extend from base.json when possible
3. Document the new configuration in this README
4. Update the package.json exports if needed

Updating Configurations

1. Consider backward compatibility
2. Test changes across all packages in the monorepo
3. Update documentation for any breaking changes
4. Use semantic versioning for releases

📄 License

MIT © Georgia Tech Alumni Association

🔗 Related Packages

• @gtalumni-la/eslint - ESLint configuration that works with these TypeScript configs
• @gtalumni-la/tokens - Type-safe design tokens
• @gtalumni-la/react - React components with full TypeScript support