@rangojs/router 0.0.0-experimental.96fbd4b7 → 0.0.0-experimental.98

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.96fbd4b7",
+  version: "0.0.0-experimental.98",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.96fbd4b7",
+  "version": "0.0.0-experimental.98",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/i18n/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: i18n
+description: Locale-aware routing with `include("/:locale?", ...)`, locale resolution chains, and react-intl integration
+argument-hint: "[topic]"
+---
+
+# Internationalization (i18n) and Locale Routing
+
+Rango doesn't ship an i18n module. The router gives you the URL primitives
+(optional include prefixes, constraints, typed reverse) and you compose
+them with whatever message library you use — `react-intl`, `lingui`,
+`@formatjs/intl`, or hand-rolled.
+
+This skill covers:
+
+- Mounting routes under an optional locale prefix (`/`, `/en`, `/gb`)
+- Constraining the prefix to a known locale set
+- Resolving the active locale (URL → cookie → `Accept-Language` → default)
+- Generating localized URLs via `reverse()` round-trip
+- Wiring `react-intl` into an RSC route tree
+
+## URL Shape: Optional Locale Prefix
+
+Mount your localized routes under an optional include prefix so the
+default locale lives at the bare URL and other locales get a prefix:
+
+```typescript
+// urls.tsx
+import { urls } from "@rangojs/router";
+import { menuRoutes } from "./menu";
+
+export const urlpatterns = urls(({ include }) => [
+  include("/:locale?", menuRoutes, { name: "menu" }),
+]);
+```
+
+URLs that match:
+
+| URL            | Matched route   | `ctx.params.locale` |
+| -------------- | --------------- | ------------------- |
+| `/`            | `menu.index`    | `undefined`         |
+| `/en`          | `menu.index`    | `"en"`              |
+| `/c/breads`    | `menu.category` | `undefined`         |
+| `/en/c/breads` | `menu.category` | `"en"`              |
+
+> **Constrain to known locales** when you want unknown locales to fall
+> through to other routes (or 404) instead of being treated as a slug:
+>
+> ```typescript
+> include("/:locale(en|gb|fr)?", menuRoutes, { name: "menu" });
+> ```
+>
+> `/de` now 404s (constraint rejects `de`), and `/c/breads` continues to
+> match `menu.category` with `locale: undefined`. Without the constraint,
+> `/de` would match `menu.index` with `locale: "de"`.
+
+## Reading the Locale in Handlers
+
+Absent optionals are `undefined` (not `""`), so `??` coalesces correctly:
+
+```typescript
+import { Handler } from "@rangojs/router";
+
+export const MenuIndex: Handler<"menu.index"> = (ctx) => {
+  // ctx.params.locale is `string | undefined`
+  const locale = resolveLocale(ctx);
+  return <Welcome locale={locale} />;
+};
+```
+
+The `resolveLocale` helper below implements a typical fallback chain.
+
+## Locale Resolution
+
+URL is the strongest signal but you usually want a fallback chain:
+
+1. **URL prefix** — if the user navigates to `/gb/...`, honor it
+2. **Cookie** — sticky preference set by a previous language switcher
+3. **`Accept-Language`** — browser hint
+4. **Default** — your app default
+
+Put it in a small helper that every locale-aware handler calls:
+
+```typescript
+// lib/locale.ts
+import { cookies, headers } from "@rangojs/router";
+
+export const SUPPORTED_LOCALES = ["en", "gb", "fr"] as const;
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+const DEFAULT_LOCALE: Locale = "en";
+
+const isSupported = (v: string): v is Locale =>
+  (SUPPORTED_LOCALES as readonly string[]).includes(v);
+
+export function resolveLocale(ctx: {
+  params: Record<string, string | undefined>;
+}): Locale {
+  const fromUrl = ctx.params.locale;
+  if (fromUrl && isSupported(fromUrl)) return fromUrl;
+
+  const fromCookie = cookies().get("locale")?.value;
+  if (fromCookie && isSupported(fromCookie)) return fromCookie;
+
+  const accept = headers().get("accept-language") ?? "";
+  for (const tag of accept.split(",")) {
+    const code = tag.split(";")[0].trim().split("-")[0];
+    if (isSupported(code)) return code as Locale;
+  }
+  return DEFAULT_LOCALE;
+}
+```
+
+If you want to redirect to the canonical URL when the resolved locale
+doesn't match the URL (e.g., user has `gb` cookie but visits `/`), do
+that in a global middleware so it covers actions too:
+
+```typescript
+import { redirect } from "@rangojs/router";
+
+router.use("/*", async (ctx, next) => {
+  const fromUrl = ctx.params.locale;
+  const resolved = resolveLocale(ctx);
+  if (resolved !== DEFAULT_LOCALE && !fromUrl) {
+    return redirect(`/${resolved}${ctx.url.pathname}`);
+  }
+  await next();
+});
+```
+
+## Generating Localized URLs
+
+`reverse()` treats `undefined` and `""` for an optional param as "absent"
+and collapses the segment cleanly. The round-trip is symmetric with the
+matcher:
+
+```typescript
+ctx.reverse("menu.index", { locale: "" }); // → "/"
+ctx.reverse("menu.index", { locale: undefined }); // → "/"
+ctx.reverse("menu.index", { locale: "en" }); // → "/en"
+ctx.reverse("menu.category", { locale: "en", slug: "breads" }); // → "/en/c/breads"
+ctx.reverse("menu.category", { slug: "breads" }); // → "/c/breads"
+```
+
+If the active locale is the app default and your URL strategy hides it
+(`"en"` → `/`, others → `/<locale>`), normalize before calling reverse:
+
+```typescript
+const normalized = locale === DEFAULT_LOCALE ? undefined : locale;
+const href = ctx.reverse("menu.category", { locale: normalized, slug });
+```
+
+## react-intl Integration
+
+`react-intl` needs a `<IntlProvider>` wrapping the tree, with `locale`
+and `messages` props. The cleanest split: load messages on the server
+(handler or layout), pass them through to a client provider component.
+
+### Messages loader
+
+Load message bundles per locale. Keep them server-side so they stream
+through the RSC payload and don't bloat the client bundle:
+
+```typescript
+// lib/messages.ts
+import type { Locale } from "./locale";
+
+const loaders: Record<Locale, () => Promise<Record<string, string>>> = {
+  en: () => import("../messages/en.json").then((m) => m.default),
+  gb: () => import("../messages/gb.json").then((m) => m.default),
+  fr: () => import("../messages/fr.json").then((m) => m.default),
+};
+
+export async function loadMessages(locale: Locale) {
+  return loaders[locale]();
+}
+```
+
+### Server layout: hand off to the client provider
+
+```tsx
+// layouts/intl-layout.tsx (server component)
+import type { ReactNode } from "react";
+import { resolveLocale } from "../lib/locale";
+import { loadMessages } from "../lib/messages";
+import { IntlClientProvider } from "../components/intl-client-provider";
+
+export async function IntlLayout({
+  ctx,
+  children,
+}: {
+  ctx: any;
+  children: ReactNode;
+}) {
+  const locale = resolveLocale(ctx);
+  const messages = await loadMessages(locale);
+  return (
+    <IntlClientProvider locale={locale} messages={messages}>
+      {children}
+    </IntlClientProvider>
+  );
+}
+```
+
+### Client provider
+
+```tsx
+// components/intl-client-provider.tsx
+"use client";
+
+import { IntlProvider } from "react-intl";
+import type { ReactNode } from "react";
+
+export function IntlClientProvider({
+  locale,
+  messages,
+  children,
+}: {
+  locale: string;
+  messages: Record<string, string>;
+  children: ReactNode;
+}) {
+  return (
+    <IntlProvider
+      locale={locale}
+      defaultLocale="en"
+      messages={messages}
+      onError={(err) => {
+        if (err.code === "MISSING_TRANSLATION") return; // common, log only
+        console.error(err);
+      }}
+    >
+      {children}
+    </IntlProvider>
+  );
+}
+```
+
+### Mounting
+
+Wrap your localized routes with the layout:
+
+```typescript
+import { urls } from "@rangojs/router";
+import { IntlLayout } from "./layouts/intl-layout";
+import { menuRoutes } from "./menu";
+
+export const urlpatterns = urls(({ layout, include }) => [
+  layout(IntlLayout, () => [
+    include("/:locale?", menuRoutes, { name: "menu" }),
+  ]),
+]);
+```
+
+`<FormattedMessage>`, `useIntl()`, etc. work in any client component
+under the layout. Server components can use `formatjs`'s `createIntl()`
+directly with the same `messages` map for static text.
+
+## Common Pitfalls
+
+| Pitfall                                                       | Fix                                                                                    |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `ctx.params.locale === ""` returns `false`                    | Absent optionals are `undefined`, not `""`. Use `=== undefined` or `??`.               |
+| `ctx.params.locale ?? "en"` returns `""`                      | Pre-fix behavior. After the include-prefix fix this works correctly.                   |
+| Bare `/` 404s when mounted via `include("/:locale?", routes)` | Requires the all-optional pattern fix in `compilePattern` (shipped).                   |
+| Unknown locale (e.g. `/de`) matches as `locale: "de"`         | Add a constraint: `:locale(en\|gb\|fr)?`. Unknown values now 404.                      |
+| Reverse produces `//c/breads` for absent locale               | `reverse()` collapses `undefined`/`""` segments — should not happen. File a bug.       |
+| Locale switcher loses search params                           | Read `ctx.url.search` and pass to `reverse(..., undefined, parsedSearch)`.             |
+| Action middleware can't read `ctx.params.locale`              | Route middleware doesn't wrap action execution. Use global `router.use()` for actions. |
+
+## Cross-references
+
+- `/route` — optional URL param syntax and runtime contract
+- `/typesafety` — `RouteParams<"name">` typing for optionals
+- `/middleware` — global vs route middleware scope (matters for actions)
+- `/server-actions` — actions and the global-vs-route middleware boundary
+- `/links` — `ctx.reverse()` and locale-aware URL generation

