Start

Installation

Prerequisites

  • Node 22 or later
  • A package manager like npm, pnpm, yarn or bun
  • A Cloudflare account (only needed to deploy, not to build locally)

Create your app

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

The dev server starts and your app is at http://localhost:5173. create-goribu does not install dependencies for you. It scaffolds the project and prints the next steps.

New projects are TypeScript by default. Pass --js for a JavaScript project instead:

npx create-goribu my-app --js

It wires up React 19, Tailwind 4 and the Cloudflare Workers config, and ships an AGENTS.md so AI tools understand the framework (see AI-Assisted Development). Runtime dependencies are just goribu, react and react-dom. Everything else like Vite, Wrangler, Tailwind, the TypeScript toolchain, is a devDependency. Goribu targets current browsers: whatever React 19 supports, Goribu supports.

Project structure

A fresh app looks like this (a --js project has the same shape with .js/.jsx files and a jsconfig.json):

my-app/
├─ AGENTS.md            rules so AI assistants understand Goribu
├─ goribu.config.js     framework + database config
├─ wrangler.jsonc       Cloudflare runtime config
├─ vite.config.ts       build pipeline
├─ tsconfig.json
├─ package.json
├─ .env / .env.production
├─ public/              static files served from / by the CDN
└─ src/
   ├─ app.css           global stylesheet (Tailwind 4 by default)
   ├─ document.tsx      the HTML shell around every page
   ├─ server.tsx        Worker entry — calls createApp(...)
   ├─ client-entry.ts   browser entry — import "goribu/client"
   ├─ goribu-env.d.ts   binding types (TypeScript projects)
   └─ routes/           pages + handlers; file path = URL
      ├─ index.tsx      → /
      └─ greet.tsx      → /greet

Most of your work happens in a handful of these.

Files you'll use often

  • src/routes/ — your pages and handlers. Each file's path becomes its URL, and a file co-locates the page with the handlers that feed it. See Routes for more.
  • src/app.css — the global stylesheet. Tailwind 4 is the default but not a requirement. Replace it with plain CSS or another setup you want. If you drop Tailwind also remove @tailwindcss/vite from vite.config.ts and package.json.
  • src/document.tsx — the HTML shell wrapped around every page: language, viewport, favicon, global stylesheets, fonts, analytics. Page-specific titles do not go here as routes declare those with a meta export. See Rendering.
  • public/ — static files served from the site root (public/logo.png → /logo.png) by Cloudflare's CDN, not your Worker. Good for favicons, logos, robots.txt and Open Graph images.
  • goribu.config.js — framework-level settings, mainly your database. Both goribu dev and goribu deploy read it. See Configuration.

Files you'll rarely touch

  • src/server.tsx — the Worker entry. It wires the generated routes, Document and error pages into Goribu via createApp. Most apps leave it alone.
  • src/client-entry.ts — the browser entry, usually just import "goribu/client". Keep that line first; add browser-only setup (analytics, error reporting) after it.
  • vite.config.ts — the build pipeline. The plugin order is fixed; change it only to add a Vite plugin or adjust styling. See Configuration.
  • wrangler.jsonc — Cloudflare runtime config. Reach for it when you need a binding Goribu doesn't manage yet (KV, R2, queues, Durable Objects, service bindings). Do not add d1_databases or hyperdrive entries — Goribu synthesizes those from goribu.config.js.

Files Goribu creates later

  • migrations/ appears the first time you run npx goribu migration:create <name>, holding your schema changes. See D1 and Postgres.
  • .goribu/ is generated — the route manifest, build output and resource cache. Don't edit it; it is gitignored.