Configuration

ReeWeb has very little to configure. Everything that varies between environments lives in .env and is read directly from Bun.env. Everything that varies between projects lives in TypeScript files under config/ that you edit like any other source file.

The .env File

Copy the example file:

cp .env.example .env

The full set of variables:

SITE_URL=https://example.com
BASE_URL=/
PORT=3000
PUBLISHER_PORT=3011
PUBLISHER_PREVIEW_PORT=3012
PUBLISHER_BRANCH=main
BLOG_DIR=engineering-notes
OPEN_IDE=vscode
# MCP_ENABLE_TEMPLATE_RENDER=true  # enables MCP template/page execution
# MCP_ENABLE_MUTATIONS=true        # enables MCP operations that write files

The required variables are strict and env-only: each is read from .env (no fallback to package.json or a hidden code default), and the script exits with an error if the value is missing. Where a script accepts an equivalent CLI flag (--site-url, --base-url, --port, --blog-dir), the flag takes precedence over the environment value. This keeps every configurable default visible in one place - your .env - rather than buried in code.

• SITE_URL - when set, the SSG generates <link rel="alternate" hreflang="..."> tags pointing to absolute URLs for each language variant, required by Google for multi-language SEO. Read by the ssg, sitemap, and rss scripts.
• BASE_URL - the URL path the site is mounted at; / for a domain root, or e.g. /docs/ when served from a sub-path.
• PORT - the port the dev server (bun dev) and preview server (bun preview) listen on.
• BLOG_DIR - the folder under src/public/ scanned for blog posts when generating the RSS and JSON feeds.

OPEN_IDE is the one optional variable: it selects which editor the dev inspector's "open in editor" action launches - one of vscode, zed, nvim, sublime, or idea. It is not required to run the dev server or generate the site; it is only consulted when you use that inspector action, which reports a clear error if OPEN_IDE is unset. See Dev Inspector - Editor Configuration.

The MCP variables are also optional and should normally be supplied only to the local MCP process. See MCP Server for the security model and tool reference.

SSG Options

The bun ssg script accepts several flags:

bun scripts/ssg.ts --public ./src/public --dist ./dist --base-url / --site-url https://example.com --verbose

--base-url and --site-url have no code default: when the flag is omitted they read BASE_URL / SITE_URL from .env, and the script exits with an error if neither the flag nor the environment variable is set.

config/supported_locales.ts

Declares the locales your site supports (BCP 47 codes):

export const locales = ["en-us", "sl-si"] as const;
export const active_locales = ["sl-si", "en-us"] as const;
export const soft_launch_locales: string[] = [];
export const default_locale = "sl-si";

export const locale_names: Record<string, string> = {
    "en-us": "English",
    "sl-si": "Slovenian",
};

export const locale_aliases: Record<string, string> = {};

Adding a new locale is a one-file change here plus a matching {locale}.json translation file.

config/redirects.ts

Declares URL redirects (301 by default, 302 for temporary):

export const redirects: { from: string; to: string; status?: 301 | 302 }[] = [
    { from: "/old-page", to: "/new-page" }, // 301
    { from: "/promo", to: "https://example.com/landing", status: 302 }, // 302
];

Redirects are validated in two phases by lib/redirects.ts:

1. Schema validation - checks from starts with /, has no file extension, to is non-empty
2. Collision check - after rendering, verifies from doesn't collide with a page or asset

Emitted as:

• dist/_redirects - Cloudflare Workers Static Assets format
• dist/{from}/index.html - HTML meta-refresh stubs (fallback for other hosts)

config/pagination.ts

Declares which routes get paginated output and how. The default config enables pagination for the blog:

export const pagination: PaginationConfig = {
    enabled: true,
    per_page: 10,
    path_segment: "",       // /blog/2/ - no untranslated "page" in the URL
    show_when_single_page: false,
    always_show_prev_next: true,
    variant: "full",         // "full" or "simple"
    routes: [
        { route: "blog" },
    ],
};

Records are collected from markdown files by default. To supply records from an external source, export load_records(locale) from the route's index.ts. See Pagination.

package.json Scripts

The scripts you'll use most:

For hreflang links, pass --site-url directly:

bun scripts/ssg.ts --public ./src/public --dist ./dist --site-url https://example.com --verbose

How Bun Loads .env

Bun reads .env files automatically at startup - there's no dotenv dependency to install. Variables become available on Bun.env.NAME.