Skip to content

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 ​

text
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.md

With --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.

FileWritten byChanges when
frontend/src/lib/api/*the app in development, or svelteGenerateTsa route or DTO changes
frontend/vite.config.tssvelteSynclibrary settings change
frontend/src/lib/ktor-svelte/*svelteSyncthemes, icons or locales change
frontend/src/hooks*.tssvelteSynci18n or theme settings change
Kotlin AppTheme and Messages classesthe Gradle build, in build/generated, never committedthemes 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,
  • svelteVerifyTs and svelteVerifySync in check fail 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:

ts
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.

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