Development preview

This page is for the development team and any client reviewer who wants to understand which local services are running.

Apps

The prototype has three local surfaces:

• storefront web app
• API service
• docs site

Portless URLs

The default root command uses Portless so the local services have stable names:

storefront: https://web.kof
api:        https://api.kof
docs:       https://docs.kof

Portless requires Node.js 24+ on PATH and may ask once for permission to trust its local HTTPS certificate and bind the local proxy on port 443. The root bun dev wrapper launches Portless through Node, pins PORTLESS_STATE_DIR to ~/.portless, derives the default TLD from the git repo name (kof-repo becomes kof), prompts before clearing stale non-443 Portless proxy state, and explicitly starts the HTTPS proxy on port 443 so these URLs stay clean. If Portless state gets stuck after a sudo attempt, run portless clean or remove stale files under ~/.portless, then retry.

Firefox-family browsers, including Zen, may not trust the local Portless CA by default. If web.kof or API fetches to api.kof show SEC_ERROR_UNKNOWN_ISSUER, run portless trust, then either enable security.enterprise_roots.enabled in about:config or import ~/.portless/ca.pem into the browser certificate authorities. Accepting a one-off browser exception for web.kof does not trust api.kof; open https://api.kof/health directly or import the CA to verify the API host is trusted too.

If Portless prints URLs like https://web.kof:1355, read Portless debugging. That page documents the WSL and macOS Tailscale port 443 conflict and the narrower fix that avoids disabling Tailscale entirely.

The plain fallback still uses direct ports:

storefront: http://localhost:5173
api:        http://localhost:8787
docs:       http://localhost:3000

Commands

From the superrepo root:

bun install
bun dev

Fallback without Portless:

bun run dev:plain

Individual services:

bun run web:dev
bun run api:dev
bun run docs:dev

Validation:

bun run typecheck
bun run web:build
bun run docs:build

The docs site intentionally uses the default Fumadocs dark theme so it stays readable and low-maintenance.