Skip to content

Gradle settings and tasks ​

Every setting of svelte { }, every task and every Gradle property.

Gradle

All defaults at a glance ​

The values shown are the defaults.

kotlin
import io.github.nijasc.ktor.svelte.gradle.PackageManager

svelte {
    frontendDir = layout.projectDirectory.dir("frontend")
    outputDir = "build"
    packageManager = PackageManager.Auto
    buildScript = "build"
    buildEnv = emptySet()
    addRuntimeDependency = true
    includeSourceMaps = false
    shortTaskNames = true
    timingSummary = true
    precompress = true
    verifyLeaks = true
    dev {
        port = 5173
        script = "dev"
        debugPort = 5005
        openBrowser = true
        https = false
        httpsPort = 8443
    }
}

bunVersion and nodeVersion are unset by default, and libraries { } is empty.

Settings ​

SettingDefaultWhat it does
frontendDirfrontendDirectory of the SvelteKit project
outputDir"build"Adapter output, a folder inside frontendDir given relative to it. Must match the adapter's pages option
packageManagerPackageManager.AutoAuto, Bun, Pnpm, Npm or Yarn. Auto picks from bun.lock, pnpm-lock.yaml, package-lock.json or yarn.lock
bunVersionunsetAn exact Bun version, such as "1.3.14", that ktor-svelte downloads and uses instead of the Bun on PATH. See Pin Bun
nodeVersionunsetAn exact Node version, such as "22.12.0", that ktor-svelte downloads and puts first on PATH for every frontend task, with npm from that Node. For npm and pnpm teams. See Pin Node
buildScript"build"package.json script that builds the frontend
buildEnvemptyEnvironment variables that affect the build. Declare any your frontend reads through $env, or Gradle can reuse a stale build. Also counted as public by svelteVerifyLeaks
addRuntimeDependencytrueAdds ktor-svelte-server to implementation, at the plugin's own version, and ktor-svelte-test to a browserTest suite
includeSourceMapsfalseShips .map files in the JAR, where anyone can download them
shortTaskNamestrueRegisters dev, sync, doctor and gen as short names for the tasks used most
timingSummarytrueEnds a build that ran the frontend with a short table of how long each step took. See Build times
precompresstrueGzips text files of 1 KiB or more that have no .br or .gz variant yet, such as SVG, JSON and fonts from static/, and keeps the result only when it saves at least 10%
verifyLeakstrueRuns svelteVerifyLeaks before the build goes into the JAR. See Secrets in the frontend build
libraries { }emptyTailwind, DaisyUI, Lucide, i18n, typed routes and more. See Libraries
naming { }no rulesNaming rules for pages, API routes, DTOs and message keys that svelteVerifyNaming checks. See svelteVerifyNaming
frontend(name) { }noneAnother SvelteKit project served under its own path prefix, with frontendDir, outputDir, buildScript, basePath and devPort. See Multiple frontends

The package manager must already be installed unless you set bunVersion, or nodeVersion with npm.

dev ​

See Dev workflow.

SettingDefaultWhat it does
dev.port5173Port passed to Vite by svelteDev and svelteDevAll
dev.script"dev"package.json script that starts Vite
dev.debugPort5005Port where the app started by svelteDevAll listens for a debugger, on 127.0.0.1 only. 0 turns it off
dev.openBrowsertrueOpens the app in the default browser once svelteDevAll is ready, the first time only. Never in CI or without a display
dev.httpsfalseServes the app started by svelteDevAll over HTTPS too, with a development certificate from ~/.ktor-svelte/dev-https. See HTTPS in development
dev.httpsPort8443Port of that HTTPS address, on 127.0.0.1 only

Misspelled settings ​

In a Groovy build.gradle, a misspelled setting such as fronendDir = file('web') fails with the closest name and the list of settings, instead of Gradle's generic missing property error. The same goes for the blocks inside svelte { }. The Kotlin DSL catches the same mistake when it compiles the script.

Libraries ​

