Rewrite Imports Utility

3.0.0 · active · verified Sun Apr 19

rewrite-imports is a lightweight (349B) utility designed to transform ECMAScript `import` statements into CommonJS `require()` calls using regular expressions. As of its current stable version, 3.0.0, it provides a performant way to transpile modules at the string level, without relying on an Abstract Syntax Tree (AST) parser. This makes it extremely fast and suitable for build-time processing in environments where a full AST transformation is overkill or undesired. The package typically sees minor updates and patches, with major versions introducing breaking changes like the shift to named exports in v3.0.0. Its primary differentiator is its simplicity and reliance on RegExp, offering a niche solution for projects that need a quick, no-frills import rewriting mechanism, particularly for older Node.js environments (>=6) or browser environments with a `require` shim. Unlike full module bundlers or transpilers, it solely performs string replacement and does not provide a runtime or evaluate the transformed code.

Common errors

```
TypeError: rewrite-imports is not a function
```
cause Attempting to use `rewrite-imports` v3.0.0+ as a default export, typically `const rewrite = require('rewrite-imports')` or `import rewrite from 'rewrite-imports'`.

fix Update your import statement to `import { rewrite } from 'rewrite-imports'` for ESM or `const { rewrite } = require('rewrite-imports')` for CommonJS.
```
Transformed code contains syntax errors or unexpected runtime behavior related to module loading.
```
cause `rewrite-imports` uses regular expressions and may incorrectly transform strings that resemble import statements but are not actual module imports (e.g., in comments, multiline strings, or variable names).

fix Review the original code for potential false positives where `import` keywords are used outside of actual module declarations. If this issue persists, consider using an AST-based transpiler for more robust code analysis.

Warnings

breaking The primary `rewrite` function was migrated from a default export to a named export. This requires updating all import/require statements.
Fix: Change `import rewrite from 'rewrite-imports'` to `import { rewrite } from 'rewrite-imports'` or `const rewrite = require('rewrite-imports')` to `const { rewrite } = require('rewrite-imports')`.
breaking The utility no longer forces semicolon termination after rewritten `require()` statements. The output will now respect the original import statement's termination or lack thereof.
Fix: No direct fix needed unless your build process relied on the forced semicolon. Review your linting rules if this causes issues.
breaking The `interop` function, which handled `default` exports from ESM/CommonJS modules, was removed in favor of a custom `require` function parameter. Users relying on `interop` will need to adjust their code.
Fix: If you relied on `interop`, you may need to manually manage default exports or adjust your custom `require` function (via the `fn` parameter) to handle interop behavior.
gotcha This module uses regular expressions for transformation, which can lead to 'false positives' if `import` keywords appear in comments, strings, or other non-module contexts. It is not an AST parser.
Fix: For highly complex codebases or strict accuracy, consider using an AST-based transpiler instead. For simpler cases, ensure `import` statements are clean and unambiguous.
gotcha The output requires a JavaScript runtime that supports CommonJS `require` calls and object destructuring assignments. This means Node.js versions `>=6.x` or browsers with a `require` shim and ES6 destructuring support.
Fix: Ensure your target runtime environment meets the Node.js `>=6.x` requirement or provides necessary polyfills/shims for browser compatibility.
gotcha The utility only performs string transformation and does not provide a module runtime or evaluate the output. It is purely a build-time string manipulation tool.
Fix: Do not expect `rewrite-imports` to handle module loading or execution at runtime; it's designed for static code transformation.

Install

npm install rewrite-imports npm
yarn add rewrite-imports yarn
pnpm add rewrite-imports pnpm

Imports

rewrite
wrong:
```
import rewrite from 'rewrite-imports'
```
correct:
```
import { rewrite } from 'rewrite-imports'
```
Since v3.0.0, `rewrite` is a named export. Default import will result in a TypeError.
rewrite
wrong:
```
const rewrite = require('rewrite-imports')
```
correct:
```
const { rewrite } = require('rewrite-imports')
```
Since v3.0.0, `rewrite` is a named export. Direct CommonJS require without destructuring will result in a TypeError.
rewrite
```
rewrite(codeString)
```
The primary API is a single function `rewrite`.

Quickstart

Demonstrates how to use the `rewrite` function to convert various ES import syntaxes into CommonJS require() statements.

import { rewrite } from 'rewrite-imports';

// Example 1: Default import
console.log(rewrite(`import foo from '../bar'`));
// Expected output: const foo = require('../bar');

// Example 2: Named import
console.log(rewrite(`import { foo } from 'bar'`));
// Expected output: const { foo } = require('bar');

// Example 3: Namespace import
console.log(rewrite(`import * as path from 'path';`));
// Expected output: const path = require('path');

// Example 4: Renamed named imports
console.log(rewrite(`import { foo as bar, baz as bat, lol } from 'quz';`));
// Expected output: const { foo:bar, baz:bat, lol } = require('quz');

// Example 5: Mixed default and named imports
console.log(rewrite(`import foobar, { foo as FOO, bar } from 'foobar';`));
// Expected output:
// const foobar = require('foobar');
// const { foo:FOO, bar } = foobar;

view raw JSON →