🪧 vite-plugin-kit-routes

vite-plugin-kit-routes automatically updates route references in SvelteKit projects, crucial for large applications where manual tracking of route changes is error-prone. It simplifies development by ensuring all route links are consistent and up-to-date, saving time and preventing broken links.

No more 🤞, now be confident ✅!

By default, no Configuration is required. Just Install the plugin, and use objects/functions available in your $lib/ROUTES.ts generated file (always in sync).

Note that this plugin is meant to be used with typescript today. If you want a JSDoc version of it, please open an issue.

Showcase

Examples

Simple route

<script lang="ts">
  import { route } from '$lib/ROUTES'
</script>

<!-- 🤞 before, hardcoded string, error prone -->
<a href="/terms-and-conditions">Terms</a>

<!-- ✅ after, typechecked route, no more errors -->
<a href={route('/terms-and-conditions')}>Terms</a>
<!--
   If you change location of `/terms-and-conditions/+page.svelte`:
     - the key '/terms-and-conditions' will not exist
     - `route` function will yell!
-->

Route with params

<script lang="ts">
  import { route } from '$lib/ROUTES'
</script>

<!-- 🤞 before, hardcoded string, error prone -->
<a href="/site/123">Go to site</a>

<!-- ✅ after, typechecked route, no more errors -->
<a href={route('/site/[id]', { id: 123 })}>Go to site</a>

Route with params & search params

<script lang="ts">
  import { route } from '$lib/ROUTES'
</script>

<!-- 🤞 before, hardcoded string, error prone -->
<a href="/site/123?limit=3">Go to site</a>

<!-- ✅ after, typechecked route, no more errors -->
<a href={route('/site/[id]', { id: 123, limit: 3 })}>Go to site</a>

As we can’t guess search_params from the route, you must explicitly specify them like this:

import { kitRoutes } from 'vite-plugin-kit-routes'

import type { KIT_ROUTES } from '$lib/ROUTES.js'

export default defineConfig({
  plugins: [
    kitRoutes<KIT_ROUTES>({
      PAGES: {
        '/site/[id]': {
          explicit_search_params: {
            limit: { type: 'number' },
          },
        },
      },
    }),
  ],
})

Actions

<script lang="ts">
  import { enhance } from '$app/forms'
  import { page } from '$app/stores'

  import { route } from '$lib/ROUTES'

  const id = $page.params.id

  // 🤞 before, hardcoded string, error prone
  const action_hope = `/site/${id}?/send`

  // ✅ after, typechecked route, no more errors
  const action = route('send /site/[id]', { id })
</script>

<form method="POST" use:enhance {action}>
  <button>Check</button>
</form>

External links

<script lang="ts">
  import { route } from '$lib/ROUTES'
</script>

<!-- 🤞 before, hardcoded string, error prone -->
<a href="https://bsky.app/profile/jyc.dev">Bluesky</a>

<!-- ✅ after, typechecked route, no more errors -->
<a href={route('bluesky')}>Bluesky</a>

Here is the vite.config.ts config for it:

plugins: [
    // ...
    kitRoutes({
      LINKS: {
        bluesky: 'https://bsky.app/profile/jyc.dev',
      }
    }),
],

Like this, you are able to have a central place to manage all your external links.

External links with params

<script lang="ts">
  import { route } from '$lib/ROUTES'
</script>

<!-- 🤞 before, hardcoded string, error prone -->
<img src="https://www.gravatar.com/avatar/jycouet?s=20&d=identicon" alt="logo" />

<!-- ✅ after, typechecked route, no more errors -->
<img src={route('gravatar', { str: 'jycouet', s: 20 })} alt="logo" />

Here is the vite.config.ts config for it:

plugins: [
    // ...
    kitRoutes({
      LINKS: {
        gravatar: {
          href: 'https://www.gravatar.com/avatar/[str]',
          params: {
            str: { type: 'string' },
          },
          explicit_search_params: {
            s: { type: 'number', default: 75 },
            d: { type: '"retro" | "identicon"', default: 'identicon' },
          },
        },
      }
    }),
],

* You can add a lot of configs to specify search params, types, …

Installation

npm i -D vite-plugin-kit-routes

Demo

Local

npm create kitql@latest --template kit-routes

Configuration

Add the plugin like this:

import { sveltekit } from '@sveltejs/kit/vite'
import { kitRoutes } from 'vite-plugin-kit-routes'

/** @type {import('vite').UserConfig} */
export default config = {
  plugins: [
    sveltekit(),
    // ✅ Add the plugin
    kitRoutes(),
  ],
}

It will generate a file ./src/lib/ROUTES.ts at the start of your dev server & any update of any of your +page.svelte | +server.ts | +page.server.ts.

CLI Command

The plugin provides a CLI command to check and sync routes configuration without running a Vite build:

npm exec kit-routes sync

This is particularly useful for:

CI/CD pipelines where you want to verify routes without:
- a full vite build
- commiting ./src/lib/ROUTES.ts
Pre-commit hooks to ensure route integrity
Quick route validation during development

You can specify a custom config file using the --config option:

npm exec kit-routes sync --config ./path/to/config.ts#named_export

If no named export is specified, it will use the default export. The config object should follow this structure:

import { kitRoutes, type Options } from 'vite-plugin-kit-routes'

import type { KIT_ROUTES } from '$lib/ROUTES'

export const _kitRoutesConfig: Options<KIT_ROUTES> = {
  // ...
}

This command provides a lightweight way to validate your routes configuration without the overhead of a full Vite build process.