Skip to content

Architecture ​

How a SvelteKit build ends up in the JAR, and how a request reaches a file. Read this before changing the plugin or the runtime. How it works has the exact resolution rules.

ktor-svelte architecture At build time the frontend is installed, built and bundled into the JAR with a manifest. At request time Ktor routing tries your routes first, then the ktor-svelte catch-all resolves the path against the manifest and serves the file. In development the handler proxies to Vite instead. Build time (Gradle)frontend/your SvelteKit appsvelteInstalllockfile installsvelteBuildadapter-staticsvelteBundlemanifest and gzipJAR resourcesktor-svelte/public/Request time (Ktor)BrowserGET /aboutKtor routingyour routes firstSvelteHandlercatch-all routeRequestResolvermanifest lookupAssetResponderETag, range, encodingfilesmanifestYour routes/api/..., always winDevProxyto Vite, dev onlySolid arrows run in production. Dashed arrows read build output or run only in development.

Build time ​

The Gradle plugin turns the frontend into resources of your app. Each step is a cacheable task, wired before processResources:

StepWhat it doesSource
svelteInstallInstalls dependencies from the lockfile with the detected package managertasks/SvelteTasks.kt, PackageManager.kt
svelteBuildRuns the build script. Its inputs include a fingerprint of the package managertasks/SvelteTasks.kt, tasks/ToolFingerprint.kt
svelteBundleCopies the output to ktor-svelte/public/, gzips what the adapter did not compress, hashes inline scripts and writes ktor-svelte/manifest.jsontasks/SvelteBundleTask.kt, tasks/InlineScripts.kt
svelteSyncWrites the frontend library setup and generated files from svelte { libraries { } }tasks/SvelteSyncTasks.kt, libraries/

Paths are relative to ktor-svelte-gradle-plugin/src/main/kotlin/io/github/nijasc/ktor/svelte/gradle/.

The manifest is the contract between the two halves. It lists every servable file with its size, hash, precompressed variants and, for HTML pages, the hashes of their inline scripts. The runtime never turns a request path into a file path. It only looks paths up in the manifest.

Request time ​

install(Svelte) adds a catch-all route and a few hooks. Ktor prefers more specific routes, so your own routes always win.

StepWhat it doesSource
GuardsOrigin check, body size, JSON shape limits and rate limits on API pathsinternal/security/RequestGuards.kt, JsonShapeLimits.kt, RateLimits.kt
Catch-allTakes GET and HEAD requests that no route of yours answered, and answers 405 for other methods on known pagesinternal/SvelteHandler.kt
ResolutionMaps the path to a manifest entry, a 308 redirect, the SPA fallback or a 404internal/assets/RequestResolver.kt
ResponseSets Cache-Control, ETag and CSP, picks a precompressed variant, serves byte ranges and injects publicConfiginternal/assets/AssetResponder.kt, ByteRanges.kt, ConfigInjector.kt
StorageOpens files from the classpath or from SvelteSource.Directoryinternal/assets/AssetStore.kt, Manifest.kt

Paths are relative to ktor-svelte-server/src/main/kotlin/io/github/nijasc/ktor/svelte/. The root package holds only the public API, such as Svelte.kt and SvelteConfig.kt.

Development ​

In development mode the same catch-all sends frontend requests to Vite through internal/dev/DevProxy.kt, which uses the JDK HttpClient and only serves local clients. Your API routes still answer directly, so the browser talks to one origin.

generateTs reads Ktor's OpenAPI model of your routes when the app starts and writes the TypeScript client. That code lives in internal/typescript/, and the client templates are TypeScript files under src/main/resources. The development-only endpoints, such as the route table and the status page, are in internal/dev/.

svelteDevAll starts Vite and the app together, waits until both answer, and prints one ready banner. See tasks/SvelteDevAllTask.kt and tasks/ReadyBanner.kt.

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