Configuration

Keep deployment identity and supported resources in one Node-loadable config file.

goribu.config.js

Default-export the result of defineConfig() from goribu/server:

import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-09-01",
  database: { type: "d1", name: "my-app-db" },
  kv: { name: "my-app-kv" },
});

D1 and KV are optional. Keep this file plain JavaScript even in a TypeScript app. Node loads it directly; do not import JSX, a Document, or application components here.

Options and defaults

Option	Meaning and default
`name`	Required Worker name. Lowercase letters, digits, and hyphens; no leading or trailing hyphen; at most 63 characters.
`compatibilityDate`	Required real date in `YYYY-MM-DD` format.
`compatibilityFlags`	Optional array of Workers compatibility flags. Defaults to an empty array.
`database`	Optional single D1 declaration. Omitted means no D1 binding.
`kv`	Optional single KV namespace. Omitted means no KV binding.
`responseHeaders`	Optional synchronous callback for Worker response defaults.

Unknown fields are rejected. Goribu generates its Wrangler configuration; edit this file rather than goribu.wrangler.jsonc or production output.

Resources

A D1 declaration accepts type: "d1", name, and optional replication. A KV declaration accepts only name. Both resource names may contain lowercase letters, digits, hyphens, and underscores, must start with a letter or digit, and are at most 63 characters.

Goribu owns the DB and KV bindings. You do not supply resource IDs or duplicate them in a Wrangler file.

For D1, omitted replication enables it on new databases and leaves existing settings untouched. Explicit true or false reconciles that setting during deployment. See D1 and KV.

Changing a resource name selects a different resource. It does not rename or delete the previous one. Removing a declaration also leaves the production resource intact.

Environment variables

Use .env for local values and .env.local for local overrides:

CATALOG_API_TOKEN=local-placeholder
PUBLIC_API_ORIGIN=https://api.example.com

Read server values through req.env in handlers or middleware. Only PUBLIC_* variables are available to browser code through import.meta.env; their values are embedded at build time and must not contain secrets.

Cloudflare also supports .dev.vars for local Worker bindings. If it exists, it replaces loading of both .env and .env.local for the server, even if the file is empty. Choose one local server-value workflow instead of expecting the files to merge.

Browser values still follow Vite's mode files: .env, .env.local, .env.development, .env.production, and their mode-specific local overrides. A value in .env.development does not become a server binding just because Vite can see it.

Production secrets

Put production values in .env.production. Deployment validates that file with Wrangler and uploads its keys as Worker secrets. Existing secrets omitted from the file remain on the Worker. Without the file, Goribu uses existing platform secrets; local .env is never an upload fallback.

A PUBLIC_* value remains public even if the same key is uploaded as a Worker secret. Keep real environment files out of Git and share placeholder names in .env.example.

Config evaluation does not load dotenv files into process.env. If the config reads an environment variable, supply it in the shell running the command.

Response headers

Use a callback for defaults on Worker-served responses:

import { defineConfig } from "goribu/server";

export default defineConfig({
  name: "my-app",
  compatibilityDate: "2026-09-01",
  // Return ordinary header values synchronously.
  responseHeaders({ request, env, mode, nonce }) {
    return { "X-Content-Type-Options": "nosniff" };
  },
});

The callback receives the original Request, Worker environment, development/production mode, and request nonce. Return a plain object of strings or arrays of strings. Route and framework headers take precedence; Vary tokens merge.

Body, redirect, cookie, and transport headers cannot be blanket defaults. This includes Content-Type, Content-Length, Content-Range, Content-Encoding, Location, Set-Cookie, Trailer, and Transfer-Encoding. Set them through the API that owns the response.

This callback does not run for Static Assets. App-authored public/_headers is currently rejected, so this API cannot establish a custom header policy for static pages. Goribu does not set a default CSP or CORS policy.

Development and build settings

Vite options belong in vite.config.js, not the Goribu app config. Keep goribu() in the plugins list. Tailwind is an app plugin; you can use ordinary CSS instead.

Changes to goribu.config.js or vite.config.js restart the development session. Invalid replacement config is reported while the existing session continues; fix it before relying on the new settings. If a newly added route is not recognized in an existing session, restart pnpm dev.