package/skills/rango/SKILL.md

@@ -17,6 +17,7 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 | `/layout`               | Layouts that wrap child routes                                             |
 | `/loader`               | Data loaders with `createLoader()`                                         |
 | `/server-actions`       | Mutations with `"use server"`, useActionState, validation, revalidation    |
+| `/i18n`                 | Locale routing with `:locale?`, resolution chains, react-intl integration  |
 | `/middleware`           | Request processing and authentication                                      |
 | `/intercept`            | Modal/slide-over patterns for soft navigation                              |
 | `/parallel`             | Multi-column layouts and sidebars                                          |

package/skills/route/SKILL.md

@@ -33,6 +33,26 @@ urls(({ path }) => [
 ]);
 ```
 
+### Optional URL params at runtime
+
+Absent optional params are **omitted from `ctx.params`** — `ctx.params.<name>`
+reads as `undefined`, matching the `RouteParams<"name">` type
+(`{ query?: string }`). Use `??` to default and `=== undefined` to check
+absence:
+
+```typescript
+path("/search/:query?", (ctx) => {
+  const query = ctx.params.query ?? ""; // works — undefined coalesces
+  if (ctx.params.query === undefined) return <EmptySearch />;
+  return <Results query={ctx.params.query} />;
+}, { name: "search" });
+```
+
+For the common pattern of an optional locale prefix
+(`include("/:locale?", routes)`) and the wider react-intl integration —
+locale detection, fallback chains, URL generation with absent locale —
+see `/i18n`.
+
 ## Route Handler Patterns
 
 ### Component Function

package/skills/typesafety/SKILL.md

@@ -287,6 +287,12 @@ type SP = RouteSearchParams<"search">;
 type P = RouteParams<"blogPost">;
 // { slug: string }
 
+// Optional URL params (`:slug?`) resolve to `string | undefined`
+// because absent segments are omitted from `ctx.params` at runtime.
+type C = RouteParams<"checkout">;
+// { step?: string }
+// → ctx.params.step is `string | undefined`; use `?? "default"` to coalesce.
+
 // Use in component props
 interface SearchResultsProps {
   params: RouteSearchParams<"search">;

package/src/browser/react/use-params.ts

@@ -27,16 +27,19 @@ import { shallowEqual } from "./shallow-equal.js";
 // interface shapes pass the constraint — interfaces lack an implicit
 // index signature and would otherwise be rejected. The generic is a
 // shape annotation, not a runtime check; the body always returns the
-// underlying params map unchanged.
+// underlying params map unchanged. The default and selector input use
+// `string | undefined` because absent optional params are omitted from
+// the params record at runtime — the type must reflect that so callers
+// don't write `p.locale.length` and crash when the segment is absent.
 export function useParams<
-  T extends object = Record<string, string>,
+  T extends object = Record<string, string | undefined>,
 >(): Readonly<T>;
 export function useParams<T>(
-  selector: (params: Record<string, string>) => T,
+  selector: (params: Record<string, string | undefined>) => T,
 ): T;
 export function useParams<T>(
-  selector?: (params: Record<string, string>) => T,
-): T | Record<string, string> {
+  selector?: (params: Record<string, string | undefined>) => T,
+): T | Record<string, string | undefined> {
   const ctx = useContext(NavigationStoreContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {

package/src/build/route-trie.ts

@@ -20,7 +20,8 @@ export interface TrieLeaf {
   sp: string;
   /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
   a: string[];
-  /** Optional param names (absent params get empty string value) */
+  /** Optional param names declared on the route. Absent params are
+   * omitted from the matched params record (read as `undefined`). */
   op?: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;

package/src/reverse.ts

@@ -312,9 +312,10 @@ export function createReverse<TRoutes extends Record<string, string>>(
         /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
         (_, key, _constraint, optional) => {
           const value = params[key];
-          // Empty string is treated as omitted — the trie matcher fills
-          // unmatched optional params with "" (not undefined), so reverse
-          // must collapse those segments instead of leaving empty slots.
+          // The matcher omits absent optional params (so `value` is
+          // `undefined` here), but caller-supplied params or `getParams()`
+          // shapes may still pass `""` explicitly. Treat both as the
+          // absent form so the segment collapses cleanly.
           if (value === undefined || value === "") {
             hadOmittedOptional = true;
             return "";

package/src/router/handler-context.ts

@@ -176,9 +176,10 @@ export function createReverseFunction(
         /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
         (_, key) => {
           const value = effectiveParams[key];
-          // Empty string is treated as omitted — the trie matcher fills
-          // unmatched optional params with "" (not undefined), so reverse
-          // must collapse those segments instead of leaving empty slots.
+          // The matcher omits absent optional params (so `value` is
+          // `undefined` here), but caller-supplied params or `getParams()`
+          // shapes may still pass `""` explicitly. Treat both as the
+          // absent form so the segment collapses cleanly.
           if (value === undefined || value === "") {
             hadOmittedOptional = true;
             return "";

package/src/router/middleware-types.ts

@@ -53,11 +53,14 @@ export interface CookieOptions {
  * Context passed to middleware
  *
  * @template TEnv - Environment type (bindings, variables) - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware, Record<string, string> for global middleware)
+ * @template TParams - URL params type (typed for route middleware,
+ *   `Record<string, string | undefined>` for global middleware — absent
+ *   optional segments are omitted from the params record at runtime, so
+ *   the index signature must include `undefined`)
  */
 export interface MiddlewareContext<
   TEnv = any,
-  TParams = Record<string, string>,
+  TParams = Record<string, string | undefined>,
 > extends RequestScope<TEnv> {
   /** URL params extracted from route/middleware pattern */
   params: TParams;
@@ -149,7 +152,10 @@ export interface MiddlewareContext<
  * router.use((ctx, next) => {...}) // ctx is typed from router's TEnv
  * ```
  */