Everything in libraries { } is off until you call it. svelteSync installs what you turn on and writes the generated files. See Frontend libraries for each one.

kotlin
import io.github.nijasc.ktor.svelte.gradle.DaisyTheme

svelte {
    libraries {
        daisyUi {
            themes(DaisyTheme.Light, DaisyTheme.Dracula)
            defaultTheme(DaisyTheme.Light)
            prefersDark(DaisyTheme.Dracula)
        }
        lucide()
        routes()
        toasts()
        i18n {
            locales("en", "de")
        }
    }
}
CallSettings insideDefault inside
tailwind { }typography(), forms()both off
daisyUi { }themes(...), defaultTheme(...), prefersDark(...), customTheme(name, colorScheme) { }. Turns Tailwind on toocolorScheme = "light" for a custom theme
lucide { }allIcons()off: only the icons you use
i18n { }locales(...), defaultLocale, strategy, messagesDirdefaultLocale is the first locale, strategy = LocaleStrategy.Cookie, messagesDir is frontend/messages
routes { }dirfrontend/src/routes
toasts { }reloadPrompt()off
fonts(sans) { }mono, variablevariable = true
installable { }name, shortName, description, themeColor, backgroundColor, display, iconcolors "#ffffff", display = "standalone"
images()none
components()none
charts()none
generatedPackage"io.github.nijasc.ktorsvelte", the package of the generated Kotlin

Review your configuration ​

./gradlew svelteConfig gives an overview of how ktor-svelte is set up in your app. It lists the Gradle settings, then starts your app once to read the effective install(Svelte) { } settings, the same way svelteGenerateTs does, so it shows what really runs, including values set from environment variables. Settings you changed are marked with their default, which makes it easy to see what a new version changed or added after an upgrade.

Then it scores the setup and lists what to change:

