Skip to content

Free MIT template · Day 6 of 365

You're looking at a demo. Download the built static files (drop on any host) or grab the full source to customize.

↓ Download static ↓ Source (Astro) All 365 →Hire me →

# Configuration

routekit doesn’t require a config file — most apps configure inline at the `createRouter()` call. The optional `routekit.config.ts` is for build-time tooling (e.g. CLI for generating types) and is read by the future `routekit codegen` command.

Note

The CLI is on the roadmap, not yet shipped. The schema below is forward-compatible — if you set up `routekit.config.ts` today it’ll be honored when the CLI lands. Until then, all of these options can be passed to `createRouter()` directly.

## Schema

routekit.config.ts

    import { defineConfig } from 'routekit/config';
    export default defineConfig({  base: '/',  hash: false,  scrollBehavior: 'auto',  routesDir: './src/routes',  output: {    types: './src/routekit.types.ts',  },  build: {    splitting: true,    chunkNamePattern: 'pages/[name]-[hash]',  },});

## Options

### `base`

type: `string` default: `'/'`

Base path for the SPA. If your app is served at `example.com/docs/`, set `base: '/docs/'`. Routes match relative to this prefix.

### `hash`

type: `boolean` default: `false`

Use `#`-based URLs (`/#/posts/42`) instead of HTML5 history (`/posts/42`). Required when deploying to a host that can’t fall back to `index.html` for unknown URLs (e.g. some S3 setups).

### `scrollBehavior`

type: `'auto' | 'instant' | 'smooth' | 'manual'` default: `'auto'`

What happens to scroll position on navigation:

Value | On forward (`go`) | On back/forward button
--- | --- | ---
`'auto'` | scroll to top, instant | restore position
`'instant'` | scroll to top, instant | scroll to top, instant
`'smooth'` | scroll to top, smooth | restore position
`'manual'` | nothing — you control it | nothing

`'manual'` is what you want if your renderer (React, Solid) does its own scroll restoration via, e.g., a `<Link preserveScroll>` prop pattern.

### `routesDir`

type: `string` default: `'./src/routes'`

Directory the future codegen CLI scans for `.tsx`/`.ts` files to build the route table. Ignored at runtime.

### `output.types`

type: `string` default: `'./src/routekit.types.ts'`

Where the codegen CLI writes the generated `RouteParams<T>` map. Ignored at runtime.

### `build.splitting`

type: `boolean` default: `true`

Whether `() => import(...)` handlers should hint code-splitting to bundlers via the `webpackChunkName` magic comment. Affects build output, not runtime behavior. Almost always leave on.

### `build.chunkNamePattern`

type: `string` default: `'pages/[name]-[hash]'`

Pattern for emitted chunk file names. `[name]` resolves from the import path’s last segment; `[hash]` is your bundler’s content hash.

## Loading the config

The config is read once at codegen time. There’s no runtime config loader; nothing in routekit reads `routekit.config.ts` during page navigation.

If you want to share values between the config and runtime, export them from a separate file and import in both places:

src/router-config.ts

    export const BASE_PATH = '/docs/';
    // routekit.config.tsimport { defineConfig } from 'routekit/config';import { BASE_PATH } from './src/router-config';export default defineConfig({ base: BASE_PATH });
    // src/main.tsimport { createRouter } from 'routekit';import { BASE_PATH } from './router-config';const router = createRouter(routes, { base: BASE_PATH });

This pattern keeps “single source of truth” honest without coupling the runtime bundle to the config file.