LangENKO

Quickstart

Ship a Mandu app in 5 minutes — install, scaffold, dev. Two install paths, one prompt your agent can run end-to-end.

since v0.22
On this page

Quickstart

TL;DR — install Mandu (binary or npm), mandu create my-app, cd my-app && bun run dev, http://localhost:3333. Five minutes, three commands.

Why Mandu

Other fullstack frameworks were built on the assumption that a human types every line. Mandu was designed from day one for AI agents pouring out code — Guard enforces architectural boundaries at runtime, contracts derive types/validation/OpenAPI from one file, and 100+ MCP tools talk directly to your editor's agent. That's why five minutes is enough.

Install

Mandu ships in two parallel formats. Pick the one that matches your situation.

Path A · Standalone binary (no prereqs, ~132 MB)

Bun is embedded in the binary, so there's nothing else to install.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/konamgil/mandu/main/install.sh | sh

# Windows (PowerShell)
iwr https://raw.githubusercontent.com/konamgil/mandu/main/install.ps1 -useb | iex

Verify: mandu --version. If "command not found", restart your shell so the new PATH entry (~/.mandu/bin on Unix, %LOCALAPPDATA%\Mandu\bin on Windows) is picked up.

Path B · npm / Bun package (~5 MB, requires Bun)

Smaller download, but you need Bun installed.

bun --version
# 1.3.12 or newer required
bun install -g @mandujs/cli

If you don't have Bun: install from bun.sh/docs/installation. Node.js is not supported — Mandu's router, bundler, and test runner all bind to Bun APIs.

Scaffold

mandu create my-app
cd my-app

The scaffolder asks two questions:

  • Template — minimal / starter / agent-ready. Pick starter if unsure.
  • MCP agents — pre-wire Claude Code · Claude Desktop · Gemini CLI. Add later with mandu mcp add.

Run dev

bun run dev
# or, if you only have the standalone binary: `mandu dev`

Open http://localhost:3333. If the Mandu mascot waves back, you're up.

🤖 Agent Prompt

🤖 Agent Prompt — Bootstrap a new project
Bootstrap a new Mandu project. Walk me through:

1. Install Mandu — prefer the standalone binary:
   - Unix:    curl -fsSL https://raw.githubusercontent.com/konamgil/mandu/main/install.sh | sh
   - Windows: iwr https://raw.githubusercontent.com/konamgil/mandu/main/install.ps1 -useb | iex
   (Or `bun install -g @mandujs/cli` if Bun is already installed.)

2. `mandu create my-app` (template: `starter`).
3. `cd my-app && bun run dev`.
4. Open http://localhost:3333 and confirm the welcome page renders.

Diagnose using these invariants:
- routes live at app/**/page.tsx (.tsx only)
- .island.tsx with `use client` is required for hydration
- dev port is 3333
- the npm path requires Bun >= 1.3.12 (the binary embeds Bun)

Once dev is running, show me the project tree
(app/, src/client, src/server, src/shared, spec/, content/, mandu.config.ts).

Paste this into Claude Code · Cursor · OpenAI Codex · GitHub Copilot · Gemini CLI — any AI agent — and it just works. The page's ai-hint and invariants frontmatter is picked up automatically.

What you got

After scaffolding:

my-app/
├── app/
│   ├── page.tsx          # the "/" route
│   ├── layout.tsx        # body wrapper (Mandu emits <html>/<head>)
│   └── api/              # file-system API routes
├── src/
│   ├── client/           # UI code (FSD: shared/entities/features/widgets)
│   ├── server/           # server code (domain/application/infra)
│   └── shared/           # contracts and types shared across the boundary
├── spec/                 # specs (contracts, decisions, sketches)
├── content/              # MDX content layer
└── mandu.config.ts       # framework config

Five things you must not miss

  • Bun ≥ 1.3.12 for the npm path (binary embeds Bun, no prereq).
  • Routes = app/**/page.tsx only. .jsx, index.tsx, .mdx are ignored.
  • Only .island.tsx files hydrate. Plain .tsx is server-only.
  • Port 3333 is the default — change via mandu.config.ts (server.port).
  • Guard enforces boundaries at runtime — if features/* imports the internal of entities/*, the dev console rejects it on the spot.

For Agents

AI hint

Install via the standalone binary (curl/iwr) or `bun install -g @mandujs/cli`, scaffold with `mandu create my-app`, then `bun run dev` on port 3333. Routes live under `app/` as `page.tsx`. Bun >= 1.3.12 is required for the npm path.

Invariants
  • Bun >= 1.3.12 is required for the npm/Bun package path; the standalone binary embeds Bun and has no prerequisite
  • Routes are recognised only as `app/**/page.tsx` (no `.jsx`, no `index.tsx`)
  • Interactive components must end with `.island.tsx` and start with `"use client"`
  • The dev server defaults to port 3333; configure via `mandu.config.ts`
Guard scope
project-init