text
Scores
  Security              [#########-]  90%  10 of 11
  Performance           [##########] 100%  4 of 4
  Operations            [#######---]  66%  2 of 3
  Developer experience  [##########] 100%  5 of 5

Suggestions
  - [Security] Set maxJsonStringLength = 100_000, or the longest text your API accepts.
  - [Operations] Set healthEndpoint = true and point your orchestrator at /_ktor-svelte/health.

The checks cover the origin check, security headers and CSP, error details, body and JSON limits, rate limits, the dev proxy, source maps, compression, caching, image optimization, health and request IDs, the sitemap address, a pinned Bun, generated TypeScript, error toasts, typed routes and dev tooling. A suggestion is advice, not an error: a public API may well do without healthEndpoint. Without the application plugin, only the Gradle settings are shown.

Pin Bun ​

A fresh CI image or laptop often has no package manager, so the first build fails. Set bunVersion and the plugin downloads that exact Bun from Bun's GitHub releases the first time a task needs it:

kotlin
svelte {
    bunVersion = "1.3.14"
}
  • The archive is checked against the release's SHASUMS256.txt before it is unpacked into ~/.gradle/ktor-svelte/bun/<version>/, and every later build reuses it.
  • Every task then uses this Bun, even when another one is on PATH, so all machines build with the same version.
  • With packageManager = AUTO, Bun becomes the package manager. Bun runs Vite itself, so Node is not needed.
  • It works on Windows, macOS and Linux, including Alpine, on x64 and arm64.
  • Behind a proxy, set Java's https.proxyHost and https.proxyPort in gradle.properties with the systemProp. prefix.

Pin Node ​

Teams whose lockfile is npm's or pnpm's need Node, and every laptop and CI image has its own. Set nodeVersion and the plugin downloads that exact Node from nodejs.org the first time a task needs it:

kotlin
svelte {
    nodeVersion = "22.12.0"
}
  • It follows the rules of the pinned Bun: the archive is checked against the release's SHASUMS256.txt before it is unpacked into ~/.gradle/ktor-svelte/node/<version>/, and every later build reuses it.
  • Every frontend task runs with that Node first on PATH, so Vite and every script use it. npm comes with it: with package-lock.json, the plugin runs the npm of that Node and needs none installed.
  • pnpm and Yarn are still taken from PATH, and run on the pinned Node.
  • svelteDoctor reports the pinned Node instead of the installed one, and the build cache counts the version, so a new Node builds the frontend again.
  • It works on Windows, macOS and Linux, on x64 and arm64. Node publishes no build for Alpine: install it with apk there.
  • Behind a proxy, set Java's https.proxyHost and https.proxyPort in gradle.properties with the systemProp. prefix.

Build times ​

A build that installed or built the frontend ends with how long each step took, so you can see where a slow build spends its time:

text
ktor-svelte build times:
  install          0.2s  up to date
  frontend build  12.4s
  bundling         0.3s
  Kotlin compile   4.1s  from cache
  total           17.0s
  • It lists the steps of this project that were part of the build: svelteInstall, svelteBuild, svelteBundle and compileKotlin. A step that did no work says why: up to date, from cache, skipped or failed.
  • A build where no frontend step ran, such as a second ./gradlew build with nothing changed, prints nothing.
  • It works with the configuration cache. Turn it off with svelte { timingSummary = false }.

Format both sides ​

One command formats Kotlin and the frontend, and one checks them:

bash
./gradlew format
bash
./gradlew formatCheck

format runs the frontend's format script from package.json, and formatCheck runs its lint script. Projects made by the setup script have both, as prettier --write . and prettier --check . && eslint .. For Kotlin, they run ktlintFormat and ktlintCheck when the ktlint Gradle plugin is applied, or spotlessApply and spotlessCheck with Spotless. Without either, Kotlin is left alone and the task says so. A frontend without the script is skipped with a hint.

If your build already has a task called format or formatCheck, ktor-svelte does not register its own. The frontend half is always there as svelteFormat and svelteFormatCheck.

Check before every commit ​

svelteGitHooks installs a git pre-commit hook in your clone that runs formatCheck and svelteVerifySync, so an unformatted file or a stale generated file never reaches a commit:

bash
./gradlew svelteGitHooks

A commit that fails the check is stopped with the command that fixes it. git commit --no-verify skips the hook once, and ./gradlew svelteGitHooks --remove takes it out again. The hook lives in .git, which git does not share, so everyone on the team runs the task once. A pre-commit hook that something else installed is never replaced: the task stops and tells you to call the two tasks from your own hook.

Generated files without merge conflicts ​

Two branches that both add a page, an icon or an API route both change the same generated files, and git reports a conflict in a file nobody wrote. The same svelteGitHooks run ends that in your clone:

  • When both sides of a merge or a rebase changed a generated file, git keeps one side and does not stop.
  • Right after the merge or rebase, svelteSync and svelteGenerateTs run and write the files as they belong to the merged code. If git status then shows changes, commit them.

It covers src/lib/ktor-svelte and src/lib/api, through a merge=ktor-svelte attribute in the .gitattributes of those folders. Run svelteSync and svelteGenerateTs once after upgrading so those files get the attribute. In a clone where nobody ran svelteGitHooks, git ignores the attribute and merges those files the way it always did.

A merge that stops for a conflict in one of your own files does not regenerate when you finish it. The pre-commit hook and check still notice stale generated files, and ./gradlew svelteSync svelteGenerateTs fixes them. If a post-merge or post-rewrite hook from another tool is already there, such as Git LFS, it stays, and the task tells you to run those two tasks yourself after such a merge.

Short task names ​

The four tasks you type most have a short name:

ShortSame as
./gradlew devsvelteDevAll
./gradlew syncsvelteSync
./gradlew doctorsvelteDoctor
./gradlew gensvelteGenerateTs

They are the same tasks under another name, so options work as well: ./gradlew doctor --fix, ./gradlew dev --full-stack-traces. dev and gen exist when the long tasks do, which is in a project with the application plugin.

A short name that your build or another plugin already uses is left alone, and the long name keeps working. Set shortTaskNames = false to register none of them. The docs use the long names, because those always exist.

Gradle tasks ​

Tasks marked "app" exist only in a project with the application plugin, because they start your app. For what each check catches and what its output looks like, see Checks and tooling.

Build ​

These run as part of jar and processResources, so you rarely call them yourself.

TaskWhat it does
svelteInstallInstalls the frontend dependencies from the lockfile
svelteBuildBuilds the frontend with buildScript
svelteVerifyLeaksFails when a secret value from the environment or a .env file is in the frontend build. Runs after svelteBuild while verifyLeaks is on. See Secrets in the frontend build
svelteBundleCopies the build into the JAR's resources with its manifest, and precompresses files
svelteInstallAdmin, svelteBuildAdmin, svelteBundleAdminThe same for each other frontend, named after it. svelteDevAdmin starts its Vite
svelteSyncInstalls configured libraries and writes their generated files. Short name sync
svelteVerifySyncFails if libraries don't match your config. Runs before every frontend build
svelteGenerateSourcesGenerates Kotlin for your libraries. Runs before compiling
svelteEmailsRenders the components in src/emails to email templates and generates Emails.kt. Runs before compiling. See Emails
svelteBuildInfoWrites the version, the git commit and its time into the build, for buildInfo. Runs before resources are processed

Develop ​

TaskOptionsWhat it does
svelteDevAll (app)--full-stack-tracesRuns Vite, the Kotlin compiler and your app, and restarts the app when Kotlin changes. Short name dev. See Dev workflow
svelteDevStarts Vite
svelteGenerateTs (app)Starts your app once to regenerate TypeScript. Needs generateTs = true. Short name gen

Check ​

TaskOptionsWhat it does
svelteVerifyTs (app)Starts your app once and fails if the committed TypeScript is out of date. Runs as part of check
svelteVerifyRoutes--fixLists links to pages that are written as strings, in the frontend and in Kotlin respondRedirect calls, with the typed route to use instead, and fails if it finds any. --fix rewrites the ones it can
svelteVerifyLinks--strictLists internal links that lead to no page, no API route and no static file
svelteVerifyLoadsFails if an API call inside a load function uses neither apiWith(event) nor { fetch }
svelteVerifyNaming--strictLists names that break your naming rules
svelteVerifyMessages--strictLists i18n messages nothing uses
svelteVerifyApiRoutes--strictLists API routes that nothing in the frontend calls
svelteApiChanges--against, --strictLists what changed in the API for callers since origin/main, or the revision given with --against. --strict fails on a change that can break them
svelteVerifyA11y (app)--path, -PbrowserPackages the app, opens its prerendered pages in a browser in light and dark, and fails on accessibility problems that axe finds. Not part of check
svelteSmokeTest (app)--path, --skip, --start-secondsPackages the app, starts it in production mode, and fails unless every prerendered page and the API routes are answered. Not part of check
svelteDoctor--fixChecks adapter, adapter output against svelte.outputDir, the bundled manifest, #api, tsconfig, Kit version, Node, tool and port, that every installed package still has its files, that NODE_EXTRA_CA_CERTS points to a file, and that the package registry is reachable with the proxy and certificate settings that apply, and says what to fix. Gradle's --offline skips the registry. --fix repairs what needs no decision. Short name doctor
svelteReadme--checkWrites the commands, addresses and environment variables of the app between two markers in README.md. --check fails when that section is out of date
svelteRoutesDiagram--outputWrites a Mermaid diagram of which page calls which API route to build/ktor-svelte/pages-to-routes.md, or to the file given with --output
svelteConfigPrints every setting of svelte { } and of install(Svelte) { }, marks the ones you changed from the default, scores the setup and suggests what to turn on. See Review your configuration
svelteCheckRuns the frontend's check script

Create and change code ​

TaskOptionsWhat it does
svelteInit--package-manager=bunCreates a working SvelteKit project in an empty frontendDir, then runs svelteSync and svelteGenerateRunConfigurations
svelteAdd--page, --route, --crudCreates a page with a typed load: svelteAdd --page=notes/[id]. --route adds a Kotlin route to start from. svelteAdd --crud=Note writes list, detail and form pages for a class
svelteRename--page, --to, --forceMoves a page and rewrites its typed route calls in the frontend and in Kotlin: svelteRename --page=notes/[id] --to=memos/[id]. --force renames even with uncommitted changes

Test and deploy ​

TaskOptionsWhat it does
browserTest-PbrowserYours: a test suite with this name gets the browser test kit, the packaged app and the browser from -Pbrowser
svelteRecordTest (app)--name, -PbrowserOpens the packaged app in a browser and writes what you do there as a Kotlin browser test: --name=SignIn
svelteDeploy--host, --forceWrites the deploy configuration for a host from the project's settings. Railway so far

Format and git ​

TaskOptionsWhat it does
format, formatCheckFormat, or check the formatting of, Kotlin and the frontend in one go
svelteFormat, svelteFormatCheckThe frontend half of those: run the format and the lint script
svelteGitHooks--removeInstalls a pre-commit hook that runs formatCheck and svelteVerifySync, and keeps generated files out of merge conflicts. --remove takes the hook out

Dependencies and cleanup ​

TaskOptionsWhat it does
svelteRun--script, --argsRuns any package.json script: svelteRun --script=lint --args="--fix --quiet". Quote an argument that contains spaces
svelteOutdatedLists outdated frontend dependencies
svelteUpdateDependenciesUpdates frontend dependencies and the lockfile
svelteUpgrade--to, --bump-onlyUpgrades ktor-svelte itself. See Upgrade ktor-svelte
svelteUpgradeNotes--sincePrints the upgrade notes since a version that apply to this project
svelteCleanDeletes node_modules, .svelte-kit and the build output
deepCleanRuns clean, then also deletes the project's .gradle and .kotlin directories, node_modules, .svelte-kit, .vite, .turbo, .cache, .eslintcache and the build output. Lockfiles and generated files are kept. Files a running Gradle daemon or IDE still holds, which happens on Windows, are skipped with a warning

IDE ​

TaskOptionsWhat it does
svelteLiveTemplates--install, --config-dirWrites IntelliJ live templates to build/ktor-svelte/live-templates/. --install copies them into every IntelliJ IDEA and WebStorm configuration it finds, --config-dir=... picks another JetBrains folder
svelteGenerateRunConfigurationsWrites IntelliJ run configurations to .run/, keeping any that exist: Dev, Dev and debug, Debug app, Debug frontend, Ktor, Vite, Generate TypeScript, Build JAR, Type check frontend and Update frontend dependencies

Gradle properties ​

PropertyEffect
-Psvelte.skip=trueSkips the frontend build, and warns if a JAR is being built
-Psvelte.dev=trueSame as skip, and also sets -Dio.ktor.development=true on run
-Psvelte.verifyTs=falseLeaves svelteVerifyTs out of check
-Psvelte.verbose=trueShows the package manager and Vite output of svelteInstall, svelteBuild, svelteSync and svelteInit. Without it, that output is hidden when the command succeeds and printed in full when it fails. --info also shows it
-Pbrowser=firefoxBrowser for browserTest, svelteRecordTest and svelteVerifyA11y: chromium (default), firefox or webkit

Set one for every build in gradle.properties:

properties
svelte.verbose=true

Full example ​

A build.gradle.kts for a real app: pinned Bun, a frontend in another folder, an environment variable the build reads, libraries, and HTTPS in development.

kotlin
import io.github.nijasc.ktor.svelte.gradle.DaisyTheme

svelte {
    frontendDir = layout.projectDirectory.dir("web")
    bunVersion = "1.3.14"
    buildEnv = setOf("PUBLIC_SENTRY_DSN")
    dev {
        port = 5174
        https = true
    }
    libraries {
        daisyUi {
            themes(DaisyTheme.Light, DaisyTheme.Dark)
            defaultTheme(DaisyTheme.Light)
            prefersDark(DaisyTheme.Dark)
        }
        lucide()
        routes()
        components()
    }
}

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