@templ-project/tsconfig

A comprehensive collection of TypeScript configurations designed for different runtime environments and build targets. This package provides portable, opinionated TSConfig presets that can be used as-is or extended for custom project needs.

- @templ-project/tsconfig
- Features
- Installation
- Available Configurations
- base.json - Foundation Configuration
- browser.json - Browser/Frontend Projects
- cjs.json - CommonJS/Node.js Projects
- esm.json - ES Modules Projects
- vitest.json - Testing with Vitest
- Usage
- Basic Usage
- Extending Configurations
- Custom Project Structure
- Configuration Details
- Base Configuration Features
- Environment-Specific Settings
- Build System Integration
- Dynamic Configuration Generation
- Automated Building
- Testing
- Compilation Testing
- Output Validation
- Common Use Cases
- Node.js CLI Application
- Browser Library
- Dual Package (ESM + CJS)
- Testing Setup
- Monorepo Configuration
- Configuration Reference
- Compiler Options
- Path Mapping
- Best Practices
- Project Structure
- Environment Selection
- Build Optimization
- Troubleshooting
- Common Issues
- Module Resolution Problems
- Contributing
- Changelog
- License

Features

- Multiple environments: Browser, Node.js (CJS/ESM), and testing configurations
- Modern TypeScript: Based on @tsconfig/node22 with latest TypeScript features
- Opinionated defaults: Production-ready settings with strict type checking
- Flexible structure: Configurable source and output directories
- Testing integration: Vitest-specific configuration with global types
- Build automation: Dynamic configuration generation via build script
- Comprehensive validation: Automated testing for all configuration variants

Installation

``bash
npm install --save-dev @templ-project/tsconfig
`

This package includes TypeScript as a dependency, so you don't need to install it separately.

Available Configurations

$3

The foundation configuration that all other configs extend from.

Features:
- Extends @tsconfig/node22 for modern Node.js compatibility
- Strict type checking with unused variable detection
- Source maps enabled for debugging
- Configurable source and output directories
- Comment removal for production builds

Best for: Starting point for any TypeScript project

$3

Optimized for browser environments and frontend applications.

Key Settings:
- Target: ES2020 for modern browser support
- Module: ES2020 for native browser modules
- Module Resolution: Bundler-optimized for webpack/vite/rollup

Best for: React, Vue, Angular apps, browser libraries

$3

Configured for traditional Node.js projects using CommonJS modules.

Key Settings:
- Module: Node16 for CommonJS output
- Module Resolution: Node16 for Node.js module resolution

Best for: Node.js servers, CLI tools, legacy Node.js projects

$3

Configured for modern Node.js projects using ES modules.

Key Settings:
- Module: ESNext for cutting-edge module features
- Module Resolution: Node for Node.js compatibility

Best for: Modern Node.js applications, libraries, ESM-first projects

$3

Specialized configuration for testing with Vitest framework.

Key Settings:
- Extends CJS configuration for Node.js test environment
- Includes Vitest global types (vitest/globals)
- Node.js types for test utilities

Best for: Unit tests, integration tests, test suites

Usage

$3

Choose the appropriate configuration for your project and extend it:

`json
{
"extends": "@templ-project/tsconfig/browser.json",
"compilerOptions": {
"outDir": "./build"
},
"include": ["src/*/"]
}
`

$3

You can extend any configuration with project-specific settings:

`json
{
"extends": "@templ-project/tsconfig/base.json",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/": ["src/"],
"@components/": ["src/components/"]
},
"lib": ["DOM", "ES2020"]
},
"include": [
"src/*/",
"types/*/"
],
"exclude": [
"*/.test.ts",
"*/.spec.ts"
]
}
`

$3

The configurations use template variables that you can customize:

`json
{
"extends": "@templ-project/tsconfig/esm.json",
"compilerOptions": {
"rootDir": "./source",
"outDir": "./output",
"declaration": true,
"declarationMap": true
},
"include": ["source/*/.ts"]
}
`

Configuration Details

$3

All configurations inherit these foundational settings:

| Setting | Value | Purpose |
|---------|-------|---------|
| target | From @tsconfig/node22 | Modern JavaScript output |
| sourceMap | true | Enable debugging support |
| removeComments | true | Smaller output files |
| forceConsistentCasingInFileNames | true | Cross-platform compatibility |
| noUnusedLocals | true | Catch unused variables |
| noUnusedParameters | true | Catch unused parameters |
| verbatimModuleSyntax | false | Allow mixed import/export styles |

$3

| Configuration | Module System | Target Environment | Module Resolution |
|---------------|---------------|-------------------|-------------------|
| browser.json | ES2020 | Modern browsers | bundler |
| cjs.json | Node16 | Node.js CommonJS | Node16 |
| esm.json | ESNext | Node.js ES Modules | Node |
| vitest.json | Node16 | Testing (Node.js) | Node16 |

Build System Integration

$3

The package includes a build system that generates configurations programmatically:

`javascript
// build.js
const nodeVersion = 'node22';

