0
# Adapter Configuration
1

2
Configuration options and main adapter factory function for customizing the build process and deployment behavior on Cloudflare infrastructure.
3

4
## Capabilities
5

6
### Adapter Factory Function
7

8
Creates a SvelteKit adapter configured for Cloudflare deployment with customizable options.
9

10
```typescript { .api }
11
import { Adapter } from '@sveltejs/kit';
12
import { GetPlatformProxyOptions } from 'wrangler';
13

14
/**
15
 * Creates a SvelteKit adapter for Cloudflare deployment
16
 * @param options - Configuration options for the adapter
17
 * @returns SvelteKit Adapter instance
18
 */
19
function adapter(options?: AdapterOptions): Adapter;
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
// Basic usage with default settings
26
import adapter from "@sveltejs/adapter-cloudflare";
27

28
export default {
29
  kit: {
30
    adapter: adapter()
31
  }
32
};
33

34
// With custom configuration
35
export default {
36
  kit: {
37
    adapter: adapter({
38
      config: './custom-wrangler.toml',
39
      fallback: 'spa',
40
      routes: {
41
        include: ['/*'],
42
        exclude: ['<all>']
43
      }
44
    })
45
  }
46
};
47
```
48

49
### Configuration Options
50

51
Interface defining all available configuration options for the adapter.
52

53
```typescript { .api }
54
interface AdapterOptions {
55
  /**
56
   * Path to your Wrangler configuration file
57
   * @see https://developers.cloudflare.com/workers/wrangler/configuration/
58
   */
59
  config?: string;
60
  
61
  /**
62
   * Whether to render a plaintext 404.html page or a rendered SPA fallback page
63
   * for non-matching asset requests.
64
   *
65
   * For Cloudflare Workers, the default behaviour is to return a null-body
66
   * 404-status response for non-matching assets requests. However, if the
67
   * assets.not_found_handling Wrangler configuration setting is set to "404-page",
68
   * this page will be served if a request fails to match an asset. If 
69
   * assets.not_found_handling is set to "single-page-application", the adapter 
70
   * will render a SPA fallback index.html page regardless of the fallback option specified.
71
   *
72
   * For Cloudflare Pages, this page will only be served when a request that
73
   * matches an entry in routes.exclude fails to match an asset.
74
   *
75
   * Most of the time 'plaintext' is sufficient, but if you are using routes.exclude 
76
   * to manually exclude a set of prerendered pages without exceeding the 100 route 
77
   * limit, you may wish to use 'spa' instead to avoid showing an unstyled 404 page 
78
   * to users.
79
   *
80
   * @see https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior
81
   * @default 'plaintext'
82
   */
83
  fallback?: 'plaintext' | 'spa';
84
  
85
  /**
86
   * Only for Cloudflare Pages. Customize the automatically-generated _routes.json file.
87
   * @see https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file
88
   */
89
  routes?: {
90
    /**
91
     * Routes that will be invoked by functions. Accepts wildcards.
92
     * @default ["/*"]
93
     */
94
    include?: string[];
95
    
96
    /**
97
     * Routes that will not be invoked by functions. Accepts wildcards.
98
     * exclude takes priority over include.
99
     * 
100
     * To have the adapter automatically exclude certain things, you can use these placeholders:
101
     * - <build> to exclude build artifacts (files generated by Vite)
102
     * - <files> for the contents of your static directory
103
     * - <prerendered> for prerendered routes
104
     * - <all> to exclude all of the above
105
     * 
106
     * @default ["<all>"]
107
     */
108
    exclude?: string[];
109
  };
110
  
111
  /**
112
   * Config object passed to getPlatformProxy during development and preview.
113
   * @see https://developers.cloudflare.com/workers/wrangler/api/#getplatformproxy
114
   */
115
  platformProxy?: GetPlatformProxyOptions;
116
}
117
```
118

119
### Routes Configuration
120

121
Detailed configuration for Cloudflare Pages routing behavior.
122

123
**Route Limitations:**
124

125
Cloudflare Pages Functions have specific limits for `_routes.json`:
126
- Must contain at least one route in `include`  
127
- Maximum of 100 total routes combined between `include` and `exclude`
128
- If the 100 route limit is exceeded, excess `exclude` rules will be dropped (causing unnecessary function invocations)
129
- Both `include` and `exclude` must be arrays
130
- Manual `_routes.json` files are not allowed - the adapter will throw an error if one exists in your project root
131

132
**Important:** If you have an existing `_routes.json` file, you must remove it and configure routing through the adapter options instead.
133

134
**Route Placeholders:**
135

136
- `<build>` - Excludes build artifacts (files generated by Vite)
137
- `<files>` - Excludes contents of your static directory  
138
- `<prerendered>` - Excludes prerendered routes
139
- `<all>` - Excludes all of the above
140

141
**Usage Examples:**
142

143
```javascript
144
// Custom routing configuration
145
adapter({
146
  routes: {
147
    include: ['/*'],
148
    exclude: [
149
      '<build>',
150
      '<files>',
151
      '/api/static/*',
152
      '/public/*'
153
    ]
154
  }
155
});
156

157
// Minimal function routing
158
adapter({
159
  routes: {
160
    include: ['/api/*', '/auth/*'],
161
    exclude: ['<all>']
162
  }
163
});
164
```
165

166
### Fallback Page Options
167

168
Controls how 404 pages are rendered for non-matching requests.
169

170
**Plaintext Mode (`'plaintext'`):**
171
- Generates a simple "Not Found" text page
172
- Minimal file size and fast response
173
- Suitable for most applications
174

175
**SPA Mode (`'spa'`):**
176
- Renders full SPA fallback index.html page
177
- Maintains styling and application shell
178
- Better for single-page applications with client-side routing
179

180
**Deployment-Specific Behavior:**
181

182
- **Cloudflare Workers**: The default behavior is to return a null-body 404-status response for non-matching assets requests. However, if the `assets.not_found_handling` Wrangler configuration setting is set to `"404-page"`, this page will be served if a request fails to match an asset. If `assets.not_found_handling` is set to `"single-page-application"`, the adapter will render a SPA fallback index.html page regardless of the `fallback` option specified.
183

184
- **Cloudflare Pages**: This page will only be served when a request that matches an entry in `routes.exclude` fails to match an asset.
185

186
**Usage Considerations:**
187

188
Most of the time `plaintext` is sufficient, but if you are using `routes.exclude` to manually exclude a set of prerendered pages without exceeding the 100 route limit, you may wish to use `spa` instead to avoid showing an unstyled 404 page to users.
189

190
```javascript
191
// For SPA applications
192
adapter({
193
  fallback: 'spa'
194
});
195

196
// For traditional server-rendered apps
197
adapter({
198
  fallback: 'plaintext'
199
});
200
```