babel-plugin-recast

0.2.0 verified Sat Apr 25 auth: no javascript

Babel plugin (v0.2.0, stable) that integrates recast's AST parsing and code generation to preserve original formatting during Babel transformations, ideal for codemods. Unlike standard Babel plugins that discard formatting, it uses undocumented parserOverride/generatorOverride hooks to maintain whitespace and style. Requires peer dependency recast 0.x. Light maintenance, release cadence is minimal.

Common errors

error Error: Plugin babel-plugin-recast not found ↓

cause Missing or incorrectly installed package.

fix

Run npm install --save-dev babel-plugin-recast

error Cannot find module 'recast' ↓

cause Missing peer dependency recast.

fix

Run npm install recast@0.x

error Multiple parser overrides found ↓

cause Another plugin also overrides parsing without chaining.

fix

Chain parserOverrides by passing the other plugin's override via options.

Warnings

gotcha Only one plugin can override parsing. Chaining with other parser overrides is possible but untested. ↓

fix If you have another parser override, pass it via options: { parserOverride: otherPlugin.parserOverride }.

gotcha Recast's source mapping replaces Babel's; may cause unexpected behavior in source maps. ↓

fix Test source maps after transformation if they are critical.

breaking Peer dependency recast must be 0.x; breaking changes may occur if recast major version updates. ↓

fix Pin recast to 0.x in your package.json.

gotcha Undocumented hooks parserOverride and generatorOverride may break in future Babel versions. ↓

fix Monitor Babel release notes for changes to these hooks.

Install

npm install babel-plugin-recast

yarn add babel-plugin-recast

pnpm add babel-plugin-recast

Imports

babel-plugin-recast

wrong

import plugin from 'babel-plugin-recast'; // Not a JS module

correct

module.exports = { plugins: ['babel-plugin-recast'] };

Used as a Babel plugin name string in config, not a direct import.

parserOverride

wrong

plugins: ['babel-plugin-recast', { parserOverride: ... }] // Options must be paired with plugin name in array

correct

plugins: [['babel-plugin-recast', { parserOverride: otherPlugin.parserOverride }]]

Options are passed as the second element of an array in Babel config.

generatorOverride

wrong

Setting generatorOverride in plugin options

correct

Not directly exposed; recast handles it internally.

generatorOverride is not configurable via this plugin.

Quickstart

Basic Babel config enabling babel-plugin-recast to preserve formatting.

// babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    plugins: ['babel-plugin-recast']
  };
};

// Run: npx babel input.js --out-file output.js --config-file babel.config.js