Project structure - better-router

Keep routes and middleware under src. Everything else is optional until you need it.

src/
  routes/                    # pages and API routes
    _document.tsx            # HTML document (title, CSS, fonts)
    _layout.tsx              # root layout (nav, chrome)
    _layout.server.tsx       # optional loader for the root layout
    _error.tsx               # uncaught errors
    _404.tsx                 # unmatched routes
    _middleware.ts           # nested middleware for /
    index.tsx                # GET /
    index.server.tsx         # loader / action for /
    about.tsx                # GET /about
    guide.mdx                # GET /guide (markdown page)
    users/
      _layout.tsx            # wraps /users/*
      [id].tsx               # GET /users/:id
      [id].server.tsx
    blog/
      index.island.tsx       # island page
      _Counter.tsx           # not a route (_ prefix)
    api/
      hello.ts               # GET /api/hello
      webhooks/
        stripe.ts            # POST /api/webhooks/stripe
  components/
    markdown/                # auto-registered MDX components
      Callout.tsx
  middleware/                # global Hono middleware, sorted by name
    01.logger.ts
  worker.ts                  # Cloudflare: fetch / scheduled / queue / email
public/                      # copied to dist/client as-is
.env                         # local Node / Vite secrets (gitignored)
.dev.vars                    # local Wrangler secrets
wrangler.jsonc               # Cloudflare deploy + bindings
vite.config.ts

Generated at runtime (gitignored):

.better-router/manifest.json # route manifest from the client build

Conventions

Location	Role
`src/routes/*/.tsx`	React page. Default export is the component.
`src/routes/*/.{md,mdx}`	Markdown page. Same routing as `.tsx`.
`src/components/markdown`	React components mapped into markdown pages.
`src/routes/*/.island.tsx`	Island page. Static HTML plus selective hydration.
`src/routes/*/.server.tsx`	Server-only loaders, actions, and flags.
`src/routes/*/.ts`	API route. Export `GET`, `POST`, and other HTTP methods.
`src/routes/_layout.tsx`	Layout for the directory and its children.
`src/routes/_document.tsx`	HTML shell. Put `<title>`, fonts, and CSS here.
`src/routes/_error.tsx`	Error page. Receives `{ error, status }`.
`src/routes/_404.tsx`	Not-found page.
`src/middleware`	Global Hono middleware, sorted by file name.
`src/worker.ts`	Cloudflare Worker entrypoint. See Worker entrypoint.
`public/`	Favicon, robots.txt, static files.

Files and folders that start with _ are not routes. _layout.tsx, _document.tsx, _error.tsx, _404.tsx, and _middleware.ts are special files. Use _Button.tsx for colocated components. Directories wrapped in parentheses are groups. (marketing)/about.tsx still maps to /about.

Required vs optional

You can ship a site with only src/routes and src/middleware. Add src/worker.ts and wrangler.jsonc when you deploy to Cloudflare — the plugin then infers target: "cloudflare". Node apps do not need either file.