Install & first run

Requirements

Terrarium runs on Apple Silicon and Intel Macs. Before installing, make sure you have:

• macOS 12 (Monterey) or later
• Node.js 18 or later — used for bundling and dependency installation behind the scenes

You don't need npm, yarn, create-react-app, or any project scaffolding tool. Terrarium handles all of that internally.

Install with Homebrew (recommended)

The fastest way to install Terrarium is via Homebrew. The cask is published from a tap maintained by the project author, so the install comes straight from the same release as the GitHub download.

brew tap michellemayes/terrarium
brew install --cask terrarium

To upgrade later when a new version ships:

brew upgrade terrarium

Install manually

If you don't use Homebrew, download the latest .dmg from the GitHub releases page, open the disk image, and drag Terrarium into your Applications folder.

To launch Terrarium from the command line after a manual install, add this alias to your shell config:

alias terrarium='open -a Terrarium'

The Homebrew install registers a terrarium command for you automatically, so you only need this alias for the manual flow.

Open your first file

With Terrarium installed, you have four equally valid ways to open a .tsx or .jsx file:

1. Drag and drop the file onto the Terrarium dock icon
2. Double-click the file in Finder (after registering Terrarium as the default opener for .tsx)
3. File picker — launch Terrarium and use the in-app open dialog
4. CLI — run terrarium myfile.tsx from your terminal

The CLI option is the one you will probably use most often, because it composes well with editors and pair-programming agents like Claude Code.

What gets rendered

Terrarium renders the default export of your file as a React component. If your component imports any npm packages (for example recharts, framer-motion, or lucide-react), Terrarium detects the imports, installs the packages on demand, and includes them in the bundle. The first run of a brand-new dependency takes a few seconds; subsequent renders are instant because the dependencies are cached.

Tailwind CSS v3 utility classes work out of the box — you can write className="flex items-center gap-3 text-violet-400" in any component without configuring anything.

Live reload

Once a file is open, Terrarium watches it for changes. Save the file in any external editor — VS Code, Zed, Cursor, vim, or Claude Code — and Terrarium re-bundles and re-renders within a second. There is nothing to enable; live reload is on by default.

If a save introduces a build error (a syntax error, a missing import, a type mismatch), Terrarium shows a collapsible error banner with the line number and keeps your last good render visible behind it. You can keep editing and the preview will recover as soon as the next save compiles cleanly.