Kylndocs
Get started

Debugging

Where a route's code runs decides where you debug it. A Kyln app has two runtimes: the browser, where client routes run after hydration, and the Bun server, where everything else runs. Each has a first-class debugger; this page shows you which one to reach for and how to attach it.

Where your code runs

  • Client routes (*.route.ts) are server-rendered for first paint, then hydrate and run in the browser. Clicks, signals, and re-renders all execute in the page, so you debug them in the page's DevTools.
  • Server-only routes (*.server.route.ts) render entirely on the server. Their code never ships to the browser, so there is nothing to break on in DevTools; you debug them in Bun's inspector. The same goes for the rest of your server-side code: API endpoints, guards, services doing server work, and scheduled tasks.

If you're stepping through a render() and your breakpoint never hits, this split is usually why: the code is running in the other runtime.

Debugging in the browser

The dev server serves every module with an inline sourcemap, so the browser's Sources panel shows your original TypeScript, not transpiled output. No setup is needed:

  1. Run kyln dev and open your app.
  2. Open DevTools and find your file under Sources (your src/ tree appears under the dev server's origin).
  3. Set breakpoints directly in the .ts file: a render(), an event handler, a signal update.
  4. Interact with the page. The debugger pauses on your original source with the real call stack.

This covers everything that runs client-side: route classes after hydration, layouts wrapping them, components, and template event handlers.

Debugging on the server

For server-only routes and any other server-side code, run the dev server under Bun's inspector:

kyln dev --inspect

--inspect boots the same dev server with the inspector attached and prints a debug.bun.sh link. Open that link in a browser and you get a full debugger against the server process:

  1. Set breakpoints in the actual .ts files: server-only routes, layouts, services, API endpoints.
  2. Trigger the code by requesting a page (or hitting the endpoint).
  3. The server pauses mid-render with the full call stack, live variables, and step controls.

The flag is a shorthand for running the dev process under bun --inspect yourself; from a project directory the manual equivalent is:

bun --inspect node_modules/@kyln/cli/src/index.ts dev

Both attach the inspector to the same process that renders your pages, so what you pause is exactly what serves the request.

Sourcemaps in production

Production builds are a different story on purpose. kyln bake does not emit sourcemaps by default, so your original source doesn't ship with the build. If you need them (for example, to symbolicate errors in an error tracker), turn them on in kyln.config.ts:

build: {
  sourcemap: true,  // emit external .map files alongside the build
}

See Configuration for the rest of the build options.

Next

With your app built, tested, and debuggable, the last step is shipping it. Deployment covers the production build and running it in a container.