-export type MiddlewareFn<TEnv = any, TParams = Record<string, string>> = (
+export type MiddlewareFn<
+  TEnv = any,
+  TParams = Record<string, string | undefined>,
+> = (
   ctx: MiddlewareContext<TEnv, TParams>,
   next: () => Promise<Response>,
 ) => Response | void | Promise<Response | void>;
@@ -196,5 +202,8 @@ export interface MiddlewareCollectableEntry {
  */
 export interface CollectedMiddleware {
   handler: MiddlewareFn<any, any>;
+  // Internal shape only. The user-facing `MiddlewareContext.params` is
+  // typed `Record<string, string | undefined>` to reflect that absent
+  // optional segments are omitted from the params record at runtime.
   params: Record<string, string>;
 }

package/src/vite/utils/prerender-utils.ts

@@ -42,10 +42,11 @@ export function substituteRouteParams(
   let hadOmittedOptional = false;
 
   // First pass: substitute provided params.
-  // Empty string on an optional placeholder is treated as omitted (the trie
-  // matcher fills unmatched optionals with "" — letting the second pass
-  // strip them keeps slash cleanup consistent). Empty string on required
-  // `:key` or wildcard `*key` still substitutes, matching prior behaviour.
+  // Empty string on an optional placeholder is treated as omitted —
+  // caller-supplied params or `getParams()` shapes may pass `""` for an
+  // absent optional, so letting the second pass strip them keeps slash
+  // cleanup consistent. Empty string on required `:key` or wildcard
+  // `*key` still substitutes, matching prior behaviour.
   for (const [key, value] of Object.entries(params)) {
     const escaped = escapeRegExp(key);
     if (value === "") {