0
# @sveltejs/adapter-node
1

2
@sveltejs/adapter-node is a SvelteKit adapter that generates a standalone Node.js server for SvelteKit applications. It transforms SvelteKit apps into production-ready Node server builds with support for server-side rendering, API routes, static asset serving, and comprehensive environment configuration.
3

4
## Package Information
5

6
- **Package Name**: @sveltejs/adapter-node
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @sveltejs/adapter-node`
10

11
## Core Imports
12

13
```javascript
14
import adapter from '@sveltejs/adapter-node';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const adapter = require('@sveltejs/adapter-node');
21
```
22

23
## Basic Usage
24

25
```javascript
26
// svelte.config.js
27
import adapter from '@sveltejs/adapter-node';
28

29
/** @type {import('@sveltejs/kit').Config} */
30
const config = {
31
  kit: {
32
    adapter: adapter()
33
  }
34
};
35

36
export default config;
37
```
38

39
With configuration options:
40

41
```javascript
42
// svelte.config.js  
43
import adapter from '@sveltejs/adapter-node';
44

45
/** @type {import('@sveltejs/kit').Config} */
46
const config = {
47
  kit: {
48
    adapter: adapter({
49
      out: 'build',
50
      precompress: true,
51
      envPrefix: 'MY_CUSTOM_'
52
    })
53
  }
54
};
55

56
export default config;
57
```
58

59
## Architecture
60

61
The adapter works by:
62

63
1. **Build Process**: Transforms SvelteKit app into standalone Node.js server
64
2. **Asset Handling**: Generates optimized client assets with optional compression
65
3. **Server Generation**: Creates Node.js server with request handler and lifecycle management
66
4. **Environment Configuration**: Supports extensive environment variable customization
67
5. **Production Deployment**: Outputs production-ready server that can run independently
68

69
The generated server includes:
70
- Static asset serving with caching headers
71
- Server-side rendering (SSR) with SvelteKit integration
72
- Prerendered route handling
73
- Graceful shutdown and socket activation support
74
- Configurable security headers and reverse proxy support
75

76
## Capabilities
77

78
### Adapter Factory Function
79

80
Creates and configures the SvelteKit adapter with optional settings.
81

82
```typescript { .api }
83
/**
84
 * Creates a SvelteKit adapter for Node.js deployment
85
 * @param options - Configuration options for the adapter
86
 * @returns Configured SvelteKit adapter
87
 */
88
export default function adapter(options?: AdapterOptions): Adapter;
89

90
interface AdapterOptions {
91
  /** Output directory for the generated server (default: 'build') */
92
  out?: string;
93
  /** Enable gzip/brotli compression of static assets (default: true) */
94
  precompress?: boolean;
95
  /** Prefix for environment variables (default: '') */
96
  envPrefix?: string;
97
}
98

99
interface Adapter {
100
  name: string;
101
  adapt(builder: Builder): Promise<void>;
102
  supports: {
103
    read(): boolean;
104
    instrumentation(): boolean;
105
  };
106
}
107

108
interface Builder {
109
  log: { minor(message: string): void };
110
  rimraf(path: string): void;
111
  mkdirp(path: string): void;
112
  config: { kit: { paths: { base: string } } };
113
  prerendered: { paths: string[] };
114
  getBuildDirectory(name: string): string;
115
  writeClient(dest: string): void;
116
  writePrerendered(dest: string): void;
117
  writeServer(dest: string): void;
118
  generateManifest(options: { relativePath: string }): string;
119
  compress(path: string): Promise<void>;
120
  copy(from: string, to: string, options?: { replace?: Record<string, string> }): void;
121
  hasServerInstrumentationFile?(): boolean;
122
  instrument?(options: { entrypoint: string; instrumentation: string; module: { exports: string[] } }): void;
123
}
124
```
125

126

127
### Generated Server Environment Variables
128

129
The generated server supports extensive environment variable configuration:
130

131
#### Core Server Configuration
132

133
```typescript { .api }
134
// Server binding configuration
135
SOCKET_PATH?: string;        // Unix socket path (alternative to HOST/PORT)
136
HOST?: string;              // Server host (default: '0.0.0.0') 
137
PORT?: string;              // Server port (default: '3000')
138

139
// Server lifecycle
140
SHUTDOWN_TIMEOUT?: string;   // Graceful shutdown timeout in seconds (default: '30')
141
IDLE_TIMEOUT?: string;      // Idle timeout for socket activation (default: '0')
142

143
// Socket activation (systemd)
144
LISTEN_PID?: string;        // Process ID for socket activation
145
LISTEN_FDS?: string;        // Number of file descriptors for socket activation
146
```
147

148
#### Request Handling Configuration
149

150
```typescript { .api }
151
// Origin and URL configuration
152
ORIGIN?: string;            // Override automatic origin detection
153
BODY_SIZE_LIMIT?: string;   // Request body size limit (default: '512K')
154

155
// Reverse proxy headers
156
XFF_DEPTH?: string;         // X-Forwarded-For header depth (default: '1')
157
ADDRESS_HEADER?: string;    // Custom client address header name
158
PROTOCOL_HEADER?: string;   // Custom protocol header name  
159
HOST_HEADER?: string;       // Custom host header name
160
PORT_HEADER?: string;       // Custom port header name
161
```
162

163
All environment variables (except LISTEN_PID and LISTEN_FDS) can be prefixed using the `envPrefix` option.
164

165
### Type Definitions
166

167
Global platform interface extension for accessing Node.js request object.
168

169
```typescript { .api }
170
declare global {
171
  namespace App {
172
    interface Platform {
173
      /** The original Node.js HTTP request object */
174
      req: import('node:http').IncomingMessage;
175
    }
176
  }
177
}
178
```
179

180
## Deployment
181

182
After building with the adapter, the generated server can be started with:
183

184
```bash
185
node build/index.js
186
```
187

188
The server will log its binding information and accept requests on the configured host and port.
189

190
### Environment Variable Examples
191

192
```bash
193
# Basic configuration
194
HOST=127.0.0.1 PORT=8080 node build/index.js
195

196
# With custom prefix
197
MY_APP_HOST=127.0.0.1 MY_APP_PORT=8080 node build/index.js
198

199
# With reverse proxy headers
200
ADDRESS_HEADER=x-real-ip PROTOCOL_HEADER=x-forwarded-proto node build/index.js
201

202
# With body size limit
203
BODY_SIZE_LIMIT=1M node build/index.js
204

205
# Unix socket
206
SOCKET_PATH=/tmp/app.sock node build/index.js
207
```
208

209
### Graceful Shutdown
210

211
The generated server supports graceful shutdown via SIGTERM and SIGINT signals, with configurable timeout:
212

213
```bash
214
# Custom shutdown timeout (60 seconds)
215
SHUTDOWN_TIMEOUT=60 node build/index.js
216
```
217

218
### Socket Activation
219

220
For systemd socket activation:
221

222
```bash
223
# Systemd will set these automatically
224
LISTEN_PID=1234 LISTEN_FDS=1 node build/index.js
225
```