Options and files

The options of framework(), and the files src/routes/ may hold. How to use each is covered in the guides.

On this page

framework

Import from @k8ordo/static

The Vite plugin that builds the application into files. It returns an array that includes React’s plugin and the RSC pipeline; put it in plugins as it is.

Copy code

framework(options?: StaticOptions): PluginOption[]

Parameters

options.routesDirstring: The route directory, relative to the project root; src/routes by default. The generated files still go to .k8ordo/.
options.paths(patterns: readonly string[]) => readonly string[] | Promise<readonly string[]>: A function that returns the URLs of routes with parameters. It receives the patterns that need values, and returns an array of URLs or a promise of one, without Vite’s base.
options.sitestring: The origin the site is served from, such as https://example.com. With it the build writes sitemap.xml too, and a route.ts sees it as the origin of request.url.
options.cspReadonly<Record<string, readonly string[]>>: The Content-Security-Policy every page carries, as an array of sources per directive. The build adds the hashes of the framework’s scripts and writes it into a <meta>.

Returns

PluginOption[] — An array of Vite plugins.

Caveats

framework() throws as it is called when csp holds a directive a <meta> ignores, or 'strict-dynamic'.

vite.config.ts

Copy code

import { framework } from '@k8ordo/static';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    framework({
      paths: () => ['/products/1', '/products/2'],
      site: 'https://example.com',
    }),
  ],
});

Route files

The files a directory under src/routes/ may hold, what each exports and what it receives. Anything else goes under a directory whose name starts with _.

`page.tsx`

Default export: the page component that answers its directory’s URL. It receives params and pathname.
paramsSchema: a schema that validates the parameters, anything implementing Standard Schema. Optional.

`layout.tsx`

Default export: a component that wraps what renders below it, received as children. It also receives params and pathname, with params typed as strings.
paramsSchema: runs for every page below, before the page’s own.

`not-found.tsx`

Default export: a component that answers any URL below its directory that no route matched. It receives params and pathname, and the params are unvalidated strings.
In this mode it is written as 404.html, so an application may hold only one.

`error.tsx`

A 'use client' file.
Default export: a component receiving error and reset, rendered in place of what is below it when that throws. It receives no params.

`loading.tsx`

Default export: a component with no props, rendered as the <Suspense> fallback while the page below it loads.

`redirect.ts`

Default export: the target as a string, or { to, permanent }. to is a pattern of the route table, filled with the matched parameters.
In this mode it is written as a page that sends the visitor on.

`route.ts`

Exports named after methods, such as GET and POST: functions that receive { request, params } and return a Response.
paramsSchema: validates the parameters, as a page’s does.
In this mode it may export GET only, and what that answers is written as the file at its URL.

`guard.ts`

Not in this mode: the build and vite dev both refuse it by name.

What route files use from `@k8ordo/router`

The types and functions route files use come from @k8ordo/router, not from the mode package, so a page reads the same under either mode.

PageProps<pattern>: the props a page receives.
LayoutProps<pattern>: the props a layout receives.
ErrorProps: the props an error.tsx receives.
RouteContext<pattern>: what a route.ts function receives.
notFound(): thrown from a page, it has the nearest not-found.tsx answer under a 404.
href(): builds a URL typed against the route table.
usePathname() and useMatch(): hooks that read the current URL in the browser.
usePendingPathname(): a hook that reads where a navigation under way is going.

framework

Parameters

Returns

Caveats

Route files

page.tsx

layout.tsx

not-found.tsx

error.tsx

loading.tsx

redirect.ts

route.ts

guard.ts

What route files use from @k8ordo/router