0
# @sveltejs/adapter-auto
1

2
Automatically chooses the SvelteKit adapter for your current environment, if possible. This adapter analyzes environment variables to detect deployment platforms and automatically installs and configures the appropriate platform-specific adapter.
3

4
## Package Information
5

6
- **Package Name**: @sveltejs/adapter-auto
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install -D @sveltejs/adapter-auto`
10

11
## Core Imports
12

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

17
For CommonJS (not recommended as this is an ESM package):
18

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

23
## Basic Usage
24

25
```javascript
26
// svelte.config.js
27
import adapter from '@sveltejs/adapter-auto';
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
## Architecture
40

41
The adapter uses a detection system with the following components:
42

43
- **Environment Detection**: Analyzes environment variables to identify deployment platforms
44
- **Auto-Installation**: Automatically installs the appropriate platform adapter if not found
45
- **Adapter Delegation**: Passes control to the detected platform-specific adapter
46
- **Fallback Handling**: Provides warnings when no supported environment is detected
47
- **Package Manager Support**: Works with npm, pnpm, yarn, bun, and deno
48

49
## Capabilities
50

51
### Main Adapter Function
52

53
The primary export that creates a SvelteKit adapter with automatic platform detection.
54

55
```javascript { .api }
56
/**
57
 * Creates a SvelteKit adapter that automatically detects the deployment environment
58
 * @returns {Adapter} SvelteKit adapter with auto-detection capabilities
59
 */
60
export default function(): Adapter;
61
```
62

63
### Supported Platform Detection
64

65
The adapter automatically detects these deployment environments using an internal configuration array:
66

67
**Supported Platforms:**
68

69
1. **Vercel**: Detected via `VERCEL` environment variable
70
   - Installs: `@sveltejs/adapter-vercel@5`
71

72
2. **Cloudflare Pages**: Detected via `CF_PAGES` environment variable
73
   - Installs: `@sveltejs/adapter-cloudflare@7`
74

75
3. **Netlify**: Detected via `NETLIFY` environment variable
76
   - Installs: `@sveltejs/adapter-netlify@5`
77

78
4. **Azure Static Web Apps**: Detected via `GITHUB_ACTION_REPOSITORY` === 'Azure/static-web-apps-deploy'
79
   - Installs: `svelte-adapter-azure-swa@0.20`
80

81
5. **AWS via SST**: Detected via `SST` environment variable
82
   - Installs: `svelte-kit-sst@2`
83

84
6. **Google Cloud Run**: Detected via `GCP_BUILDPACKS` environment variable
85
   - Installs: `@sveltejs/adapter-node@5`
86

87
### Package Manager Support
88

89
Supports automatic installation using any of these package managers:
90

91
The adapter uses internal command templates to install adapters with the detected package manager.
92

93
The adapter automatically detects the package manager by looking for lockfiles in this priority order:
94
1. `pnpm-lock.yaml` → pnpm
95
2. `yarn.lock` → yarn  
96
3. `package-lock.json` → npm
97
4. `bun.lockb` or `bun.lock` → bun
98
5. `deno.lock` → deno
99

100
### Error Handling
101

102
The adapter handles several error scenarios:
103

104
1. **Peer Dependency Resolution Errors**: When the target adapter package cannot be found
105
2. **Installation Errors**: When automatic installation of the adapter fails
106
3. **Unsupported Feature Errors**: When attempting to use features not supported by adapter-auto (like the `read` function)
107

108
The adapter includes internal error handling that provides context-aware error messages when unsupported features are used.
109

110
## Types
111

