0
# SvelteKit Adapter for Vercel
1

2
The SvelteKit Adapter for Vercel enables seamless deployment of SvelteKit applications to the Vercel platform. It handles build process transformation, serverless function generation, and static asset optimization required for Vercel's deployment infrastructure, with automatic configuration for serverless architecture, edge functions, and ISR (Incremental Static Regeneration).
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
import adapter from "@sveltejs/adapter-vercel";
15
```
16

17
For CommonJS:
18

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

23
## Basic Usage
24

25
Configure the adapter in your `svelte.config.js`:
26

27
```javascript
28
import adapter from "@sveltejs/adapter-vercel";
29

30
export default {
31
  kit: {
32
    adapter: adapter()
33
  }
34
};
35
```
36

37
With configuration options:
38

39
```javascript
40
import adapter from "@sveltejs/adapter-vercel";
41

42
export default {
43
  kit: {
44
    adapter: adapter({
45
      runtime: "nodejs20.x",
46
      regions: ["iad1"],
47
      memory: 512,
48
      maxDuration: 30
49
    })
50
  }
51
};
52
```
53

54
## Architecture
55

56
The adapter transforms SvelteKit applications for Vercel deployment by:
57

58
- **Build Transformation**: Converts SvelteKit output into Vercel Build Output API format
59
- **Function Generation**: Creates serverless or edge functions based on configuration
60
- **Static Asset Handling**: Optimizes and deploys static assets with proper caching headers
61
- **Route Configuration**: Maps SvelteKit routes to Vercel's routing system
62
- **Bundle Optimization**: Uses Vercel's Node File Trace (NFT) for minimal bundle sizes
63

64
## Capabilities
65

66
### Main Adapter Function
67

68
Primary adapter factory function that creates a Vercel adapter instance for SvelteKit configuration.
69

70
```typescript { .api }
71
function adapter(config?: Config): Adapter;
72

73
// Main configuration type
74
type Config = (EdgeConfig | ServerlessConfig) & {
75
  images?: ImagesConfig;
76
};
77

78
// Adapter type from @sveltejs/kit
79
interface Adapter {
80
  name: string;
81
  adapt(builder: any): Promise<void>;
82
  supports?: {
83
    read?: ({ config, route }: { config: any; route: any }) => boolean;
84
    instrumentation?: () => boolean;
85
  };
86
}
87
```
88

89
[Adapter Configuration](./configuration.md)
90

91
### Configuration Types
92

93
Type definitions for adapter configuration including serverless, edge, and image optimization settings.
94

95
```typescript { .api }
96
interface ServerlessConfig {
97
  runtime?: `nodejs${number}.x`;
98
  regions?: string[];
99
  maxDuration?: number;
100
  memory?: number;
101
  split?: boolean;
102
  isr?: {
103
    expiration: number | false;
104
    bypassToken?: string;
105
    allowQuery?: string[] | undefined;
106
  } | false;
107
}
108

109
/**
110
 * @deprecated Edge runtime configuration is deprecated
111
 * Will be removed in a future version of adapter-vercel
112
 */
113
interface EdgeConfig {
114
  runtime?: 'edge';
115
  regions?: string[] | 'all';
116
  external?: string[];
117
  split?: boolean;
118
}
119

120
interface ImagesConfig {
121
  sizes: number[];
122
  domains: string[];
123
  remotePatterns?: RemotePattern[];
124
  minimumCacheTTL?: number;
125
  formats?: ImageFormat[];
126
  dangerouslyAllowSVG?: boolean;
127
  contentSecurityPolicy?: string;
128
  contentDispositionType?: string;
129
}
130

131
interface RemotePattern {
132
  protocol?: 'http' | 'https';
133
  hostname: string;
134
  port?: string;
135
  pathname?: string;
136
}
137

138
type ImageFormat = 'image/avif' | 'image/webp';
139
```
140

141
[Configuration Reference](./configuration.md)
142

143
### Utility Functions
144

145
Helper functions for route processing and pattern conversion used internally by the adapter.
146

147
```typescript { .api }
148
function get_pathname(route: RouteDefinition<any>): string;
149
function pattern_to_src(pattern: string): string;
150

151
// Route definition type from @sveltejs/kit
152
interface RouteDefinition<Config = any> {
153
  id: string;
154
  pattern: RegExp;
155
  segments: Array<{
156
    content: string;
157
    dynamic: boolean;
158
    rest: boolean;
159
  }>;
160
  methods: string[];
161
  prerender?: boolean | 'auto';
162
  config?: Config;
163
}
164
```
165

166
[Utilities](./utilities.md)
167

168
## Runtime Detection and Error Handling
169

170
The adapter automatically detects and validates runtime environments to ensure compatibility:
171

172
### Automatic Runtime Detection
173

174
When no `runtime` is specified, the adapter automatically selects the appropriate Node.js runtime:
175

176
```typescript { .api }
177
// Automatic runtime detection based on build environment
178
adapter(); // Uses build environment's Node.js version
179

180
// Equivalent to:
181
adapter({
182
  runtime: "nodejs20.x" // (example - actual version depends on build env)
183
});
184
```
185

186
**Detection Logic:**
187
- Uses the Node.js version from the build environment  
188
- Only supports even-numbered Node.js versions (18, 20, 22, etc.)
189
- Validates version compatibility with Vercel platform
190

191
### Common Validation Errors
192

193
The adapter performs several validation checks and provides helpful error messages:
194

195
#### 1. Unsupported Node.js Version
196
```javascript
197
// ❌ Error: Building with Node.js 17 (odd version)
198
// Error: "Unsupported Node.js version: v17.x.x. Please use an even-numbered Node version"
199

200
// ❌ Error: Building with Node.js 16 (too old)  
201
// Error: "Building locally with unsupported Node.js version: v16.x.x. Please use Node 18, 20 or 22"
202
```
203

204
#### 2. Legacy Edge Configuration
205
```javascript  
206
// ❌ Error: Using deprecated edge syntax
207
adapter({ edge: true });
208
// Error: "{ edge: true } has been removed in favour of { runtime: 'edge' }"
209
```
210

211
#### 3. SvelteKit Version Compatibility
212
```javascript
213
// ❌ Error: Using adapter-vercel 2.x+ with old SvelteKit
214
// Error: "@sveltejs/adapter-vercel >=2.x requires @sveltejs/kit version 1.5 or higher"
215
```
216

217
#### 4. Runtime-Specific Feature Conflicts
218
```javascript
219
// ❌ Error: ISR with edge runtime
220
adapter({
221
  runtime: "edge",
222
  isr: { expiration: 300 }
223
});
224
// Error: "Routes using `isr` must use a Node.js runtime (for example 'nodejs20.x')"
225
```
226

227
### Troubleshooting Guide
228

229
**Build Environment Issues:**
230
- Ensure you're using an even-numbered Node.js version (18, 20, 22)
231
- Update your local Node.js version to match supported versions
232
- Check your CI/CD environment's Node.js configuration
233

234
**Runtime Configuration:**
235
- Use `nodejs20.x` instead of deprecated `edge` runtime for new projects
236
- Specify explicit runtime if automatic detection fails
237
- Ensure ISR features only use Node.js runtimes
238

239
**Version Compatibility:**
240
- Update `@sveltejs/kit` to version 1.5 or higher for adapter-vercel 2.x+
241
- Check peer dependency requirements in package.json