Routing 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.htmlbecomes/aboutpages/index.htmlbecomes/pages/blog/index.htmlbecomes/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].htmlbecomes/posts/:id./posts/123yieldsroute.params.id = '123'.pages/[year]/[month].htmlbecomes/:year/:month./2025/03yields both parameters.pages/posts/[id]/index.htmlis the same route aspages/posts/[id].html.pages/docs/[...slug].htmlis a catch-all. It matches/docs,/docs/aand/docs/a/b, withroute.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.
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:
interface CoraliteRoute {
path: string
pattern: string
params: Record<string, string>
dynamic: boolean
}
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:
import { defineConfig } from 'coralite'
export default defineConfig({
cleanUrls: true
})
cleanUrls: true(default):pages/about.htmlwritesdist/about/index.htmlwithroute.path = '/about'.cleanUrls: false: the same page writesdist/about.htmlwithroute.path = '/about.html'.- Nested index pages represent their directory.
pages/docs/guide/index.htmlwritesdist/docs/guide/index.htmlwithroute.path = '/docs/guide'under the default. pages/docs/guide.htmlandpages/docs/guide/index.htmlproduce the same route and cannot both exist.- The root page always writes
dist/index.htmlwithroute.path = '/'.
7. Navigation
Navigation uses standard anchors and full document loads, animated with native View Transitions when enabled:
<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():
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.