Configuration

Adapter options

adapter({
  out: 'build',
  precompress: true,
  envPrefix: '',
  healthCheckPath: '/healthz',
  websocket: true // or false, or an options object
})

WebSocket options

Pass an object instead of true for fine-grained control:

adapter({
  websocket: {
    path: '/ws',
    handler: './src/lib/server/websocket.js',
    maxPayloadLength: 16 * 1024,
    idleTimeout: 120,
    maxBackpressure: 1024 * 1024,
    compression: false,
    sendPingsAutomatically: true,
    upgradeTimeout: 10,
    upgradeRateLimit: 10,
    upgradeRateLimitWindow: 10,
    allowedOrigins: 'same-origin'
  }
})

Environment variables

All set at runtime (node build), not build time. If you set envPrefix: 'MY_APP_', all variables are prefixed (e.g. MY_APP_PORT).

Important: PROTOCOL_HEADER, HOST_HEADER, PORT_HEADER, and ADDRESS_HEADER are trusted verbatim. Only set these behind a reverse proxy that overwrites them on every request. If the server is directly internet-facing, use a fixed ORIGIN instead.

Examples

# Simple HTTP
node build

# Custom port
PORT=8080 node build

# Behind nginx
ORIGIN=https://example.com node build

# Behind a proxy with forwarded headers
PROTOCOL_HEADER=x-forwarded-proto HOST_HEADER=x-forwarded-host node build

# Native TLS
SSL_CERT=./cert.pem SSL_KEY=./key.pem node build

# Everything at once
SSL_CERT=./cert.pem SSL_KEY=./key.pem PORT=443 BODY_SIZE_LIMIT=10M SHUTDOWN_TIMEOUT=60 node build

TypeScript setup

Add the platform type to src/app.d.ts:

import type { Platform as AdapterPlatform } from 'svelte-adapter-uws';

declare global {
  namespace App {
    interface Platform extends AdapterPlatform {}
  }
}

export {};

Now event.platform.publish(), event.platform.topic(), etc. are fully typed.

Vite plugin

The Vite plugin is required when using WebSockets. It does two things:

1. Dev mode - spins up a ws WebSocket server alongside Vite’s dev server, so event.platform and the client store work identically to production
2. Production builds - runs your hooks.ws file through Vite’s pipeline so $lib, $env, and $app imports resolve correctly

Without it, event.platform won’t work in dev, and your hooks.ws file won’t be able to import from $lib or use $env variables.

// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import uws from 'svelte-adapter-uws/vite';

export default {
  plugins: [sveltekit(), uws()]
};

Changes to your hooks.ws file are picked up automatically - the plugin reloads the handler on save and closes existing connections so they reconnect with the new code. No dev server restart needed.

Note: The dev server does not enforce allowedOrigins. Origin checks only run in production. A warning is logged at startup as a reminder.

Health check endpoint

The adapter exposes a health check at /healthz by default. Set healthCheckPath to a different path or false to disable:

adapter({
  healthCheckPath: '/healthz' // default
  // healthCheckPath: false   // disable
})

Backpressure and connection limits

These options control how the server handles misbehaving or slow clients at the WebSocket level:

maxPayloadLength (default: 16 KB) - the maximum size of a single incoming WebSocket message. If a client sends a message larger than this, uWS closes the connection immediately (not just the message - the entire connection is dropped). Set this based on the largest message your application expects to receive.

maxBackpressure (default: 1 MB) - the per-connection outbound send buffer. When a client reads slower than the server writes, messages queue up in this buffer. Once it overflows, subsequent send() and publish() calls for that connection silently drop the message. The drain hook fires when the buffer empties again. Lower this if you expect many slow consumers to avoid per-connection memory bloat.

upgradeRateLimit (default: 10 per 10s window) - sliding-window rate limit on WebSocket upgrade requests per client IP. Clients exceeding the limit get a 429 Too Many Requests response. The IP rate map is capped at 10,000 entries with LRU eviction by activity score, so sustained connection floods from many IPs don’t cause unbounded memory growth.

Static file behavior

All static assets (from the client/ and prerendered/ output directories) are loaded once at startup and served directly from RAM. Each response automatically includes:

• Content-Type - detected from the file extension
• Vary: Accept-Encoding - required for correct CDN/proxy caching
• Accept-Ranges: bytes - enables partial content requests
• X-Content-Type-Options: nosniff - prevents MIME-type sniffing
• ETag - derived from modification time and size; enables 304 Not Modified
• Cache-Control: public, max-age=31536000, immutable - for versioned assets under /_app/immutable/
• Cache-Control: no-cache - for all other assets (forces ETag revalidation)

Range requests (HTTP 206): Single byte ranges are supported (bytes=0-499, bytes=-500, bytes=500-). Multi-range requests are served as full 200 responses. Unsatisfiable ranges return 416. When a Range header is present, the response is always served uncompressed so byte offsets are correct. The If-Range header is respected.

Binary downloads: Files with extensions like .zip, .tar, .exe, .dmg, .pkg, .deb, .apk, .iso, .img, .bin automatically receive Content-Disposition: attachment so browsers prompt a download dialog.

Precompression: If precompress: true, brotli (.br) and gzip (.gz) variants are loaded at startup and served when the client’s Accept-Encoding includes br or gzip. Precompressed variants are only used when smaller than the original.

Graceful shutdown

On SIGTERM or SIGINT, the server:

1. Stops accepting new connections
2. Waits for in-flight SSR requests to complete (up to SHUTDOWN_TIMEOUT seconds)
3. Emits a sveltekit:shutdown event on process
4. Exits

process.on('sveltekit:shutdown', async (reason) => {
  console.log(`Shutting down: ${reason}`);
  await db.close();
});

Deployment

• Docker: Use node:22-trixie-slim (glibc >= 2.38 required for the uWS native addon)
• Build: npm run build → node build
• Clustering: Set CLUSTER_WORKERS=auto for multi-core, uses SO_REUSEPORT on Linux
• OS tuning: Increase nofile ulimit to 65536+ for high connection counts

# Production with clustering and TLS
SSL_CERT=./cert.pem SSL_KEY=./key.pem CLUSTER_WORKERS=auto node build