Library / SDK
unjs/magicast avatar
unjs/magicast

Magicast's documented failure path is a human editing the file, and recast is vendored rather than depended on

🧀 Programmatically modify JavaScript and TypeScript source codes with a simplified, elegant and familiar syntax powered by recast and babel.

2,479 stars57 forksTypeScriptMIT

At a glance

What is it?
Magicast lets you edit a JavaScript or TypeScript file as if it were JSON and write it back with its original formatting intact, built on recast and babel. It is unusually honest about its own limits, recommending a try and catch around every call and shipping an example whose fallback tells a human to edit the file by hand. It is also unusually careful about its own packaging, running one test suite against both the source and the built output.
Who is it for?
Magicast is the right tool for the narrow job it does well, which is a build script or a configuration migration that has to edit a file a human will later read in a diff. The formatting preservation is the feature that matters, because a codemod that reflows a thousand lines is a codemod nobody reviews.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 16, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • unjs/magicast2,479 ★ · +1
Star history
Repository2026-09-292026-11-16
unjs/magicast2.5k2.5k

1 Stars in the last 48 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The documented failure path is a human editing the file

The notes section is the most useful paragraph on the page and it is not reassuring. Because the language is dynamic, the convention cannot cover all possible cases, and interacting with any node has a chance of throwing depending on the input code. The recommendation is to wrap every call in a try and catch, and preferably to write defensively. The example that follows makes the intent concrete:

js
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");
    console.error(
      "Please update it manually with the following instructions: ...",
    );
    // handle error
  }
}

Note what the fallback says. The expected outcome when the library cannot cope is that a person edits the file by hand. That is a defensible contract for a tool that rewrites source, and it is far better than a library that silently produces the wrong tree.

The library it is built on is vendored, not depended on

Three runtime dependencies appear in the package file: a parser, a types package, and a source map utility. Recast, the library the page credits for preserving formatting, is not among them. It is a development dependency, and there is a vendor directory at the repository root with a prepare script that runs a vendoring step before anything else. So recast is folded into the published output at build time rather than installed beside it, which is what lets the installed dependency count stay at three and keeps the formatting behaviour under the project's control instead of under a version range. The cost is that the build step becomes load bearing rather than optional, which is exactly why the test pipeline described below exists.

One suite runs against the source and against the build

The scripts are arranged around a simple and unusually disciplined idea. The plain test script runs the test runner against the source. A second script sets an environment variable and runs the same runner again, which is how the suite is pointed at the built output instead. A third script chains all three steps: run the tests, run the build, then run the build tests. The release script runs the test task and then a version bumper, so a release cannot skip the suite. Because the vendoring of recast happens during the build, testing only the source would leave the most fragile part of the pipeline unverified, and this arrangement is what closes that gap. It is a small repository and a small amount of configuration, but it encodes the lesson that a library whose correctness depends on a build step should test what the build produced.

The main entry point cannot run in a browser

The package exposes three entry points and the split is about environment, not about features. The main one includes filesystem utilities, which is what the load and write helpers use. The second is the same parser and code generator with the filesystem code removed, and the page says to import from it when you want to run in a browser or a worker. The third holds a set of high level helpers for common tasks, and the page is careful about them: they are described as an experiment that might be moved to a separate package in the future, so their location is explicitly not settled. The package is also marked as having no side effects, which is what lets a bundler drop it entirely when nothing is imported from it. For most consumers the practical rule is simple: if you are writing a build script, use the main entry point; if you are writing a plugin that runs in the browser, use the core one and leave the helpers alone until they settle.

Configuration wrappers are your problem, and there is a documented trick

