GitHub v1.3.1

Routing Reference

Reference

How file paths become routes: dynamic segments, path enumeration, URL conventions, navigation, the 404 convention and redirects.

Page exports, meta, server() and the page block contexts are specified in the Page API reference. This page covers routing only.

1. Page structure

A page is an HTML document in src/pages. It may contain exactly one Coralite page controller <script>, which exports page blocks or uses definePage. That script is removed from the output. Normal inline and external scripts are allowed alongside it and are never evaluated as page modules.

Pages that need no dynamic data or path enumeration can be pure HTML. Coralite processes static pages during the build without a controller script.

More than one page controller fails the page with CORALITE-E107. For literal script or markup regions, see coralite-ignore.

2. File-based routing

The file path below src/pages is the route:

  • pages/about.html becomes /about
  • pages/index.html becomes /
  • pages/blog/index.html becomes /blog

Subdirectories create nested paths. An index.html serves as the route for its directory.

3. Dynamic routes

Square brackets declare parameters in file or directory names. Values are extracted during routing and passed to page context through route.params.

  • pages/posts/[id].html becomes /posts/:id. /posts/123 yields route.params.id = '123'.
  • pages/[year]/[month].html becomes /:year/:month. /2025/03 yields both parameters.
  • pages/posts/[id]/index.html is the same route as pages/posts/[id].html.
  • pages/docs/[...slug].html is a catch-all. It matches /docs, /docs/a and /docs/a/b, with route.params.slug = 'a/b' for the last case.

When resolving a URL, static segments win over parameter segments, which win over catch-all segments, evaluated from left to right.

4. Enumeration via paths

Dynamic routes must enumerate the parameter combinations to build. Export a paths function returning an array of parameter objects. It receives { app } and may be asynchronous.

javascript
Code copied!
export async function paths () {
  const fs = await import('node:fs/promises')
  const files = await fs.readdir('src/data/posts')

  return files.map((file) => ({
    id: file.replace(/\.json$/, '')
  }))
}

Return parameter objects, not paths. Every declared parameter must be present, values must be strings, and extra keys are rejected with CORALITE-E402. Plugins can contribute additional paths by returning { paths } from onPageSet; duplicates across sources are a build error.

See the Page API reference for the full contract.

5. The route context key

route is available in page server(), getters, client and error boundaries:

typescript
Code copied!
interface CoraliteRoute {
  path: string
  pattern: string
  params: Record<string, string>
  dynamic: boolean
}
javascript
Code copied!
export const getters = {
  activeTab: ({ route }) => route.params.id || 'overview'
}

export function client ({ route }) {
  console.log('Page mounted at', route.path, route.params)
}

6. URL conventions

The cleanUrls option controls output filenames and route.path:

javascript
Code copied!
import { defineConfig } from 'coralite'

export default defineConfig({
  cleanUrls: true
})
  • cleanUrls: true (default): pages/about.html writes dist/about/index.html with route.path = '/about'.
  • cleanUrls: false: the same page writes dist/about.html with route.path = '/about.html'.
  • Nested index pages represent their directory. pages/docs/guide/index.html writes dist/docs/guide/index.html with route.path = '/docs/guide' under the default.
  • pages/docs/guide.html and pages/docs/guide/index.html produce the same route and cannot both exist.
  • The root page always writes dist/index.html with route.path = '/'.

7. Navigation

Navigation uses standard anchors and full document loads, animated with native View Transitions when enabled:

html
Code copied!
<nav>
  <a href="/">Home</a>
  <a href="/about/">About</a>
  <a href="/posts/123/">Read Post</a>
</nav>

Set viewTransitions: true in the project configuration to enable crossfades between full page loads. No client router is required.

8. 404 convention

A root pages/404.html compiles to dist/404.html with route.path = '/404', which static hosts use as the fallback page. Subdirectory 404 files are ordinary content pages.

9. Redirects

Host-level redirects are preferable in production. Pages can also emit a static redirect stub by returning __redirect from server():

javascript
Code copied!
export function server ({ route }) {
  return {
    __redirect: {
      to: '/docs/getting-started/',
      status: 301
    }
  }
}

The value is an object with to and an optional status of 301 or 302. Relative targets start with /; absolute HTTP and HTTPS targets are allowed. Coralite writes a small HTML stub with a meta refresh, canonical link and location.replace() fallback.

10. SPA router

The optional coralite/plugins/router turns the same static output into a client-side router. Every route is still a real file; the plugin intercepts same-origin links and swaps only the outlet.

See the SPA Router Guide for patterns and the Router Plugin Reference for configuration and the client API.