TSConfig for Templ Project
npm install @templ-project/tsconfigA 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
- 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
``bash`
npm install --save-dev @templ-project/tsconfig
This package includes TypeScript as a dependency, so you don't need to install it separately.
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
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
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
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
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
Choose the appropriate configuration for your project and extend it:
`json`
{
"extends": "@templ-project/tsconfig/browser.json",
"compilerOptions": {
"outDir": "./build"
},
"include": ["src/*/"]
}
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"
]
}
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"]
}
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 |
| 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 |
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
};
`bashRegenerate all configuration files
npm run build
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)
}
``This package is part of the Templ Project ecosystem. See the main repository for contribution guidelines.
See CHANGELOG.md for version history and changes.
MIT Ā© Dragos Cirjan