creating-bunderstack-apps

name	creating-bunderstack-apps
description	Use when working in a repository that depends on bunderstack - starting or structuring the application, adding or changing oRPC procedures, bases, middleware, access rules, jobs, storage, or realtime, choosing a runtime integration, or preparing it for production.

Creating Bunderstack Apps

Workflow

1. Inspect the product brief and target runtime.
2. Choose the layout from the table below.
3. For a full TanStack Start SaaS, copy templates/tanstack-start-saas/.
4. Configure schema, access, auth, env, storage, jobs, realtime, and the oRPC API graph.
5. Mount the single app.handler integration.
6. Add committed migrations and a deployment blueprint before production.
7. Run the verification contract.

Condition	Layout
Small API with short configuration	src/bunderstack.ts
Auth, access, jobs, env, or custom oRPC procedures need independent modules	src/bunderstack/
Full SaaS	Copy templates/tanstack-start-saas/ and keep its modular layout

Runtime decision recipe

Choose the process boundary before listing files. A TanStack Start SaaS keeps the API mount in Start. A standalone Bun API has src/bunderstack.ts (or the modular src/bunderstack/ entry) and a Bun process that delegates to app.handler.

For a React SPA brief, use the browser-only layout: an api/ project contains the Bunderstack entry and Bun API process, and a separate frontend/ project contains the React build. The API process owns app.handler; the browser client receives a configured API base URL and calls that process. Include both processes and the configured browser-to-API path in the proposed structure.

node_modules/bunderstack/llms.txt is a dense plain-text reference for the whole framework. Read it when a detail is not covered here.

Read application structure before placing the Bunderstack entry, schemas, authorization, or configuration modules, and before declaring procedures, bases, middleware, or errors. Read runtime integrations before mounting HTTP, adding a worker, or choosing a framework adapter. Read the verification contract after adding the app scripts and again before handoff or deployment.