Skip to content

Multiple frontends ​

One app can serve more than one SvelteKit project, such as a public site at / and an admin area under /admin. Each frontend has its own build, its own pages and its own fallback page, and they all share the one Ktor API.

It is opt-in: an app that declares no second frontend works exactly as before.

How it works ​

  • The main frontend is the one you already have. It keeps every path that no other frontend claims.
  • Each other frontend gets a path prefix, such as /admin. A request goes to the frontend with the longest prefix that covers it, so /admin/reports can be a frontend of its own inside /admin. A prefix covers whole path segments only: /admin covers /admin and /admin/users, but not /administrator.
  • The API stays global. apiPrefixes are checked first, for every frontend, and a frontend may not sit inside an API prefix.
  • Each frontend has its own build and manifest. In the JAR they live under ktor-svelte/frontends/<name>/, next to the main frontend's ktor-svelte/. The name is the prefix without its slashes, such as admin for /admin and admin-reports for /admin/reports.
  • Each frontend answers like the main one: its pages, its _app files with the same cache headers, compression and Content-Security-Policy, its own spaFallback and notFoundPage, and redirects that stay inside its prefix.

On the server ​

kotlin
install(Svelte) {
    frontend("/admin") {
        spaFallback = "200.html"
        notFoundPage = "404.html"
    }
}
SettingDefaultWhat it does
sourceSvelteSource.ClasspathWhere the build is: from the classpath under ktor-svelte/frontends/<name>/, or SvelteSource.Directory(path)
spaFallback"200.html"The page for paths that have no page of their own, inside this frontend
notFoundPage"404.html"The page for missing paths, when there is no fallback
paramRoutes(...)noneLike the main paramRoutes, with paths relative to the prefix
devUrlset by svelteDevAllThe Vite of this frontend in development. Without one, development serves its build
generateTsOutputsrc/lib/api in the frontend's folderWhere its copy of the typed client goes, when generateTs is on

Outside development, a frontend without a build stops the start, like the main frontend does. In development it is a warning.

In Gradle ​

Declare the frontend in build.gradle.kts, under the same name the server derives from its prefix:

kotlin
svelte {
    frontend("admin") {
        frontendDir = layout.projectDirectory.dir("admin")
    }
}
SettingDefaultWhat it does
frontendDirthe folder named like the frontend, such as adminDirectory of its SvelteKit project
outputDiroutputDir of the main frontend, "build"Adapter output, a folder inside its frontendDir
buildScriptbuildScript of the main frontend, "build"package.json script that builds it
basePath"/" and the name, such as "/admin"The path prefix it is built for. Set it for a nested prefix, such as "/admin/reports" for the frontend admin-reports
devPortthe next port after dev.port, such as 5174Port of its Vite

Each frontend gets its own tasks, named after it: svelteInstallAdmin, svelteBuildAdmin and svelteBundleAdmin. They run with the main frontend's tasks when the JAR is built, and svelteBundleAdmin puts the build under ktor-svelte/frontends/admin/, where install(Svelte) { frontend("/admin") } reads it. The settings that are not per frontend, such as packageManager, bunVersion, precompress and includeSourceMaps, apply to every frontend.

When no page of the build loads its files from /admin/_app/, svelteBundleAdmin warns: the base path is missing from the frontend's Vite config.

The typed client ​

With generateTs = true, every frontend gets the same generated client as the main one, in its own src/lib/api, so the admin pages call the API with the same types. The frontend's folder comes from Gradle (svelteDevAll, run and svelteGenerateTs pass it to the app); without Gradle it is the folder named like the frontend, or set generateTsOutput.

In development ​

svelteDevAll starts one Vite per frontend, each on its own devPort, and tells the app where they are, so /admin shows the admin project with hot reload while / shows the main one. Through the app's port, the dev panel and the browser logs work on every frontend.

Vite serves a project with a base path under that path, so the app forwards /admin/... to the admin Vite as it is. To run one frontend's Vite on its own, use svelteDevAdmin, and give the app its address with devUrl.

In the frontend project ​

A second frontend is a SvelteKit project with adapter-static like the main one, built for its prefix. Set the base path in its Vite config, so its links and its _app files carry the prefix:

ts
import { sveltekit } from '@sveltejs/kit/vite';
import adapter from '@sveltejs/adapter-static';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [sveltekit({ adapter: adapter({ fallback: '200.html', precompress: true }), paths: { base: '/admin' } })],
    server: { hmr: { clientPort: 5174, protocol: 'ws' } }
});

Links inside it go through resolve() from $app/paths, as SvelteKit asks for any app with a base path. The hmr line points hot reload at the frontend's own Vite, on its devPort.

  • SvelteKit writes asset paths relative to the page, and for the start page of a base path it counts on a slash at the end. So the app answers /admin with a redirect to /admin/, and the start page loads its files from /admin/_app/.
  • A link from one frontend into another, such as from the public site to /admin, needs data-sveltekit-reload, so the browser loads the other app instead of SvelteKit looking for a route of its own.
  • A prerendered page with such a link makes the prerender crawler visit /admin in the wrong app. Let it pass with prerender: { handleHttpError } in the main frontend's sveltekit() options, as the example does.

Example ​

examples/two-frontends is a public site and an admin area under /admin, each with a page that calls the API through its own generated client. Its browser tests open both in the packaged JAR and check where their files come from, the navigation inside each frontend, the links between them and the fallback pages, and a development mode test runs svelteDevAll with two Vite servers.

Limits ​

These parts of ktor-svelte know only the main frontend for now:

  • The sitemap and robots.txt, the default favicon and the language redirect of i18n.
  • The startup warning about Ktor routes that hide a page, the route table and the route map of the dev panel.
  • The build fingerprint in X-Ktor-Svelte-Build and in the status endpoint.
  • svelteVerifyTs checks the main frontend's client only.
  • The typed page routes (FrontendRoutes) and the generated Kotlin of libraries { } come from the main frontend.
  • In Gradle, libraries { } with svelteSync, the svelteVerify... checks, svelteVerifyLeaks, svelteCheck and the other frontend tools work on the main frontend. Another frontend is installed, built and packaged; add what it needs to its own package.json.

Documentation for ktor-svelte 1.4.0. Released under the Apache 2.0 license.