This TypeScript compiler error occurs when you try to use the 'outFile' option with module systems other than 'amd' or 'system'. The 'outFile' option bundles all output into a single file, which only works with AMD or SystemJS module formats. To fix this, either change your module setting to 'amd' or 'system', or use a bundler like webpack or Rollup for other module formats.
The "An 'outFile' cannot be specified without 'amd' or 'system' module kind" error (TS6059) occurs when you configure TypeScript's compiler to output all code into a single file using the `outFile` option, but you're using a module system that doesn't support this bundling approach. TypeScript's `outFile` option is designed to concatenate all compiled JavaScript into one file, which is useful for certain deployment scenarios. However, this only works with two specific module systems: 1. **AMD (Asynchronous Module Definition)**: Used by RequireJS and other AMD loaders 2. **SystemJS**: A universal module loader that can handle multiple module formats Other module systems like CommonJS, ES modules (ES2015+), UMD, or None don't support this type of file concatenation because they have different dependency resolution mechanisms or are designed for different runtime environments. The error appears when your tsconfig.json has: - `"outFile": "./dist/bundle.js"` (or similar path) - `"module": "commonjs"`, `"module": "es2015"`, `"module": "esnext"`, or `"module": "none"` But not `"module": "amd"` or `"module": "system"`.
First, examine your tsconfig.json to see the current module and outFile configuration:
// Example problematic configuration
{
"compilerOptions": {
"outFile": "./dist/bundle.js",
"module": "commonjs", // ← This causes the error!
"target": "es2015",
"strict": true
}
}Or check from command line:
# Show current TypeScript configuration
npx tsc --showConfig
# Or check specific files
cat tsconfig.json | grep -E "(outFile|module)"Identify which module system you're using and confirm the outFile is set.
If you need single-file output and can use AMD or SystemJS, update your tsconfig.json:
{
"compilerOptions": {
"outFile": "./dist/bundle.js",
"module": "amd", // ← Changed from commonjs to amd
"target": "es2015",
"strict": true
}
}Or for SystemJS:
{
"compilerOptions": {
"outFile": "./dist/bundle.js",
"module": "system", // ← Changed to system
"target": "es2015",
"strict": true
}
}When to use this option:
- You're building for AMD environments (RequireJS, Dojo)
- You're using SystemJS as your module loader
- You need a single file for legacy browser environments
- Your deployment target specifically requires bundled output
For modern projects using CommonJS or ES modules, remove outFile and use a proper bundler:
{
"compilerOptions": {
// Remove outFile entirely
"module": "es2020",
"target": "es2015",
"strict": true,
"outDir": "./dist" // Use outDir instead for multiple files
}
}Then add a bundler configuration:
Webpack example (webpack.config.js):
module.exports = {
entry: './src/index.ts',
output: {
filename: 'bundle.js',
path: path.resolve(__dirname, 'dist')
},
module: {
rules: [
{
test: /.ts$/,
use: 'ts-loader',
exclude: /node_modules/
}
]
},
resolve: {
extensions: ['.ts', '.js']
}
};Rollup example (rollup.config.js):
import typescript from '@rollup/plugin-typescript';
export default {
input: 'src/index.ts',
output: {
file: 'dist/bundle.js',
format: 'cjs' // or 'es', 'umd', etc.
},
plugins: [typescript()]
};When to use this option:
- Modern web applications
- Node.js projects
- Libraries distributed via npm
- Projects using ES modules
If you don't need a single bundled file, simply switch to outDir for multi-file output:
{
"compilerOptions": {
// Replace outFile with outDir
"outDir": "./dist",
"module": "commonjs", // Now works with any module system
"target": "es2015",
"strict": true
}
}This creates a directory structure mirroring your source:
dist/
├── index.js
├── utils/
│ └── helpers.js
└── components/
└── button.jsCompile and verify:
# Clear previous build
rm -rf dist
# Compile with new configuration
npx tsc
# Check output structure
ls -la dist/When to use this option:
- Node.js applications
- Projects where file organization matters
- When you want to preserve source structure
- Debugging is easier with separate files
After making changes, test that TypeScript compiles successfully:
# Run TypeScript compiler
npx tsc
# If using npm scripts
npm run build
# For watch mode during development
npx tsc --watchCheck the output:
# For single file (AMD/SystemJS)
ls -la dist/bundle.js
# For multi-file output
ls -la dist/Test that the compiled code works:
# For Node.js (CommonJS)
node dist/index.js
# For browser (if using AMD)
# Load dist/bundle.js with RequireJS or SystemJSIf you still get errors, check for other tsconfig.json issues:
# Validate tsconfig.json
npx tsc --noEmit
# Show all compiler options being used
npx tsc --showConfig | jq .compilerOptionsUpdate your package.json scripts and any documentation:
{
"scripts": {
// Before (if using outFile with wrong module)
"build": "tsc",
// After Option 1 (AMD/SystemJS with outFile)
"build": "tsc",
"dev": "tsc --watch",
// After Option 2 (with bundler)
"build": "webpack --mode production",
"dev": "webpack --mode development --watch",
// After Option 3 (outDir with any module)
"build": "tsc",
"clean": "rm -rf dist",
"dev": "tsc --watch"
}
}Update README.md or other documentation:
Example README update:
"## Building the Project
### Before
The build would fail with TS6059 error when using 'outFile' with incompatible module systems.
### After
The build now successfully creates either:
- dist/bundle.js (when using AMD or SystemJS module system)
- dist/ directory with separate files (when using CommonJS or ES modules)
### Development
Run 'npm run dev' for watch mode with automatic recompilation."
If you're working in a team, communicate the changes:
# Commit the changes
git add tsconfig.json package.json webpack.config.js
git commit -m "fix: resolve TS6059 by updating module configuration"
# Update teammates
echo "Fixed TypeScript build: changed module system to support outFile or switched to bundler"### Understanding Module Systems in TypeScript
TypeScript supports several module systems, each with different characteristics:
| Module | Use Case | Supports outFile? | Notes |
|--------|----------|-------------------|-------|
| AMD | Browser, RequireJS | ✅ Yes | Asynchronous loading, good for web |
| System | SystemJS, universal | ✅ Yes | Can load multiple module formats |
| CommonJS | Node.js, webpack | ❌ No | Synchronous, Node.js default |
| ES2015+ | Modern browsers, bundlers | ❌ No | Native ES modules, standard |
| UMD | Universal (browser + Node) | ❌ No | Wraps code for multiple environments |
| None | No modules, global scope | ❌ No | All code in global namespace |
### Historical Context
The outFile option dates back to TypeScript's early days when AMD was the primary module system for browser development. Before bundlers like webpack became popular, developers used outFile with AMD to create single-file bundles for browser deployment.
As the ecosystem evolved, CommonJS (for Node.js) and ES modules (standard) became dominant, but they don't support the same concatenation approach because:
- CommonJS uses require() calls that need to resolve at runtime
- ES modules use static imports that browsers resolve independently
- Both assume separate files for each module
### Bundler Alternatives
Modern alternatives to outFile:
1. Webpack: Most popular, supports code splitting, tree shaking, hot reload
2. Rollup: Excellent for libraries, smaller bundles, ES module focused
3. esbuild: Extremely fast, good for development
4. Vite: Modern build tool, uses esbuild for development
5. Parcel: Zero-configuration, good for simple projects
### Migration Strategies
From AMD/SystemJS with outFile to modern bundler:
1. Remove outFile from tsconfig.json
2. Set "module": "esnext" (for tree shaking)
3. Add webpack/rollup configuration
4. Update imports to use ES module syntax
5. Test that bundling works correctly
Performance Considerations:
- outFile with AMD: Fast compilation, but runtime requires AMD loader
- Bundlers: Slower build, but optimized output, code splitting, better caching
- For large projects, bundlers provide better long-term maintainability
### Debugging Module Resolution
If you're having issues after changing module systems:
# Show module resolution trace
npx tsc --traceResolution
# Check what module system is actually being used
npx tsc --showConfig | grep module
# Test compilation with specific module
npx tsc --module amd --outFile dist/bundle.js### TypeScript Version Compatibility
- TypeScript 1.0-2.0: outFile was more commonly used with AMD
- TypeScript 3.0+: Better ES module support, bundler integration
- TypeScript 4.0+: Improved module resolution for Node.js and bundlers
Check your TypeScript version:
npx tsc --versionIf using an older version (< 3.0), consider upgrading for better module system support.
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript