CJS to ESM

You are a JavaScript migration specialist. The user wants to convert CommonJS (CJS) modules to ES Modules (ESM) syntax and structure.

What to check first

• Run node --version to confirm Node.js 12.20+ (required for ESM support)
• Check package.json and add "type": "module" to enable ESM parsing, or use .mjs file extensions
• Scan your codebase with grep -r "require(" --include="*.js" to identify all CJS imports
• Verify if you're using conditional exports or dynamic requires that need special handling

Steps

1. Update package.json by adding "type": "module" at the root level, or rename files from .js to .mjs
2. Replace all const x = require('module') with import x from 'module' (named exports become import { x } from 'module')
3. Replace module.exports = {} with export default {} or use named exports with export const x = {}
4. Convert require.resolve() calls to import.meta.resolve() (Node.js 18.19+) or use a workaround with createRequire
5. Replace __dirname and __filename with equivalents using import.meta.url and the path module or fileURLToPath
6. Update dynamic requires like require(variable) to import(variable) which returns a Promise
7. Handle circular dependencies by reorganizing exports or using lazy imports with import() inside functions
8. Test with node --check file.js to validate syntax, then run your test suite to verify runtime behavior

Code

// Before: CommonJS
const path = require('path');
const { readFile } = require('fs/promises');
const myModule = require('./utils');

module.exports = {
  processFile: async (filePath) => {
    const content = await readFile(filePath, 'utf-8');
    return myModule.transform(content);
  }
};

// After: ES Modules
import path from 'path';
import { readFile } from 'fs/promises';
import { fileURLToPath } from 'url';
import * as myModule from './utils.js';

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

export const processFile = async (filePath) => {
  const content = await readFile(filePath, 'utf-8');
  return myModule.transform(content);
};

// Handling dynamic requires
export const loadPlugin = async (pluginName) => {
  const module = await import(`./plugins/${pluginName}.js`);
  return module.default;
};

// Mixed export (default + named)
export default {
  version: '1.0.0'
};

export const helper = () => 'helper function';

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change