Magicast

Magicast lets tools edit JS/TS source files the way they’d edit a JSON object — mutate a property, push to an array, add an import — and write the result back with the original formatting (quotes, indentation, style) preserved. It’s built on recast for formatting-preserving AST printing and Babel for parsing, and exposes helpers for the common config-file editing patterns codemods and CLI generators actually need: modifying exports, imports, and function-call arguments like defineConfig().

What You Get

• loadFile/writeFile helpers to read a JS/TS file, mutate it, and write it back with formatting intact
• parseModule/generateCode for lower-level AST parsing and code generation with source maps
• A proxy-based mod.exports object that lets you read and mutate exported values like plain JS objects/arrays
• Built-in handling for common patterns like export default defineConfig({...}) wrapper calls
• Formatting preservation (quote style, indentation) inherited from recast, so diffs stay minimal

Common Use Cases

• Writing codemods that update config files (vite.config.js, nuxt.config.ts) as part of a migration or plugin installer
• Building CLI scaffolding tools that need to inject new imports or config options into existing project files
• Automating dependency or plugin registration by mutating an array/object inside a config export
• Programmatically reading and updating structured JS/TS config without losing developer-authored formatting

Under The Hood

Architecture Magicast wraps a recast-parsed AST in a proxy layer (core.ts, proxy/) that intercepts property reads/writes on the parsed module’s exports and translates them into the corresponding AST mutations, with babel.ts and format.ts handling parsing and formatting-preserving code generation respectively. Tech Stack Built in TypeScript as an ESM package with three runtime dependencies — @babel/parser, @babel/types, and source-map-js — using a vendored copy of recast, built with tsdown, and tested with Vitest including a dedicated build-output test pass (test:build). Code Quality The project runs ESLint (via eslint-config-unjs) and Prettier in its lint script, tracks coverage with Codecov, and maintains a full unit test suite alongside type-checking via tsc --noEmit. API Design The core idea — treat AST mutation like editing a JSON object via mod.exports.default.foo.push(...) — collapses what would otherwise require deep Babel/recast knowledge into a handful of intuitive method calls, which is the library’s main design win.