Configuration files come in two shapes: a plain object export, or the same object wrapped in a call to a configuration helper. The library does not choose for you, and the example shows how to cope. Read the node's type marker; if it reports a function call, take the first entry from its argument list, otherwise use the export itself. Alongside that marker there is a raw escape hatch: any proxied node exposes the underlying syntax tree node, so you can drop down to the parser's representation whenever the pretty interface runs out. Both are used in the same example, which is the honest picture of how the library is meant to be used: the sugar handles the ninety percent case and the escape hatches are not hidden. The array methods and logical assignment operators work straight through the proxy, so `foo ||= []` followed by a push reads like ordinary code.

Three install commands for a project that develops with one package manager

The install section shows three commands, one each for three package managers, all adding the library as a development dependency. The development instructions then say to install a long term support runtime, enable the corepack shim, install dependencies with one package manager, and run an interactive test mode. So the library is convenient to consume three ways and is built and tested one way, which is normal and unremarkable. The tooling around it is a little more elaborate than the library itself: a bundler configured through its own config file for the build, a type check with no output, linting through a shared configuration with a cache, formatting through a separate tool with its own ignore file, a version bumper for releases, staged formatting wired to a commit hook, and a dependency update bot. None of that reaches the published package, and all of it is evidence of what a well-run small library looks like from the inside.

Patch releases every few months, still on a zero major

The three most recent tags are a patch in mid May 2026, a patch at the end of July, and a patch in mid September, with the branch pushed to again three weeks after the last one. So the line is moving steadily at a few months per release, and every one of those releases is a patch rather than a minor or a major. Nothing on the page says why the major is still zero, and a library whose interface is described as unable to cover all cases is exactly the kind where a version number carries real information about whether you can upgrade safely. The readme points at a changelog file at the repository root as the place to check, which is the right advice: with patch-only releases on a zero major, the changes between two versions are small by design, and the only question worth asking before upgrading is whether one of them changes a convention you rely on. There is one more signal on the page worth noting, and it is about where the project sits in its own ecosystem: the repository belongs to an organisation whose packages share a naming style and a maintainer, and the readme links out to generated reference documentation and to a package-size report rather than describing bundle weight in prose. A library whose selling point is a three dependency install has an obvious incentive to keep a size badge honest, which is a small thing, but it is the kind of small thing that tends to be maintained carefully.

Editorial conclusion

Magicast is the right tool for the narrow job it does well, which is a build script or a configuration migration that has to edit a file a human will later read in a diff. The formatting preservation is the feature that matters, because a codemod that reflows a thousand lines is a codemod nobody reviews. Three things to weigh first. The failure mode, which the project states outright: the interface cannot cover every case, any option might throw depending on the input, and the recommended handling is a try and catch whose fallback message asks a person to edit the file. Second, whether the build-time vendoring of recast suits you, since that is what keeps the installed dependency count at three and it is the most unusual thing about the packaging. And third, the version, since releases are patch bumps every few months and the line is still on a zero major, so pin exactly and read the changelog before taking a minor.

Frequently asked questions

What does Magicast do?

It parses JavaScript or TypeScript and lets you modify the syntax tree through a JSON-like interface, then writes the file back with the original formatting preserved. It is built on recast and babel.

Can Magicast be used in a browser or a worker?

Not from its main entry point, because that one contains filesystem utilities. Import from the core entry point instead, which parses and generates code without touching the filesystem.

What happens when Magicast cannot handle a file?

The documentation says its convention cannot cover every case and that any option might throw depending on the input. It recommends wrapping calls in a try and catch, and its example fallback prints a message asking a person to update the file manually.

How do I handle a config file wrapped in a function call?

Check the node's type marker. The documented example branches on whether the default export is a function call, and if so reads the first entry of its argument list, otherwise using the export directly.

What are the runtime dependencies of Magicast?

Three: a parser, a types package and a source map utility. recast, which the project credits for preserving formatting, is a development dependency and is vendored into the build output instead.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. unjs/magicast on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/unjs-magicast.svg)](https://hysenlabs.com/projects/unjs-magicast)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/unjs-magicast.svg)](https://hysenlabs.com/projects/unjs-magicast)

Was this useful?