Pages and routing

Veryfront uses file-system based routing. Folders and files under app/ (or pages/) define routes; layouts compose down the tree; brackets in path segments mark dynamic params. Examples below use the default app router. Set router: "pages" in veryfront.config.ts to switch to the pages router.

Prerequisites

A project created with veryfront init (see Create project).
The dev server is the easiest way to test routes: veryfront dev.

Router equivalents

Veryfront supports both router styles. The main difference is file shape:

URL / capability	App router	Pages router
`/`	`app/page.tsx`	`pages/index.tsx`
`/about`	`app/about/page.tsx`	`pages/about.tsx`
`/blog/:slug`	`app/blog/[slug]/page.tsx`	`pages/blog/[slug].tsx`
`/api/users`	`app/api/users/route.ts`	`pages/api/users.ts`
Root layout	`app/layout.tsx`	`pages/layout.tsx`

Use the app router when you want the newer directory-per-route shape. Use the pages router when you want the flatter file-per-route layout.

Basic pages

app/
  page.tsx          # /
  about/page.tsx    # /about
  blog/page.tsx     # /blog

A page exports a default React component:

// app/page.tsx
export default function Home() {
  return <h1>Welcome</h1>;
}

Run veryfront dev and open http://localhost:3000. The page should render Welcome.

Layouts

Layouts wrap pages and persist across navigation. Create layout.tsx at any level:

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

Nested layouts compose automatically:

app/
  layout.tsx            # Wraps everything
  page.tsx              # /
  dashboard/
    layout.tsx          # Wraps dashboard pages
    page.tsx            # /dashboard
    settings/page.tsx   # /dashboard/settings

/dashboard/settings renders inside both the root layout and the dashboard layout. layout.tsx and the other supported layout.* extensions are reserved layout metadata at every directory level in both routers. They wrap descendant pages and never create a /layout route.

Overriding or disabling a layout

A page can opt out of the nested layout chain, or replace it with a named layout. On .md/.mdx pages, set layout in the frontmatter:

---
title: Standalone
layout: false
---

# Renders with no layout at all

On .tsx/.jsx/.ts/.js pages, export a layout constant:

// app/standalone/page.tsx
export const layout = false;

export default function StandalonePage() {
  return <div>Renders with no layout at all</div>;
}

You can also put the same value in an exported frontmatter object:

export const frontmatter = { layout: "marketing" };

The frontmatter.layout property accepts the same false and named-layout values as the direct layout export. Supported values in both cases:

layout: false renders the page bare: no ancestor layouts, no default layout.
layout: "name" replaces the entire nested chain with the named layout. Ancestor layouts (including the root layout) are not applied.

An explicit project path with a file extension, such as @/layouts/custom.tsx or @components/CustomLayout.tsx, loads that file directly, without falling back to convention-based discovery. Plain names resolve from, in order:

layouts/<name>.{tsx,mdx,md,jsx,ts,js} - anything in layouts/ is a layout.
components/<Name>Layout.* or components/Layout.*.

A project-wide default can also be set with layout in veryfront.config.ts; a page’s layout frontmatter or export always wins over the config default.

Dynamic routes

Use brackets for dynamic segments:

app/
  blog/[slug]/page.tsx      # /blog/:slug
  users/[id]/page.tsx       # /users/:id

Access params via the usePageContext hook:

// app/blog/[slug]/page.tsx
"use client";
import { usePageContext } from "veryfront/context";

export default function BlogPost() {
  const { params } = usePageContext();
  return <h1>Post: {params.slug}</h1>;
}

Open http://localhost:3000/blog/hello. The page should render Post: hello.

Catch-all routes

Use [...segments] to match multiple path segments:

app/docs/[...segments]/page.tsx   # /docs/a, /docs/a/b, /docs/a/b/c

MDX pages

Rename any page to .mdx to write content in Markdown with JSX:

{/* app/about/page.mdx */}

# About Us

We build tools for developers.

<TeamGrid members={team} />

MDX pages support frontmatter:

---
title: "About"
description: "Learn about the team."
---

# {frontmatter.title}

Access frontmatter from components using usePageContext() from veryfront/context:

"use client";
import { usePageContext } from "veryfront/context";

function PageTitle() {
  const { frontmatter } = usePageContext();
  return <h1>{frontmatter.title}</h1>;
}

Lazy JSX imports

