Troubleshooting

“Node.js not found” on first run

Terrarium uses a local Node.js install to bundle and install dependencies. If you see an error about Node not being found, install Node 18 or later. The easiest path is via Homebrew:

brew install node

You can verify the install with node --version. Any version 18 or higher works; Terrarium does not require an exact version.

A dependency fails to install

When you open a file that imports an npm package Terrarium hasn't seen before, it runs an install in the background. If the install fails, the error banner shows the npm output. The most common causes:

• Network restrictions. If you are on a corporate VPN or behind a proxy that blocks the npm registry, the install will time out. Try again on an unrestricted network or configure npm to use your proxy in ~/.npmrc.
• A typo in the import. Terrarium attempts to install whatever name appears in the import statement. If you typed recartz instead of recharts, npm will return a 404 and the install will fail. Fix the import and save again.
• A package with native bindings. Some packages compile native code on install (sharp, canvas, certain crypto libraries). These need build tools available on your machine — usually Xcode Command Line Tools (xcode-select --install).

Bundle errors with no useful message

If the error banner shows an esbuild error you don't recognize, start by checking that your file's default export is a React component. Terrarium renders the default export, so a file that exports a plain function or an object will fail to mount.

// ✗ This won't render
export default function add(a: number, b: number) {
  return a + b
}

// ✓ This will render
export default function MyComponent() {
  return <div>Hello, terrarium</div>
}

The other common cause is mixing CommonJS and ESM exports. Stick to export default for the entry component and import for everything else.

File watcher isn't picking up saves

Terrarium uses the macOS file system events API to watch the file you opened. If saves aren't triggering re-renders, check the following:

• Is your editor saving the same inode? Some editors (notably some vim configurations and Sublime Text setups) save by writing to a temp file and renaming it on top of the original. This breaks watchers tracking the original inode. Switch your editor to “in-place” or “atomic write off” saving for that file.
• Did you open the file from a symlink? If the file you opened in Terrarium is a symlink, the watcher follows the link target. If the editor is saving to the link source, the watcher won't fire. Open the real path instead.
• Is iCloud Drive syncing the file? iCloud Drive can pause writes mid-save and produce confusing watcher events. Move the file out of an iCloud-synced directory while iterating.

Preview is blank but there's no error

If Terrarium shows an empty preview area with no error banner, the most likely cause is a component that returns null or renders nothing visible. Add a temporary <div>hello</div> at the top of your component to confirm the file is mounting at all. If that renders, your real component is hitting an early return — probably waiting on data, an effect, or a conditional that always evaluates false in this environment.

macOS Gatekeeper warning on first launch

If you installed via Homebrew and macOS shows a security warning when launching Terrarium for the first time, that's Gatekeeper checking the app. Open System Settings → Privacy & Security and click Open Anyway next to the Terrarium entry. The warning will not appear again on subsequent launches.

Getting more help

If none of the above resolves your issue, the project's GitHub issue tracker is the best next stop. Search for your error message first; if there is no existing issue, open a new one with the contents of the error banner, the file you were trying to open (with sensitive bits removed), and your macOS and Node versions.

• GitHub issues
• Source code
• Latest release notes