112
```typescript { .api }
113
/**
114
 * SvelteKit Adapter interface - returned by the default export function
115
 */
116
interface Adapter {
117
  /** The name of the adapter, using for logging. Will typically correspond to the package name. */
118
  name: string;
119
  /** This function is called after SvelteKit has built your app. */
120
  adapt(builder: Builder): MaybePromise<void>;
121
  /** Checks called during dev and build to determine whether specific features will work in production with this adapter. */
122
  supports?: {
123
    /** Test support for `read` from `$app/server`. */
124
    read?(details: { config: any; route: { id: string } }): boolean;
125
  };
126
  /** Creates an `Emulator`, which allows the adapter to influence the environment during dev, build and prerendering. */
127
  emulate?(): MaybePromise<Emulator>;
128
}
129

130
/**
131
 * SvelteKit Builder interface (from @sveltejs/kit)
132
 * This object is passed to the `adapt` function of adapters.
133
 * It contains various methods and properties that are useful for adapting the app.
134
 */
135
interface Builder {
136
  /** Print messages to the console. `log.info` and `log.minor` are silent unless Vite's `logLevel` is `info`. */
137
  log: Logger;
138
  /** Remove `dir` and all its contents. */
139
  rimraf(dir: string): void;
140
  /** Create `dir` and any required parent directories. */
141
  mkdirp(dir: string): void;
142

143
  /** The fully resolved Svelte config. */
144
  config: ValidatedConfig;
145
  /** Information about prerendered pages and assets, if any. */
146
  prerendered: Prerendered;
147
  /** An array of all routes (including prerendered) */
148
  routes: RouteDefinition[];
149

150
  /** Find all the assets imported by server files belonging to `routes` */
151
  findServerAssets(routes: RouteDefinition[]): string[];
152
  /** Generate a fallback page for a static webserver to use when no route is matched. Useful for single-page apps. */
153
  generateFallback(dest: string): Promise<void>;
154
  /** Generate a module exposing build-time environment variables as `$env/dynamic/public`. */
155
  generateEnvModule(): void;
156
  /** Generate a server-side manifest to initialise the SvelteKit server with. */
157
  generateManifest(opts: { relativePath: string; routes?: RouteDefinition[] }): string;
158

159
  /** Resolve a path to the `name` directory inside `outDir`, e.g. `/path/to/.svelte-kit/my-adapter`. */
160
  getBuildDirectory(name: string): string;
161
  /** Get the fully resolved path to the directory containing client-side assets, including the contents of your `static` directory. */
162
  getClientDirectory(): string;
163
  /** Get the fully resolved path to the directory containing server-side code. */
164
  getServerDirectory(): string;
165
  /** Get the application path including any configured `base` path, e.g. `my-base-path/_app`. */
166
  getAppPath(): string;
167

168
  /** Write client assets to `dest`. */
169
  writeClient(dest: string): string[];
170
  /** Write prerendered files to `dest`. */
171
  writePrerendered(dest: string): string[];
172
  /** Write server-side code to `dest`. */
173
  writeServer(dest: string): string[];
174
  /** Copy a file or directory. */
175
  copy(
176
    from: string,
177
    to: string,
178
    opts?: {
179
      filter?(basename: string): boolean;
180
      replace?: Record<string, string>;
181
    }
182
  ): string[];
183

184
  /** Compress files in `directory` with gzip and brotli, where appropriate. Generates `.gz` and `.br` files alongside the originals. */
185
  compress(directory: string): Promise<void>;
186
}
187

188
/**
189
 * Logger interface used by Builder.log
190
 */
191
interface Logger {
192
  (msg: string): void;
193
  success(msg: string): void;
194
  error(msg: string): void;
195
  warn(msg: string): void;
196
  minor(msg: string): void;
197
  info(msg: string): void;
198
}
199

200
/**
201
 * A collection of functions that influence the environment during dev, build and prerendering
202
 */
203
interface Emulator {
204
  /** A function that is called with the current route `config` and `prerender` option and returns an `App.Platform` object */
205
  platform?(details: { config: any; prerender: PrerenderOption }): MaybePromise<App.Platform>;
206
}
207

208
/** Helper type for values that may or may not be wrapped in a Promise */
209
type MaybePromise<T> = T | Promise<T>;
210

211
/** Configuration interfaces and other supporting types are imported from @sveltejs/kit */
212
interface ValidatedConfig extends Record<string, any> {}
213
interface Prerendered extends Record<string, any> {}
214
interface RouteDefinition extends Record<string, any> {}
215
type PrerenderOption = boolean | 'auto'
216
```
217

218
## Installation Behavior
219

220
When a supported environment is detected:
221

222
1. **Check for existing adapter**: Attempts to resolve the platform-specific adapter as a peer dependency
223
2. **Auto-install if missing**: If not found, automatically installs the adapter using the detected package manager
224
3. **Import and configure**: Imports the installed adapter and configures it
225
4. **Delegate control**: Passes the build process to the platform-specific adapter
226
5. **Provide feedback**: Logs detected environment and suggests manual installation for better performance
227

228
## Error Messages
229

230
The adapter provides helpful error messages in various scenarios:
231

232
- **Peer dependency resolution**: "Could not resolve peer dependency..."
233
- **Installation failure**: "Could not install [adapter]. Please install it yourself..."
234
- **Unsupported environment**: "Could not detect a supported production environment..."
235
- **Unsupported features**: "The read function imported from $app/server only works in certain environments..."