Skip to content

Examples ​

Three example apps live in the repository, from the smallest possible app to a full team board with sign in. They are separate Gradle builds that use ktor-svelte the way your project does, and they double as the end-to-end tests, so they always work with the current code.

ExampleSizeBest for
basicOne route, three pagesSeeing the minimum that works
notesA notes appEach feature on its own, easy to find
showcaseA team board with usersFeatures working together in a real app
two-frontendsA public site and an admin areaMultiple frontends in one app

Run them ​

Clone the repository, then start an example with everything in one command:

bash
git clone https://github.com/nijasc/ktor-svelte.git
cd ktor-svelte
./gradlew -p examples/notes svelteDevAll

Open http://localhost:8080. In IntelliJ, open the repository and run the Notes: Dev, Showcase: Dev or Basic: Dev run configuration instead. You need Java 17 or newer and Bun.

To build and run the production JAR:

bash
./gradlew -p examples/notes buildFatJar
bash
java -jar examples/notes/build/libs/notes-all.jar

The showcase builds the same way with buildFatJar. The basic example uses Shadow instead, so its task is shadowJar.

basic ​

examples/basic is the smallest possible app: install(Svelte) with no settings, one API route and three pages.

Look atTo see
src/main/kotlin/Application.ktinstall(Svelte) with no settings, and one API route
frontend/src/routes/+page.svelte, about/Prerendered pages
frontend/src/routes/app/A page that renders in the browser and calls the API
frontend/vite.config.tsThe adapter-static setup SvelteKit needs

Start here when you want to see what ktor-svelte does before any of its options.

notes ​

examples/notes is a small notes app that uses almost every feature, each in a place that is easy to find. The tutorial builds a smaller version of it step by step.

Look atTo see
src/main/kotlin/notes/Application.ktgenerateTs, transport { json(); xml(); compression() }, publicConfig and apiDocs
src/main/kotlin/notes/Model.ktDTOs with @JsonSchema bounds and Validated rules, a query class, a sealed Activity and Page<Note>
src/main/kotlin/notes/Routes.ktCRUD routes with resource, typed 404 errors, a paged feed with getPage and multipart attachments
build.gradle.ktsTailwind, DaisyUI with a custom theme, Lucide, typed routes, images, toasts and i18n, all in svelte { libraries { } }
frontend/src/lib/api/The generated client, committed
frontend/src/routes/notes/+page.svelteForms with use:field, client and server validation, search and tag filters
frontend/src/routes/notes/[id]/A dynamic route with apiWith(event) in load and typed errors
frontend/src/routes/+layout.svelteDaisyUI themes, Lucide icons and i18n with a language switcher
src/e2eTest/kotlin/NotesAppTest.ktHow the production JAR is tested end to end

Things to try ​

While svelteDevAll runs:

  • Change a Svelte file: the page updates without a reload.
  • Add a property to Note in Model.kt: the app restarts, and frontend/src/lib/api/types.ts gains the property a moment later.
  • Open http://localhost:8080/api/docs for Swagger UI.
  • Submit an empty title: the error comes from the generated validate() before any request is sent.
  • Click the API button in the corner of a page to see every call, with its status and time.

showcase ​

examples/showcase is a team board that people sign in to. Where notes shows each feature on its own, the showcase shows them working together the way a real app needs them: pages behind a login, an admin area, a database and uploads.

The board of the showcase, with counters, a search box, filters and a list of tasks

bash
./gradlew -p examples/showcase svelteDevAll

Signing in ​

The first start creates two people, ada@example.com as admin and grace@example.com as member. Set their passwords with SHOWCASE_ADMIN_PASSWORD and SHOWCASE_MEMBER_PASSWORD, at least 10 characters each. Without them, the app generates passwords and writes them to its log once.

The data lives in examples/showcase/build/showcase-data, so ./gradlew -p examples/showcase clean starts over.

Where to look ​

