magicast

Magicast allows you to easily manipulate arguments passed to function calls. When a module export is a function call (e.g., export default defineConfig({ ... })), you can access the arguments via the $args property and check the $type property.

import { parseModule, generateCode } from "magicast";

const mod = parseModule(`export default defineConfig({ foo: 'bar' })`);

// Support for both bare object export and `defineConfig` wrapper
const options =
  mod.exports.default.$type === "function-call"
    ? mod.exports.default.$args[0]
    : mod.exports.default;

console.log(options.foo); // bar

You can install Magicast using your preferred package manager. It is recommended to install it as a development dependency.

yarn add --dev magicast

npm install -D magicast

pnpm add -D magicast

The default entry point for magicast includes Node.js filesystem utilities. To use the core AST manipulation logic in a browser or Web Worker, import from magicast/core instead.

import { parseModule } from "magicast/core";

Magicast provides high-level filesystem utilities to read, manipulate, and write back JS/TS files using a JSON-like syntax. This is the easiest way to programmatically update configuration files.

1. Use loadFile(path) to get a module object.
2. Access properties via mod.exports using familiar dot notation.
3. Use writeFile(mod, path) to save the changes back to the file.

import { loadFile, writeFile } from "magicast";

const mod = await loadFile("config.js");

// Append 'b' to the 'foo' property of the default export
mod.exports.default.foo.push("b");

await writeFile(mod, "config.js");

Magicast uses a proxy mechanism to represent Abstract Syntax Tree (AST) nodes as interactive JavaScript objects. Every proxified entity (objects, arrays, functions, etc.) inherits from ProxyBase and includes a $ast property containing the underlying ASTNode.

To identify the type of a proxified node at runtime, check the $type property. Common $type values include:

• object
• array
• identifier
• function-call
• new-expression
• binaryExpression
• module
• imports

Because JavaScript is highly dynamic, Magicast's simplified syntax cannot cover every possible edge case. Accessing properties on nodes might throw errors if the input code doesn't match the expected structure. It is highly recommended to wrap your modification logic in a try/catch block.

import { loadFile, writeFile } from "magicast";

function updateConfig() {
  try {
    const mod = await loadFile("config.js");

    mod.exports.default.foo.push("b");

    await writeFile(mod);
  } catch {
    console.error("Unable to update config.js");
    // handle error
  }
}

Use the builders utility to programmatically construct new AST nodes, such as function calls, and assign them to your module structure.

import { parseModule, generateCode, builders } from "magicast";

const mod = parseModule(`export default {}`);

// Create a function call: create([1, 2, 3])
const options = (mod.exports.default.list = builders.functionCall(
  "create",
  [1, 2, 3],
));

console.log(mod.generateCode()); // export default { list: create([1, 2, 3]) }

Magicast provides experimental high-level helpers for common configuration tasks (like adding Nuxt modules or Vite plugins). These are located in magicast/helpers.

Note: These helpers are experimental and may move to a separate package in the future.

import {
  deepMergeObject,
  addNuxtModule,
  addVitePlugin,
  // ...
} from "magicast/helpers";

If you are working with code strings rather than files, use parseModule to create a module object and generateCode to turn it back into a string.

Note that generateCode returns an object containing both the code and a map (for source maps).

import { parseModule, generateCode } from "magicast";

// Parse to AST
const mod = parseModule(`export default { }`);

// Manipulate using familiar syntax
mod.exports.default.foo ||= [];
mod.exports.default.foo.push("b");
mod.exports.default.foo.unshift("a");

// Generate code
const { code, map } = generateCode(mod);

If Magicast's simplified syntax is insufficient for a specific transformation, you can access the raw AST node directly via the $ast property on any Magicast node.

import { parseModule, generateCode } from "magicast";

const mod = parseModule(`export default { }`);
const ast = mod.exports.default.$ast;
// Perform direct AST manipulation on 'ast'