Next.js on the platform
web/ is an ordinary Next.js App Router app. This page is what the platform does with it: how it's built and served, where records may be read, how variables reach the code and the browser, and what the router in front adds and strips.
web/ is the app
Pages live in web/app/**/page.tsx, route handlers in web/app/**/route.ts, and shared code wherever you like under web/ (the starters use web/lib/). Dependencies go in the root package.json. A next.config.(ts|mjs|js) in web/ is kept: Inference Bureau moves it to next.config.app.<ext> and puts a config in front that extends it, adding the app's development address to allowedDevOrigins and turning the dev-tools badge off unless the app sets devIndicators itself.
Development runs next dev in a sandbox, and each synced file hot-reloads; a change to package.json reinstalls dependencies, which takes longer than a save. process.env.NODE_ENV is development there and production in a deploy. Don't import from api/ in web/, or the reverse: a build places them apart. The one exception is web/emails/, which a build copies beside api/ so actions can send the app's emails.
What a build ships
A deploy builds production from the environment's files; development's dev server runs from the same layout. The build takes:
| In the app | In the build |
|---|---|
web/ | The root: Next.js wants app/ there |
api/ | ib/api/, with a registry of its actions and the route that runs them, /_ib/actions. Don't define a route there |
web/emails/ | Its place under the root, and a second copy under ib/ for actions |
package.json | Yours, with next, react and react-dom added when missing, the SDK installed from the build itself, TypeScript and the React and Node types added, and vitest left out. Node 24 unless engines pins another |
| Everything else | Stays in the app's files and never ships: README.md, AGENTS.md, .agents/, tests/, the *.ib.ts metadata (read by Inference Bureau, not the build) |
next build type-checks every .ts and .tsx file under the app's tsconfig.json (or the one Next.js writes when there is none) and fails the deploy on an error; the version that's live stays in place. Problems shows the same errors in development as you type, so check it before deploying.
Server code and route handlers
Server components, server actions and route handlers read and write records with createClient(), which runs as the environment itself and reaches every record: it's made from IB_API_URL and IB_ENVIRONMENT_TOKEN, variables the browser never sees. Client components never get that client. They call the app's own route handlers, which check who's asking (currentUser() in a Members app) and read or write for them, or the records route.
// web/app/api/projects/route.ts
import { createClient } from "@inferencebureau/apps-sdk";
import { currentUser } from "../../../lib/auth";
export const dynamic = "force-dynamic"; // read per request, never at build time
export async function GET() {
const me = await currentUser();
if (!me) return Response.json({ error: "Not signed in" }, { status: 401 });
const page = await createClient().project.findMany({ filter: { user: { equals: me.id } }, first: 50 });
return Response.json(page);
}
export async function POST(request: Request) {
const me = await currentUser();
if (!me) return Response.json({ error: "Not signed in" }, { status: 401 });
const body = (await request.json()) as { name?: string }; // JSON: a cross-site form can't send it
const record = await createClient().project.create({ name: String(body.name ?? ""), user: me.id });
return Response.json(record, { status: 201 });
}Server actions ("use server") are the starter's way for forms: the sign-in forms post to web/app/auth-actions.ts. Next.js protects them against cross-site posts. A route handler that changes data should take JSON, which a cross-site form can't send. In a route or a page's server code, createAiClient() is an action's ai for calling models, billed to the team.
force-dynamic
A production build prerenders every page it can. A page that reads records would then read them at build time, with a build's view of the data, and serve that until the next deploy. Mark pages and route handlers that read records export const dynamic = "force-dynamic", so they render per request; every page in the starters that reads records is. Pages that read nothing (a landing page with no records on it) can stay static.
Next.js's own caching otherwise applies as in any Next.js app: fetch caching, revalidate, use cache. The platform adds none and removes none in production; in development the router marks every response no-store (see below).
Environment variables
Set on Settings → Environment variables, per environment, and read as process.env.NAME. Development's dev server restarts with a change; production gets it on its next deploy. Inference Bureau sets IB_APP, IB_APP_URL, IB_ENVIRONMENT, IB_API_URL, IB_ENVIRONMENT_TOKEN and, in production, IB_FILE_VERSION; names starting IB_, VERCEL, __NEXT or NEXT_RUNTIME, and NODE_ENV, PORT, HOSTNAME, PATH, HOME and NEXT_PUBLIC_SHOPIFY_API_KEY, are reserved. See the list.
A variable named NEXT_PUBLIC_* is compiled into the browser's JavaScript: Next.js inlines it at build time, so production's pages carry the value from the deploy they were built in, and development's from the dev server's last restart. Never put a secret in one; marking a variable secret only hides it in the dashboard, and wouldn't keep it out of the bundle. Everything else is server-only and reaches pages, route handlers and actions, never the browser.
// web/app/analytics.tsx
"use client";
// Compiled into the browser's JavaScript at build time: never a secret.
const site = process.env.NEXT_PUBLIC_ANALYTICS_SITE;Use IB_APP_URL for links the app sends out: it's where visitors reach the environment, which a request's own host can't be trusted for behind the router, and it follows production's primary domain.
Records from the browser
The starter's web/app/api/records/route.ts is the one place pages' own scripts reach records: serveRecords(request, api) answers as the api it's given, the signed-in user's signed-in role in a Members app, or null (a 401) when no one is. AutoTable, AutoForm and the hooks in @inferencebureau/apps-sdk/react call it with a plain same-origin request, carrying the session cookie: useFindMany, useFindOne, useAction, useEnqueue, and live: true on any read to read again whenever its model's records change, whoever changes them. permissions.ib.ts decides what a page may read and change. A Site grants visitors nothing and has no records route: its pages read in server code only.
Uploads
A file field's file goes straight from the browser to storage, never through the app's route: the React client's upload(field, file) asks the records route for a direct upload, PUTs the file to the signed URL it gets back, and returns { directUploadToken } to write to the field, within a day. AutoForm's file chooser does this itself. Files can be up to 1 GiB this way; a public field's file reads as a lasting CDN URL, a private one through a URL signed for an hour. In server code, api.<model>.upload and createUpload do the same, and api.files is the environment's own storage apart from any record.
"use client";
import { useRecordsClient } from "@inferencebureau/apps-sdk/react";
export function AvatarPicker({ userId }: { userId: string }) {
const records = useRecordsClient();
async function onChange(e: React.ChangeEvent<HTMLInputElement>) {
const file = e.target.files?.[0];
if (!file) return;
// The file goes straight to storage; only the token goes through the records route.
const value = await records.model("user").upload("avatar", file);
await records.model("user").update(userId, { avatar: value });
}
return <input type="file" accept="image/*" onChange={onChange} />;
}Calls from other sites
The app's own pages need nothing. A page on another origin that calls the app's routes with fetch needs its origin named under cors in settings.ib.ts; the router answers preflights and adds the headers for the app, and a refused call lands in Logs as cors <origin>. Don't write OPTIONS handlers or CORS middleware. See Calls from other sites (CORS).
The router in front
Every request to the app's address, on inferencebureau.app or a custom domain, goes through Inference Bureau's router before it reaches the app. Visitors see the app's hostname and nothing of the hosting provider. What it does on the way:
| What the router does | |
|---|---|
| Request headers | Sets x-forwarded-host and x-forwarded-proto to the address the visitor used, and x-ib-client-ip to the visitor's IP from its own view of the connection (a visitor can't set it; the sign-in limits count by it). The rest pass through. |
| Response headers | Headers that name the provider are removed; Strict-Transport-Security is set; a Location that points at the provider's address is rewritten to the app's. Everything else passes through, so the app's own Cache-Control, ETag and the like reach the browser in production. |
| Development | Every response is marked Cache-Control: no-store, with ETag, Last-Modified and Expires dropped, so a saved file shows at once. Hot reload's WebSocket passes straight through. |
| Cookies | On the apps domain, a Set-Cookie's Domain is removed, so a cookie stays with the hostname that set it and never reaches another app. On your own domain the cookie is left as the app set it. |
| When the app can't answer | A sleeping dev server's visitor sees a starting page until it's up; a provider error page is replaced with the router's own 404 or 502; an app that can't be reached gets a 502 the caller can retry. Each carries the CORS headers an allowed origin expects. |
| Primary domain | Once production has one, a browser navigation to the apps-domain address is redirected (308) to the same path there. The page's own fetches, webhooks and API calls pointed at the old address keep being served. |
| Usage | Each proxied request and the bytes it sent count toward the app's usage. |
Custom domains
Production, or a development environment, can be served on a domain of your own, CNAMEd to Inference Bureau; a production domain can be primary, and IB_APP_URL and the apps-domain redirect follow it. See Custom domains.