Look atTo see
src/main/kotlin/showcase/Application.ktrouting = SvelteRouting.Manual with public pages, everything else behind authenticate, a named rate limit and a health check that asks the database
src/main/kotlin/showcase/Application.ktEnvironment variables declared once with environment, and startupStep for the slow parts of startup
src/main/kotlin/showcase/Application.ktcurrentUser<User>, loginPage, permissions, preferences and page guards, declared once for both sides
src/main/kotlin/showcase/Application.ktconstants, errorCodes, idempotency(), frontendErrors(), webVitals and a typed cookie
src/main/kotlin/showcase/Auth.ktA signed session cookie, sign in, registration, and an admin area guarded on the server
src/main/kotlin/showcase/Database.kt, src/main/resources/db/migration/Exposed on an embedded H2 database, with Flyway migrations
src/main/kotlin/showcase/TaskRoutes.ktPaged and filtered lists, typed errors in the language of the person, multipart uploads with a size and type check, and downloads that browsers never run as a page
src/main/kotlin/showcase/Model.kt@JsonSchema bounds, Validated rules and a sealed Activity that becomes a TypeScript union
build.gradle.ktsEvery frontend library at once: themes with a custom one, fonts, charts, an installable app, components, toasts with a reload prompt and i18n
frontend/src/routes/+layout.svelteThe generated currentUser store that the header reads
frontend/src/routes/(app)/+layout.tsA layout group for the pages that need a session
frontend/src/routes/(app)/board/+page.svelteSearch as you type with latest, filters, "load more" with a cursor, and prefetchOnHover
frontend/src/routes/(app)/tasks/[id]/+page.svelteUploads with a progress bar, comments, Activity.match and a confirm dialog
frontend/src/lib/components/TaskForm.svelteOne form for creating and editing, with use:field and errors from the browser and the server
frontend/messages/English and German texts that the pages and the API errors share
frontend/src/emails/Welcome.svelteA welcome email in English and German with a shared layout, rendered on registration and shown to admins at /api/admin/emails/welcome
src/e2eTest/kotlin/ShowcaseAppTest.ktSessions, roles, uploads, paging and rate limits tested against the production JAR
src/browserTest/kotlin/ShowcaseBrowserTest.ktThe same JAR driven by Playwright in Chromium, Firefox and WebKit, with accessibility checks
src/devBrowserTest/kotlin/DevModeBrowserTest.ktsvelteDevAll with a browser: hot reload, a restart after a Kotlin change, and browser errors in the dev log

Environment variables ​

VariableWhat it does
PORTThe port the server listens on, 8080 unless you set it
SESSION_SIGN_KEY64 hex characters that sign the session cookie, so sessions survive a restart
SHOWCASE_DATAWhere the database and the uploaded files go
SHOWCASE_REGISTRATIONclosed stops new people from creating an account
SHOWCASE_LOGIN_ATTEMPTSSign-in attempts allowed per minute, 10 unless you set it
SHOWCASE_SESSION_SECONDSHow long someone stays signed in, a week unless you set it
SHOWCASE_SITE_URLThe public address of the site, for the sitemap
SHOWCASE_INSECURE_COOKIEStrue to test the JAR over plain HTTP in browsers that do not treat localhost as secure
APP_NAMEThe name shown in the header

The pictures on the start page come from ./gradlew -p examples/showcase screenshots, which starts the showcase JAR in a headless Chromium.

Your own examples ​

The recipes show complete solutions for sessions, uploads, live updates, paging and an admin area that you can copy into your app. Everything ktor-svelte does links every feature to its page.

two-frontends ​

Two SvelteKit projects in one app: the public site in frontend/ and an admin area in admin/, served under /admin.

Look atTo see
src/main/kotlin/twofrontends/Application.ktfrontend("/admin") and generateTs with one API route
build.gradle.ktssvelte { frontend("admin") { } }, and ports you can change with -PvitePort, -PadminVitePort and -PdebugPort
admin/vite.config.tspaths: { base: '/admin' } and the admin's own hot reload port
frontend/src/lib/api/, admin/src/lib/api/The same generated client in both frontends
src/browserTest/Both frontends in a browser, from the packaged JAR
src/devBrowserTest/svelteDevAll with one Vite per frontend

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