# Goribu

> A React framework for full-stack apps on Cloudflare Workers, with a small API and predictable patterns for humans and coding agents.

## Project

- [Source code](https://github.com/anges244/goribu): Framework source, starter templates, and documentation.
- License: MIT.
- Requires Node.js 22 or newer. Starter apps use pnpm.
- TypeScript is the default; pass --js to create a JavaScript app.

## Start an app

    pnpm create goribu@latest my-app
    cd my-app
    pnpm install
    pnpm dev

Read the generated app's AGENTS.md and README.md before making changes.

## Core conventions

- Routes live in src/routes. A route can contain its React page and named HTTP handlers together.
- Handlers receive (req, res). Read input with req.params, req.query, and await req.body().
- Return res.render(props), res.json(data), res.text(text), res.redirect(url), or res.notFound().
- Use Link and Form from goribu for hydrated navigation and form behavior.
- Declare optional D1 and KV resources in goribu.config.js. Use request-scoped req.d1 and req.kv in server handlers.
- Keep server-only helpers outside the routes directory in .server.ts or .server.js files.
- Export route metadata with meta. Keep Stylesheet, head, ClientEntry, and the request nonce in the document shell.
- Only PUBLIC_* environment values are browser-visible. Never expose secrets in those values or page props.
- Request-time pages stream on the first visit. Hydrated navigation fetches page data. Static routes are built ahead of time and served without invoking the Worker.
- KV is eventually consistent. Use D1 when correctness requires fresh reads, and use migrations for schema changes.

## Commands

- pnpm dev: Local development.
- pnpm build: Production build.
- pnpm check: Read the production plan without changing resources.
- pnpm run deploy: Build and deploy. Database migrations and Worker deployment are not atomic.

Follow the app's ownership and approval instructions before installing dependencies, committing, or deploying.