Page routing

Page Router

What is the Page Router?

Val's page router allows you to create dynamic routes based on your content. By using s.router(nextAppRouter, schema), you can automatically generate pages for each entry in your content record.

Basic Setup

The documentation you're reading right now is built using Val's page router. Here's how it's structured:

// app/(main)/docs/[[...slug]]/page.val.ts
import { c, nextAppRouter, s } from "@/val.config";
import { docsSchema } from "./docsSchema.val";

export default c.define(
  "/app/(main)/docs/[[...slug]]/page.val.ts",
  s.router(nextAppRouter, docsSchema),
  {
    "/docs": {
      title: "Overview",
      sections: [/* ... */],
    },
    "/docs/init": {
      title: "Installation",
      sections: [/* ... */],
    },
    "/docs/getting-started": {
      title: "Getting started",
      sections: [/* ... */],
    },
    // ... more routes
  },
);

How It Works

The router maps keys in your record to URL paths. Each key becomes a route, and Next.js will generate the corresponding pages automatically.

// Use s.route() to create type-safe links
const navigationSchema = s.object({
  links: s.array(
    s.object({
      label: s.string(),
      href: s.route(), // Validated against all router modules
    })
  ),
});

export default c.define("/content/navigation.val.ts", navigationSchema, {
  links: [
    { label: "Overview", href: "/docs" },
    { label: "Installation", href: "/docs/init" },
    { label: "Getting Started", href: "/docs/getting-started" },
    // Val validates these are valid routes!
  ],
});

Rendering Routes in Server Components

In server components, use fetchValRoute to fetch route content based on URL parameters. This function is async and returns the content for the matching route, or null if no route matches.

// app/(main)/privacy/page.tsx - Server Component
import { fetchValRoute } from "@/val/val.rsc";
import pageVal from "./page.val";
import { notFound } from "next/navigation";

export default async function PrivacyPage({ params }: { params: unknown }) {
  const page = await fetchValRoute(pageVal, params);
  if (!page) {
    return notFound();
  }
  return (
    <div>
      <h1>{page.title}</h1>
      {/* Render your content */}
    </div>
  );
}

Rendering Routes in Client Components

In client components, use the useValRoute hook to access route content. This hook takes the Val module and the params Promise from Next.js and returns the content for the matching route.

// app/(main)/docs/[[...slug]]/page.tsx - Client Component
"use client";
import { useVal, useValRoute } from "@/val/val.client";
import pageVal from "./page.val";
import { notFound } from "next/navigation";

export default function DocsPage({
  params,
}: {
  params: Promise<{ slug: string[] }>;
}) {
  const docsData = useValRoute(pageVal, params);

  if (!docsData) {
    return notFound();
  }
  return (
    <div>
      <h1>{docsData.title}</h1>
      {/* Render your content */}
    </div>
  );
}

Choosing Between Server and Client Components

Use server components (fetchValRoute) when:

  • The page content is mostly static

  • You want better SEO and initial page load performance

  • You don't need client-side interactivity for the content

Use client components (useValRoute) when:

  • You need client-side interactivity

  • The page has other client-side state or effects