sveltekit-lib-routes

Motivation

SvelteKit's filesystem-based routing and its approach to SvelteKit packages allow developers to expose src/lib for components and utilities. However, packages that need to provide pre-configured routes, such as those handling authentication, face limitations in this system.

Current status

While the community has discussed solutions, no official proposal has been adopted

• https://stackoverflow.com/questions/71728342/creating-sveltekit-library-with-reusable-routes
• https://github.com/sveltejs/kit/issues/8896
• https://github.com/sveltejs/kit/discussions/5880

Better than nothing proposal

This project introduces a Vite plugin that allows developers to copy routes from a package library's src/routes to a user's src/routes directory, offering a workaround for the current limitations.

For Package Developers

When creating a package with reusable routes:

• Define routes in src/routes

/account
└── +page.svelte
/users
├── +layout.svelte
├── +page.svelte
├── /[userId]
│   └── +page.svelte
└── /add
    └── +page.svelte
/auth
├── /login
│   ├── +page.svelte
│   └── +page.server.ts
├── /logout
│   ├── +page.svelte
│   └── +page.server.ts
└── /callback
    ├── +page.svelte
    └── +page.server.ts

• Expose routes through src/lib/routes.ts

export const routes = {
  users: "src/routes/users",
  account: "src/routes/account",
  auth: "src/routes/auth",
};

• Configure exports & files at package.json

{
  "name": "lib-routes-users-example",
  "...": "...",
  "exports": {
    "...": {},
    // export src/lib/routes.ts
    "./routes": {
      "types": "./dist/routes.d.ts",
      "default": "./dist/routes.js"
    }
  },
  // sveltekit lib only adds lib to files,
  // include src/routes in published package
  "files": ["...", "src/routes"]
}

• Publish the package

For Consumers of the Package

To use the routes provided by a package

• Install the vite plugin in vite.config.ts

import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";
import { svelteKitLibRoutes } from "sveltekit-lib-routes";

export default defineConfig({
  plugins: [sveltekit(), svelteKitLibRoutes()],
});

• Install the Package containing the routes (ex. lib-routes-users-example).
• Create a Route Directory (ex. src/routes/users) and add _sveltekit-lib-route.js

import { routes } from "lib-routes-users-example/routes";

export default {
  from: "lib-routes-users-example/routes",
  import: routes.users,
  to: import.meta.dirname,
};

• Route handling
  • The plugin will copy the specified routes from the package into the user's src/routes directory.
  • Any existing files, except _sveltekit-lib-route.js, will be deleted during this process.

Drawbacks

• Component Imports: Routes exposed by package libraries cannot use $lib/* as it refers to the user's $lib directory, not the package's.
• File Stability: Large or frequently changing files in the src/routes of a package can lead to excessive updates in the user's project.
• Customizability: Users cannot easily customize routes or components within them, as changes will be overwritten by the Vite plugin.
• URL Path Mapping: Within routes, paths should avoid hardcoding. Use $page.url.pathname from src/routes/$route/+layout.svelte get the /$route path. If you use this in a child route (ex. src/routes/$route/$subroute/+page.svelte), $page.url.pathname would reflect the full nested path, such as /$route/$subroute.