@kimmio/svelte-adapter-bun

Adapter for SvelteKit apps that generates a standalone Bun server.

:zap: Usage

Install with bun add -d @kimmio/svelte-adapter-bun, then add the adapter to your svelte.config.js:

// svelte.config.js
import adapter from '@kimmio/svelte-adapter-bun';

export default {
  kit: {
    adapter: adapter(),
  },
};

After building the server (vite build), use the following command to start:

# go to build directory
cd build/

# run Bun
bun run ./index.js

:gear: Options

The adapter can be configured with various options:

// svelte.config.js
import adapter from '@kimmio/svelte-adapter-bun';
export default {
  kit: {
    adapter: adapter({
      out: 'build',
      serveAssets: true,
      envPrefix: 'MY_CUSTOM_',
      precompress: true,
    }),
  },
};

out

The directory to build the server to. It defaults to build — i.e. bun run ./index.js would start the server locally after it has been created.

serveAssets

Serve static assets. Default: true

• [x] Support HTTP range requests

precompress

Enables precompressing using gzip and brotli for assets and prerendered pages. It defaults to true.

envPrefix

If you need to change the name of the environment variables used to configure the deployment (for example, to deconflict with environment variables you don't control), you can specify a prefix:

envPrefix: 'MY_CUSTOM_';

MY_CUSTOM_HOST=127.0.0.1 \
MY_CUSTOM_PORT=4000 \
MY_CUSTOM_ORIGIN=https://my.site \
bun build/index.js

:spider_web: WebSocket Server

https://bun.sh/docs/api/websockets

The server supports WebSocket connections. To enable them, you need to add a websocket hook to server hooks.

// hooks.server.ts
import type { Handle } from '@sveltejs/kit';

export const handle: Handle = async ({ event, resolve }) => {
  const { request } = event;
  const url = new URL(request.url);

  // Check for WebSocket upgrade request
  if (
    request.headers.get('connection')?.toLowerCase().includes('upgrade') &&
    request.headers.get('upgrade')?.toLowerCase() === 'websocket' &&
    url.pathname.startsWith('/ws')
  ) {
    await event.platform.server.upgrade(event.platform.request);
    return new Response(null, { status: 101 });
  }

  return resolve(event);
};

export const websocket: Bun.WebSocketHandler<undefined> = {
  async open(ws) {
    console.log('WebSocket opened');
    ws.send('Slava Ukraїni');
  },
  message(ws, message) {
    console.log('WebSocket message received');
    ws.send(message);
  },
  close(ws) {
    console.log('WebSocket closed');
  },
};

For detailed documentation, examples, and advanced usage patterns, visit the WebSocket example README.

:desktop_computer: Environment variables

Bun automatically reads configuration from .env.local, .env.development and .env

For production deployments, set these deliberately rather than relying on local defaults:

• ORIGIN, or the trusted proxy header pair PROTOCOL_HEADER and HOST_HEADER.
• BODY_SIZE_LIMIT, sized for the largest legitimate request body your app accepts.
• IDLE_TIMEOUT, sized for your traffic pattern and reverse-proxy timeout.
• ADDRESS_HEADER and XFF_DEPTH only when the app is behind trusted proxies.
• SOCKET_PATH only when serving through a local reverse proxy over a Unix socket.

When serving behind nginx, a CDN, or a load balancer, terminate TLS and rate-limit request floods at the proxy layer. The Bun server should receive sanitized Host, protocol, forwarding, and client-address headers from infrastructure you control.

PORT and HOST

By default, the server will accept connections on 0.0.0.0 using port 3000. These can be customized with the PORT and HOST environment variables:

HOST=127.0.0.1 PORT=4000 bun build/index.js

SOCKET_PATH

Instead of using TCP/IP connections, you can configure the server to listen on a Unix domain socket by setting the SOCKET_PATH environment variable:

SOCKET_PATH=/tmp/sveltekit.sock bun build/index.js

When SOCKET_PATH is set, the server will ignore the HOST and PORT settings and use the Unix socket instead. This is useful for deployment behind reverse proxies like nginx.

ORIGIN, PROTOCOL_HEADER and HOST_HEADER

HTTP doesn't give SvelteKit a reliable way to know the URL that is currently being requested. The simplest way to tell SvelteKit where the app is being served is to set the ORIGIN environment variable:

ORIGIN=https://my.site bun build/index.js

With this, a request for the /stuff pathname will correctly resolve to https://my.site/stuff. Alternatively, you can specify headers that tell SvelteKit about the request protocol and host, from which it can construct the origin URL:

PROTOCOL_HEADER=x-forwarded-proto HOST_HEADER=x-forwarded-host bun build/index.js

x-forwarded-proto and x-forwarded-host are de facto standard headers that forward the original protocol and host if you're using a reverse proxy (think load balancers and CDNs). You should only set these variables if your server is behind a trusted reverse proxy; otherwise, it'd be possible for clients to spoof these headers.

ADDRESS_HEADER and XFF_DEPTH

The RequestEvent object passed to hooks and endpoints includes an event.clientAddress property representing the client's IP address. Bun.js haven't got functionality to get client's IP address, so SvelteKit will receive 127.0.0.1 or if your server is behind one or more proxies (such as a load balancer), you can get an IP address from headers, so we need to specify an ADDRESS_HEADER to read the address from:

ADDRESS_HEADER=True-Client-IP bun build/index.js

Headers can easily be spoofed. As with PROTOCOL_HEADER and HOST_HEADER, you should know what you're doing before setting these. If the ADDRESS_HEADER is X-Forwarded-For, the header value will contain a comma-separated list of IP addresses. The XFF_DEPTH environment variable should specify how many trusted proxies sit in front of your server. E.g. if there are three trusted proxies, proxy 3 will forward the addresses of the original connection and the first two proxies:

<client address>, <proxy 1 address>, <proxy 2 address>

Some guides will tell you to read the left-most address, but this leaves you vulnerable to spoofing:

<spoofed address>, <client address>, <proxy 1 address>, <proxy 2 address>

Instead, we read from the right, accounting for the number of trusted proxies. In this case, we would use XFF_DEPTH=3.

If you need to read the left-most address instead (and don't care about spoofing) — for example, to offer a geolocation service, where it's more important for the IP address to be real than trusted, you can do so by inspecting the x-forwarded-for header within your app.

:white_check_mark: Production verification

This repository includes checks for the adapter and the bundled static file server:

bun run build
bunx tsc --noEmit
bun run coverage:check
bun run test:adapter
bun run load:adapter
bun run package:dry-run
bun run smoke:nginx
bun audit

test:adapter builds disposable SvelteKit apps with @sveltejs/[email protected] and the current compatible SvelteKit 2.x release. It verifies SSR, static assets, prerendering, base paths, body limits, trusted proxy headers, WebSocket upgrades, scanner-style requests, and a concurrent request pass.

load:adapter runs the same runtime fixture with a larger request count. Tune it with ADAPTER_LOAD_REQUESTS, ADAPTER_LOAD_CONCURRENCY, and KIT_MATRIX.

Publishing

This package is published as @kimmio/svelte-adapter-bun.

Before publishing, authenticate npm and make sure the account can publish to the @kimmio scope:

npm logout
npm login --registry=https://registry.npmjs.org/
npm whoami

bun run publish:npm -- --dry-run
bun run publish:npm -- --tag latest
bun run publish:npm -- --tag latest --otp 123456

publish:npm checks npm authentication and @kimmio scope access before real publishes. It then runs the production verification suite, checks that LICENSE and NOTICE are present in the npm tarball, and calls npm publish --access public. Automatic npm provenance is enabled when the script detects supported CI OIDC credentials; local publishes intentionally skip provenance because npm cannot generate it outside a supported provider. Use --provenance to force provenance or --no-provenance to disable it explicitly.

Legal Notice

This package is a Kimmio-maintained MIT-licensed fork of svelte-adapter-bun. The original copyright notice for Volodymyr Palamar is retained in LICENSE, and fork attribution is recorded in NOTICE.

License

MIT © Volodymyr Palamar, with Kimmio modifications.