Getting Started

Manic is a zero-config React SPA framework designed exclusively for Bun. It pairs an OXC-powered build engine with a Hono server runtime, so you write code and Manic handles the bundler, dev server, router, and production output.

This guide walks you from a clean machine to a running Manic application.

Prerequisites

Tool	Minimum	Notes
Bun	`1.0.0+`	The framework uses `Bun.serve`, `Bun.build`, `Bun.Glob`, and `Bun.spawn` — Node.js is not supported.
Node-compatible OS	macOS, Linux, or WSL	Native Windows is supported through Bun's installer.
Editor	VS Code, Cursor, Zed	TypeScript is enabled out of the box.

Install Bun if you do not already have it:

curl -fsSL https://bun.sh/install | bash

Scaffold a New Project

The fastest way to bootstrap a Manic app is with the official create-manic template.

bun create manic my-app
cd my-app
bun install
bun dev

npx create-manic my-app
cd my-app
npm install
npm run dev

yarn create manic my-app
cd my-app
yarn dev

pnpm create manic my-app
cd my-app
pnpm dev

The dev server starts on http://localhost:6070 by default.

What You Just Generated

index.html

main.tsx

manic.config.ts

~manic.ts

package.json

tsconfig.json

app/routes/ — every .tsx becomes a page.
app/api/ — every folder with an index.ts becomes a Hono route.
app/index.html — the HTML shell the build engine fills in.
app/main.tsx — the React entry point mounted on #root.
manic.config.ts — plugins, providers, build and router options.
~manic.ts — the Bun server entry. Do not delete.

A more thorough breakdown is available in Project Structure.

Add Your First Route

Manic's router maps any .tsx file under app/routes/ to a URL. Files prefixed with ~ are excluded from routing — use the prefix for components and helpers you want to colocate.

app/routes/about.tsx

import { Link } from 'manicjs';

export default function AboutPage() {
  return (
    <main>
      <h1>About</h1>
      <p>This file became /about with no configuration.</p>
      <Link to="/">← Back home</Link>
    </main>
  );
}

Visit http://localhost:6070/about. React Fast Refresh, view transitions, and code-splitting are already wired up.

Add Your First API Route

Every directory in app/api/ that exports a Hono app becomes an endpoint. Manic bundles each route into its own chunk so cold starts on serverless platforms stay fast.

app/api/hello/index.ts

import { Hono } from 'hono';

const app = new Hono();

app.get('/', c => c.json({ message: 'Hello from Manic' }));

export default app;

The endpoint is now available at GET /api/hello. Read API Routes for middleware, parameters, and type-safe RPC clients.

Manual Installation

If you prefer to wire things up yourself instead of using the template:

mkdir my-app && cd my-app
bun init -y
bun add manicjs react react-dom
bun add -d @types/react @types/react-dom

Create the mandatory server entry at the project root:

~manic.ts

import { createManicServer } from 'manicjs/server';

const app = await createManicServer();

export default {
  port: Number(Bun.env.PORT) || 6070,
  fetch: app.fetch,
};

Add a config file so plugins and providers can be wired up later:

manic.config.ts

import { defineConfig } from 'manicjs/config';

export default defineConfig({
  app: { name: 'My App' },
});

Add a starter page:

app/routes/index.tsx

export default function Page() {
  return <h1>Hello from Manic!</h1>;
}

Add an HTML shell that the build engine will fill in:

app/index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./main.tsx"></script>
  </body>
</html>

And a React entry point:

app/main.tsx

import { createRoot } from 'react-dom/client';
import { Router } from 'manicjs';

createRoot(document.getElementById('root')!).render(<Router />);

Start the dev server:

bunx manic dev

Build for Production

When you are ready to ship, produce an optimized bundle:

bunx manic build
bunx manic start

manic build runs oxlint, regenerates app/~routes.generated.ts, bundles the client, the API routes, and the server, and finally hands the artifacts to your configured provider.

Getting Started

Getting Started

Prerequisites

Scaffold a New Project

What You Just Generated

Add Your First Route

Add Your First API Route

Manual Installation

Build for Production

Next Steps

Project Structure

Routing Guide

API Routes

Plugins

Deployment

CLI Reference

On this page