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.ts
import { defineConfig } from 'routekit/config';
import { BASE_PATH } from './src/router-config';
export default defineConfig({ base: BASE_PATH });

// src/main.ts
import { 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.