Project structure
What goes where in a ktor-svelte project, and which files are yours to edit.
A project created by the setup script looks like the tree below. Projects that add ktor-svelte to an existing app have the same core: a Gradle build with the plugin, a Ktor app with install(Svelte), and a SvelteKit app in frontend/.
The tree
my-app/
build.gradle.kts plugins, svelte { } settings, dependencies
settings.gradle.kts
gradle.properties
gradle/libs.versions.toml version catalog
gradlew, gradlew.bat Gradle wrapper
src/main/kotlin/
Application.kt embeddedServer, install(Svelte), routes
Env.kt env() and requireEnv(), reading the environment and .env
Errors.kt typed error responses
Auth.kt if you chose sign in
Database.kt if you chose Postgres
src/main/resources/
logback.xml
db/migration/ if you chose Flyway
frontend/
package.json
vite.config.ts generated by ktor-svelte
vite.user.ts your own Vite settings, if you need any
messages/ i18n message files, if i18n is on
src/
app.html
routes/ your pages
lib/api/ generated TypeScript client
lib/ktor-svelte/ generated helpers for themes, icons, i18n and more
.run/ IntelliJ run configurations
.env.example every variable the app reads
.env local secrets, if you chose sign in or Postgres; not committed
compose.yaml if you chose Postgres
Dockerfile if you chose Docker
.github/workflows/ci.yml if you chose GitHub Actions
build-logic/ if you chose the convention plugin
README.mdWith --no-idea-ext, the Kotlin files sit in package folders, such as src/main/kotlin/com/example/app/, instead of directly in src/main/kotlin.
Files you own and files ktor-svelte owns
ktor-svelte writes some files for you and keeps them up to date. Each of them starts with a "Generated by ktor-svelte" header, and the line after it links to the docs page that explains the file, so a teammate who opens it knows where to look. The files in src/lib/api have no header of their own; their .gitattributes carries it instead.
Do not edit generated files
The next sync or start overwrites your changes.
| File | Written by | Changes when |
|---|---|---|
frontend/src/lib/api/* | the app in development, or svelteGenerateTs | a route or DTO changes |
frontend/vite.config.ts | svelteSync | library settings change |
frontend/src/lib/ktor-svelte/* | svelteSync | themes, icons or locales change |
frontend/src/hooks*.ts | svelteSync | i18n or theme settings change |
Kotlin AppTheme and Messages classes | the Gradle build, in build/generated, never committed | themes or messages change |
Everything else is yours. ktor-svelte never overwrites a file without the header. If it needs to own a file you already have, such as your own vite.config.ts, the build stops and tells you what to move. Put custom Vite settings in vite.user.ts.
Commit the generated files
Commit the generated frontend files. That way:
- a frontend build never needs the JVM app to run first,
svelteVerifyTsandsvelteVerifySyncincheckfail when they are out of date, so a changed DTO cannot drift away from the frontend unnoticed.
Each generated folder also gets a .gitattributes that marks its files as generated. Generated files without merge conflicts shows how to keep two branches from fighting over them.
The #api import
svelteInit and svelteSync add an import alias to frontend/package.json, so pages import the generated client the same way wherever they are:
import { api, isApiError, type Note } from '#api';Libraries add their own short imports next to it, such as #routes for typed routes and #components/... for the ready-made components.
What ends up in the JAR
svelteBundle copies the static build into ktor-svelte/public/ in your resources and writes ktor-svelte/manifest.json. Hidden files such as .env and source maps are left out. The How it works page explains how requests are answered from the manifest.