Workspaces and gateway

A workspace runs isolated applications behind one domain-routing gateway. Add an application from the workspace root; the CLI scaffolds apps/reports and registers it in wrnexus.workspace.ts:

wrnexus workspace add reports --domain=reports.localhost
bun install
bun run dev

Forward authentication

Point protected applications at a dedicated verifier endpoint. The verifier must return 2xx for an authenticated session, 401/403 to deny access, or an HTTP redirect to begin browser login.

// wrnexus.workspace.ts
{
  name: "admin",
  dir: "apps/admin",
  domains: ["admin.localhost"],
  auth: { forward: { url: "http://sso.localhost:3000/api/verify" } },
}

The gateway forwards cookies, authorization, original host, protocol, method, path, and query. Inside the verifier, ctx.url identifies the SSO verifier request—not the original admin URL. Use @wrnexus/helpers to reconstruct and validate the original destination:

import type { Context } from "@wrnexus/core";
import { redirectToLogin } from "@wrnexus/helpers";

export const GET = async (ctx: Context) => {
  if (await hasValidSession(ctx)) {
    return new Response(null, { status: 204 });
  }

  return redirectToLogin(ctx, "/login", {
    allowedHosts: ["admin.localhost:3000", "reports.localhost:3000"],
  });
};

Always allowlist redirect hosts. After login, validate or sign the returnTo value before redirecting. Keep internal app ports private and open applications through the gateway port.

Practical example

Register applications explicitly and verify host routing through the gateway port.

bunx wrnexus workspace company-platform
cd company-platform
bunx wrnexus workspace add admin --domain=admin.localhost
bunx wrnexus gateway --port=3000

What to verify

Run this against the selected profile, inspect the generated or returned result, and add a test for both the successful path and its most important failure path.

Configuration

Keep configuration in wrnexus.config.ts, select an explicit profile, and store secrets only in validated environment variables. Use wrnexus config . --explain to review the resolved non-secret configuration.

Implementation workflow

bunx wrnexus doctor .
bunx wrnexus typecheck .
bunx wrnexus inspect routes .
bunx wrnexus build .

Start from the exact installed package page, implement the smallest server-owned contract, and add browser behavior only where interaction requires it. Run the production build because development-only success does not prove deployability.

Verification checklist

• Inputs are validated at the authoritative server boundary.
• Authentication and resource authorization are tested independently.
• Generated routes and application types are current.
• Error, empty, loading, denied, and success states are documented.
• The production artifact starts and serves the expected route.

Release scope

This guide describes installed 0.8.7 capabilities. Follow linked package declarations for exact signatures; undocumented behavior is not guaranteed.

Browse package APIs · CLI reference · Troubleshooting · Support