const tsconfig = {
base: {
extends: @tsconfig/${nodeVersion}/tsconfig.json,
// ... configuration options
},
// ... other configurations
};
`

$3

`bash


Regenerate all configuration files

npm run build

Run tests with fresh configurations

npm run pretest
npm test
`

Testing

$3

The package includes comprehensive tests that validate:

- ✅ Compilation success: All configurations compile without errors
- ✅ Output format: Correct module format (CJS/ESM) is generated
- ✅ Type checking: Strict type validation works correctly
- 🔧 Environment compatibility: Configurations work in target environments

$3

`typescript
// Example test validation
expect(output).toContain('export const hello'); // ESM output
expect(output).toContain('exports.hello = hello'); // CJS output
`

Common Use Cases

$3

`json
{
"extends": "@templ-project/tsconfig/cjs.json",
"compilerOptions": {
"outDir": "./dist",
"declaration": false
},
"include": ["src/*/"],
"exclude": ["*/.test.ts"]
}
`

$3

`json
{
"extends": "@templ-project/tsconfig/browser.json",
"compilerOptions": {
"outDir": "./lib",
"declaration": true,
"declarationMap": true,
"lib": ["DOM", "ES2020"]
}
}
`

$3

Create separate configurations for each output:

`jsonc
// tsconfig.esm.json
{
"extends": "@templ-project/tsconfig/esm.json",
"compilerOptions": {
"outDir": "./dist/esm"
}
}
`

`jsonc
// tsconfig.cjs.json
{
"extends": "@templ-project/tsconfig/cjs.json",
"compilerOptions": {
"outDir": "./dist/cjs"
}
}
`

$3

`jsonc
// tsconfig.test.json
{
"extends": "@templ-project/tsconfig/vitest.json",
"compilerOptions": {
"noEmit": true
},
"include": [
"src/*/",
"test/*/",
"*/.test.ts",
"*/.spec.ts"
]
}
`

$3

`jsonc
// packages/shared/tsconfig.json
{
"extends": "@templ-project/tsconfig/base.json",
"compilerOptions": {
"composite": true,
"declaration": true,
"outDir": "./dist"
},
"include": ["src/*/"]
}
`

`jsonc
// packages/app/tsconfig.json
{
"extends": "@templ-project/tsconfig/esm.json",
"references": [
{ "path": "../shared" }
],
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@shared/": ["../shared/src/"]
}
}
}
`

Configuration Reference

$3

| Option | base.json | browser.json | cjs.json | esm.json | vitest.json |
|--------|-----------|--------------|----------|----------|-------------|
| module | From base | ES2020 | Node16 | ESNext | Node16 |
| moduleResolution | From base | bundler | Node16 | Node | Node16 |
| target | From @tsconfig/node22 | ES2020 | From base | From base | From base |
| types | ["node"] | From base | From base | From base | ["node", "vitest/globals"] |

$3

All configurations support TypeScript path mapping:

`json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/": ["src/"],
"@utils/": ["src/utils/"],
"@types/": ["types/"]
}
}
}
`

Best Practices

$3

Recommended directory structure for optimal configuration usage:

`
project/
├── src/ # Source TypeScript files
├── dist/ # Compiled output
├── test/ # Test files
├── types/ # Type definitions
└── tsconfig.json # Main TypeScript config
`

$3

Choose the right configuration for your target environment:

- Node.js applications: Use cjs.json for compatibility or esm.json for modern projects
- Browser libraries: Use browser.json with bundler integration
- Full-stack projects: Consider separate configs for client/server code
- Testing: Always use vitest.json for test files

$3

For production builds, consider these overrides:

`jsonc
{
"extends": "@templ-project/tsconfig/base.json",
"compilerOptions": {
"sourceMap": false, // Disable in production
"removeComments": true, // Already enabled
"declaration": true, // For libraries
"declarationMap": true // For better IDE support
}
}
`

Troubleshooting

$3

Configuration not found: Ensure the package is installed and the path is correct:
`bash
npm list @templ-project/tsconfig
`

Module resolution errors: Check that you're using the right configuration for your environment:
- Browser projects need moduleResolution: "bundler"
- Node.js projects need moduleResolution: "Node16"

Type errors in tests: Make sure you're extending vitest.json for test configurations.

$3

If you encounter module resolution issues:

1. Check your package.json: Ensure type field matches your chosen configuration
2. Verify imports: Use appropriate import syntax for your target environment
3. Update dependencies: Ensure TypeScript version compatibility

`jsonc
{
"type": "module", // For ESM projects
"type": "commonjs" // For CJS projects (default)
}
``

Contributing

This package is part of the Templ Project ecosystem. See the main repository for contribution guidelines.

Changelog

See CHANGELOG.md for version history and changes.

License

MIT © Dragos Cirjan