stack/packages/mosaic/framework/skills/tsdown/references/option-shims.md

Shims

Add compatibility between ESM and CommonJS module systems.

Overview

Shims provide small pieces of code that bridge the gap between CommonJS (CJS) and ECMAScript Modules (ESM), enabling cross-module-system compatibility.

What Shims Provide

ESM Output (when enabled)

With shims: true, adds CommonJS variables to ESM:

• __dirname - Current directory path
• __filename - Current file path

ESM Output (automatic)

Always added when using require in ESM on Node.js:

• require function via createRequire(import.meta.url)

CJS Output (automatic)

Always added to CommonJS output:

• import.meta.url
• import.meta.dirname
• import.meta.filename

Usage

CLI

tsdown --shims

Config File

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm'],
  shims: true,
});

Generated Code

ESM with Shims

Source:

console.log(__dirname);
console.log(__filename);

Output (shims: true):

import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

console.log(__dirname);
console.log(__filename);

ESM with require

Source:

const mod = require('some-module');

Output (automatic on Node.js):

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);

const mod = require('some-module');

CJS with import.meta

Source:

console.log(import.meta.url);
console.log(import.meta.dirname);

Output (automatic):

const import_meta = {
  url: require('url').pathToFileURL(__filename).toString(),
  dirname: __dirname,
  filename: __filename,
};

console.log(import_meta.url);
console.log(import_meta.dirname);

Common Patterns

Node.js CLI Tool

export default defineConfig({
  entry: ['src/cli.ts'],
  format: ['esm'],
  platform: 'node',
  shims: true, // Add __dirname, __filename
});

Dual Format Library

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  platform: 'node',
  shims: true, // ESM gets __dirname/__filename
  // CJS gets import.meta.* (automatic)
});

Server-Side Code

export default defineConfig({
  entry: ['src/server.ts'],
  format: ['esm'],
  platform: 'node',
  shims: true,
  external: [/.*/], // External all deps
});

File System Operations

// Source code
import { readFileSync } from 'fs';
import { join } from 'path';

// Read file relative to current module
const content = readFileSync(join(__dirname, 'data.json'), 'utf-8');

// tsdown config
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm'],
  shims: true, // Enables __dirname
});

When to Use Shims

Use shims: true when:

• ✅ Building Node.js tools/CLIs
• ✅ Code uses __dirname or __filename
• ✅ Need file system operations relative to module
• ✅ Migrating from CommonJS to ESM
• ✅ Need cross-format compatibility

Don't need shims when:

• ❌ Browser-only code
• ❌ No file system operations
• ❌ Using only import.meta.url
• ❌ Pure ESM without CJS variables

Performance Impact

Runtime Overhead

Shims add minimal runtime overhead:

// Added to output when shims enabled
import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Tree Shaking

If __dirname or __filename are not used, they're automatically removed during bundling (no overhead).

Platform Considerations

Node.js Platform

export default defineConfig({
  platform: 'node',
  format: ['esm'],
  shims: true, // Recommended for Node.js
});

• require shim added automatically
• __dirname and __filename available with shims: true

Browser Platform

export default defineConfig({
  platform: 'browser',
  format: ['esm'],
  shims: false, // Not needed for browser
});

• Shims not needed (no Node.js variables)
• Will cause warnings if Node.js APIs used

Neutral Platform

export default defineConfig({
  platform: 'neutral',
  format: ['esm'],
  shims: false, // Avoid platform-specific code
});

• Avoid shims for maximum portability

CLI Examples

# Enable shims
tsdown --shims

# ESM with shims for Node.js
tsdown --format esm --platform node --shims

# Dual format with shims
tsdown --format esm --format cjs --shims

Troubleshooting

__dirname is not defined

Enable shims:

export default defineConfig({
  shims: true,
});

require is not defined in ESM

Automatic on Node.js platform. If not working:

export default defineConfig({
  platform: 'node', // Ensure Node.js platform
});

Import.meta not working in CJS

Automatic - no configuration needed. If still failing, check output format:

export default defineConfig({
  format: ['cjs'], // Shims added automatically
});

Tips

1. Enable for Node.js tools - Use shims: true for CLIs and servers
2. Skip for browsers - Not needed for browser code
3. No overhead if unused - Automatically tree-shaken
4. Automatic require shim - No config needed for require in ESM
5. CJS shims automatic - import.meta.* always available in CJS

Related Options

• Platform - Runtime environment
• Output Format - Module formats
• Target - Syntax transformations