Veryfront bounds the on-disk JSX transform cache. A loaded MDX module keeps a recovery snapshot for its literal dynamic JSX imports, so a delayed import can restore an evicted artifact. Recovery uses the original transformed code, not the latest source at that path. Load the updated MDX module to use changed source. Recovery snapshots have a combined limit of 2 MiB per MDX module. Recovery follows the same cache capacity limits as initial compilation and can fail when active artifacts occupy the available capacity. Recovery snapshots share a process-wide cache with a 16 MiB storage budget and a 256-entry limit. Identical transformed sources share one snapshot. Least-recently used snapshots are evicted when either limit is reached. Existing on-disk artifacts remain usable. If both an artifact and its snapshot are evicted, the delayed import fails. Reload the MDX module to capture its recovery data again. Temporary parent modules use the same disk quota and maintenance sweeps as JSX artifacts. If immediate cleanup fails, a later sweep retires the file, including after a process restart. Active evaluations keep their parent artifacts pinned. During a rolling upgrade, automatic cleanup preserves prior-version JSX artifacts. Their timestamps cannot prove that older runtimes have stopped using them. Before you remove legacy artifacts, you must ensure all runtimes using those versions have drained and cannot resume. Legacy files remain outside the current version’s quota and require operator-managed cleanup; total disk usage across versions is not bounded by the current version’s quota.

Override rendered MDX elements

Wrap an MDX page or layout with MDXProvider to replace generated elements:

import type React from "react";
import { MDXProvider } from "veryfront/mdx";

const docsComponents = {
  h1: (props: React.ComponentProps<"h1">) => <h1 className="docs-title" {...props} />,
  a: (props: React.ComponentProps<"a">) => <a {...props} rel="noreferrer" />,
};

export default function DocsLayout({ children }: { children: React.ReactNode }) {
  return <MDXProvider components={docsComponents}>{children}</MDXProvider>;
}

Nested providers inherit entries from outer providers. A nearer provider wins for duplicate keys. Call useMDXComponents(localOverrides) when a component needs the effective map; local entries take final precedence. MDXProvider supplies application-owned React components to already compiled MDX. It does not compile or sanitize arbitrary strings. Render runtime Markdown strings with veryfront/markdown.

Reading server data from a layout or nested component

A page’s getServerData props are passed to the page component. To read them from a layout or a deeply-nested component without prop-drilling, use usePageContext().data:

import { usePageContext } from "veryfront/context";

function Greeting() {
  const { data } = usePageContext();
  return <p>{data.greeting as string}</p>;
}

data is the object your page returned as getServerData’s props. It is populated identically on the server render, in the hydration markup, and after client-side navigation. A page without getServerData sees an empty object.

Client components

By default, components render on the server. Add 'use client' to make a component interactive:

"use client";

import { useState } from "react";

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

Use the Link component for client-side navigation:

import { Link } from "veryfront/router";

export default function Nav() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
    </nav>
  );
}

Veryfront can prefetch eligible internal links before navigation. Use prefetch={false} when a link must not prefetch. Programmatic navigation:

"use client";

import { useRouter } from "veryfront/router";

export default function LoginForm() {
  const router = useRouter();

  async function handleSubmit() {
    await login();
    router.push("/dashboard");
  }

  return <form onSubmit={handleSubmit}>...</form>;
}

Reading the live location

useRouter() is the single hook for location and navigation. Its pathname, query, and params update reactively on client-side navigation:

"use client";

import { useRouter } from "veryfront/router";

export default function Filters() {
  const { pathname, query, params } = useRouter();
  return <p>{pathname} · {params.category} · sort: {query.sort ?? "none"}</p>;
}

By default a query-only navigation refetches the page so server data that depends on the query is never shown stale. If a page’s query is purely client-side state (tabs, filters), opt into the soft fast path, updating the URL and re-rendering without a refetch, with the router’s shouldRevalidate option.

Verify it worked

Start the dev server and request each page you added:

veryfront dev
curl -I http://localhost:3000/
curl -I http://localhost:3000/about
curl -I http://localhost:3000/blog/hello

Each request should return HTTP/1.1 200 OK. Visit the same URLs in a browser to confirm the React component renders without console errors.

Getting Started

Concepts

Guides

API Reference

Prerequisites

Router equivalents

Basic pages

Layouts

Overriding or disabling a layout

Dynamic routes

Catch-all routes

MDX pages

Lazy JSX imports

Override rendered MDX elements

Reading server data from a layout or nested component

Client components

Navigation

Reading the live location

Verify it worked

​Prerequisites

​Router equivalents

​Basic pages

​Layouts

​Overriding or disabling a layout

​Dynamic routes

​Catch-all routes

​MDX pages

​Lazy JSX imports

​Override rendered MDX elements

​Reading server data from a layout or nested component

​Client components

​Navigation

​Reading the live location

​Verify it worked

Prerequisites

Router equivalents

Basic pages

Layouts

Overriding or disabling a layout

Dynamic routes

Catch-all routes

MDX pages

Lazy JSX imports

Override rendered MDX elements

Reading server data from a layout or nested component

Client components

Navigation

Reading the live location

Verify it worked