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/reportscan be a frontend of its own inside/admin. A prefix covers whole path segments only:/admincovers/adminand/admin/users, but not/administrator. - The API stays global.
apiPrefixesare 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'sktor-svelte/. The name is the prefix without its slashes, such asadminfor/adminandadmin-reportsfor/admin/reports. - Each frontend answers like the main one: its pages, its
_appfiles with the same cache headers, compression and Content-Security-Policy, its ownspaFallbackandnotFoundPage, and redirects that stay inside its prefix.
On the server
install(Svelte) {
frontend("/admin") {
spaFallback = "200.html"
notFoundPage = "404.html"
}
}| Setting | Default | What it does |
|---|---|---|
source | SvelteSource.Classpath | Where 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(...) | none | Like the main paramRoutes, with paths relative to the prefix |
devUrl | set by svelteDevAll | The Vite of this frontend in development. Without one, development serves its build |
generateTsOutput | src/lib/api in the frontend's folder | Where 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:
svelte {
frontend("admin") {
frontendDir = layout.projectDirectory.dir("admin")
}
}| Setting | Default | What it does |
|---|---|---|
frontendDir | the folder named like the frontend, such as admin | Directory of its SvelteKit project |
outputDir | outputDir of the main frontend, "build" | Adapter output, a folder inside its frontendDir |
buildScript | buildScript 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 |
devPort | the next port after dev.port, such as 5174 | Port 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:
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
/adminwith 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, needsdata-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
/adminin the wrong app. Let it pass withprerender: { handleHttpError }in the main frontend'ssveltekit()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-Buildand in the status endpoint. svelteVerifyTschecks the main frontend's client only.- The typed page routes (
FrontendRoutes) and the generated Kotlin oflibraries { }come from the main frontend. - In Gradle,
libraries { }withsvelteSync, thesvelteVerify...checks,svelteVerifyLeaks,svelteCheckand the other frontend tools work on the main frontend. Another frontend is installed, built and packaged; add what it needs to its ownpackage.json.