Skip to content

Commit 2e27a3e

Browse files
benmccannbenmccann
authored
Merge branch 'main' into patch-1
2 parents e647e04 + dfb4b9e commit 2e27a3e

File tree

161 files changed

+2572
-2675
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

161 files changed

+2572
-2675
lines changed

‎.changeset/afraid-scissors-own.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@sveltejs/enhanced-img': minor
3+
---
4+
5+
feat: add validation to ensure plugin occurs in correct order

‎README.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ Web development, streamlined. Read the [documentation](https://svelte.dev/docs/k
1111
| [@sveltejs/kit](packages/kit) | [Changelog](packages/kit/CHANGELOG.md) |
1212
| [@sveltejs/adapter-auto](packages/adapter-auto) | [Changelog](packages/adapter-auto/CHANGELOG.md) |
1313
| [@sveltejs/adapter-cloudflare](packages/adapter-cloudflare) | [Changelog](packages/adapter-cloudflare/CHANGELOG.md) |
14-
| [@sveltejs/adapter-cloudflare-workers](packages/adapter-cloudflare-workers) | [Changelog](packages/adapter-cloudflare-workers/CHANGELOG.md) |
1514
| [@sveltejs/adapter-netlify](packages/adapter-netlify) | [Changelog](packages/adapter-netlify/CHANGELOG.md) |
1615
| [@sveltejs/adapter-node](packages/adapter-node) | [Changelog](packages/adapter-node/CHANGELOG.md) |
1716
| [@sveltejs/adapter-static](packages/adapter-static) | [Changelog](packages/adapter-static/CHANGELOG.md) |

‎documentation/docs/10-getting-started/30-project-structure.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ The `src` directory contains the meat of your project. Everything except `src/ro
5555
- `hooks.server.js` contains your server [hooks](hooks)
5656
- `service-worker.js` contains your [service worker](service-workers)
5757

58-
(Whether the project contains `.js` or `.ts` files depends on whether you opt to use TypeScript when you create your project. You can switch between JavaScript and TypeScript in the documentation using the toggle at the bottom of this page.)
58+
(Whether the project contains `.js` or `.ts` files depends on whether you opt to use TypeScript when you create your project.)
5959

6060
If you added [Vitest](https://vitest.dev) when you set up your project, your unit tests will live in the `src` directory with a `.test.js` extension.
6161

‎documentation/docs/20-core-concepts/10-routing.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -277,7 +277,7 @@ Like `+layout.js`, `+layout.server.js` can export [page options](page-options)
277277

278278
## +server
279279

280-
As well as pages, you can define routes with a `+server.js` file (sometimes referred to as an 'API route' or an 'endpoint'), which gives you full control over the response. Your `+server.js` file exports functions corresponding to HTTP verbs like `GET`, `POST`, `PATCH`, `PUT`, `DELETE`, `OPTIONS`, and `HEAD` that take a `RequestEvent` argument and return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object.
280+
As well as pages, you can define routes with a `+server.js` file (sometimes referred to as an 'API route' or an 'endpoint'), which gives you full control over the response. Your `+server.js` file exports functions corresponding to HTTP verbs like `GET`, `POST`, `PATCH`, `PUT`, `DELETE`, `OPTIONS`, and `HEAD` that take a [`RequestEvent`](@sveltejs-kit#RequestEvent) argument and return a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object.
281281

282282
For example we could create an `/api/random-number` route with a `GET` handler:
283283

‎documentation/docs/25-build-and-deploy/20-adapters.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ Before you can deploy your SvelteKit app, you need to _adapt_ it for your deploy
66

77
Official adapters exist for a variety of platforms — these are documented on the following pages:
88

9-
- [`@sveltejs/adapter-cloudflare`](adapter-cloudflare) for Cloudflare Pages
10-
- [`@sveltejs/adapter-cloudflare-workers`](adapter-cloudflare-workers) for Cloudflare Workers
9+
- [`@sveltejs/adapter-cloudflare`](adapter-cloudflare) for Cloudflare Workers and Cloudflare Pages
1110
- [`@sveltejs/adapter-netlify`](adapter-netlify) for Netlify
1211
- [`@sveltejs/adapter-node`](adapter-node) for Node servers
1312
- [`@sveltejs/adapter-static`](adapter-static) for static site generation (SSG)

‎documentation/docs/25-build-and-deploy/40-adapter-node.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Development dependencies will be bundled into your app using [Rollup](https://ro
3434

3535
### Compressing responses
3636

37-
You will typically want to compress responses coming from the server. If you are already deploying your server behind a reverse proxy for SSL or load balancing, it typically results in better performance to also handle compression at that layer since Node.js is single-threaded.
37+
You will typically want to compress responses coming from the server. If you're already deploying your server behind a reverse proxy for SSL or load balancing, it typically results in better performance to also handle compression at that layer since Node.js is single-threaded.
3838

3939
However, if you're building a [custom server](#Custom-server) and do want to add a compression middleware there, note that we would recommend using [`@polka/compression`](https://www.npmjs.com/package/@polka/compression) since SvelteKit streams responses and the more popular `compression` package does not support streaming and may cause errors when used.
4040

@@ -101,7 +101,7 @@ If `adapter-node` can't correctly determine the URL of your deployment, you may
101101
102102
### `ADDRESS_HEADER` and `XFF_DEPTH`
103103

104-
The [RequestEvent](@sveltejs-kit#RequestEvent) object passed to hooks and endpoints includes an `event.getClientAddress()` function that returns the client's IP address. By default this is the connecting `remoteAddress`. If your server is behind one or more proxies (such as a load balancer), this value will contain the innermost proxy's IP address rather than the client's, so we need to specify an `ADDRESS_HEADER` to read the address from:
104+
The [`RequestEvent`](@sveltejs-kit#RequestEvent) object passed to hooks and endpoints includes an `event.getClientAddress()` function that returns the client's IP address. By default this is the connecting `remoteAddress`. If your server is behind one or more proxies (such as a load balancer), this value will contain the innermost proxy's IP address rather than the client's, so we need to specify an `ADDRESS_HEADER` to read the address from:
105105

106106
```
107107
ADDRESS_HEADER=True-Client-IP node build

‎documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md

Lines changed: 117 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,39 @@
11
---
2-
title: Cloudflare Pages
2+
title: Cloudflare
33
---
44

5-
To deploy to [Cloudflare Pages](https://pages.cloudflare.com/), use [`adapter-cloudflare`](https://github.com/sveltejs/kit/tree/main/packages/adapter-cloudflare).
5+
To deploy to [Cloudflare Workers](https://workers.cloudflare.com/) or [Cloudflare Pages](https://pages.cloudflare.com/), use [`adapter-cloudflare`](https://github.com/sveltejs/kit/tree/main/packages/adapter-cloudflare).
66

7-
This adapter will be installed by default when you use [`adapter-auto`](adapter-auto). If you plan on staying with Cloudflare Pages, you can switch from [`adapter-auto`](adapter-auto) to using this adapter directly so that `event.platform` is emulated during local development, type declarations are automatically applied, and the ability to set Cloudflare-specific options is provided.
7+
This adapter will be installed by default when you use [`adapter-auto`](adapter-auto). If you plan on staying with Cloudflare, you can switch from [`adapter-auto`](adapter-auto) to using this adapter directly so that `event.platform` is emulated during local development, type declarations are automatically applied, and the ability to set Cloudflare-specific options is provided.
88

99
## Comparisons
1010

11-
- `adapter-cloudflare` – supports all SvelteKit features; builds for [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/)
12-
- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for Cloudflare Workers
13-
- `adapter-static` – only produces client-side static assets; compatible with Cloudflare Pages
11+
- `adapter-cloudflare` – supports all SvelteKit features; builds for Cloudflare Workers Static Assets and Cloudflare Pages
12+
- `adapter-cloudflare-workers` – deprecated. Supports all SvelteKit features; builds for Cloudflare Workers Sites
13+
- `adapter-static` – only produces client-side static assets; compatible with Cloudflare Workers Static Assets and Cloudflare Pages
1414

1515
## Usage
1616

1717
Install with `npm i -D @sveltejs/adapter-cloudflare`, then add the adapter to your `svelte.config.js`:
1818

1919
```js
20-
// @errors: 2307
2120
/// file: svelte.config.js
2221
import adapter from '@sveltejs/adapter-cloudflare';
2322

2423
export default {
2524
kit: {
2625
adapter: adapter({
2726
// See below for an explanation of these options
28-
routes: {
29-
include: ['/*'],
30-
exclude: ['<all>']
31-
},
27+
config: undefined,
3228
platformProxy: {
3329
configPath: undefined,
3430
environment: undefined,
3531
persist: undefined
32+
},
33+
fallback: 'plaintext',
34+
routes: {
35+
include: ['/*'],
36+
exclude: ['<all>']
3637
}
3738
})
3839
}
@@ -41,9 +42,31 @@ export default {
4142

4243
## Options
4344

45+
### config
46+
47+
Path to your [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/). If you would like to use a Wrangler configuration filename other than `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml` you can specify it using this option.
48+
49+
### platformProxy
50+
51+
Preferences for the emulated `platform.env` local bindings. See the [getPlatformProxy](https://developers.cloudflare.com/workers/wrangler/api/#parameters-1) Wrangler API documentation for a full list of options.
52+
53+
### fallback
54+
55+
Whether to render a plaintext 404.html page or a rendered SPA fallback page for non-matching asset requests.
56+
57+
For Cloudflare Workers, the default behaviour is to return a null-body 404-status response for non-matching assets requests. However, if the [`assets.not_found_handling`](https://developers.cloudflare.com/workers/static-assets/routing/#2-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.
58+
59+
For Cloudflare Pages, this page will only be served when a request that matches an entry in `routes.exclude` fails to match an asset.
60+
61+
Most of the time `plaintext` is sufficient, but if you are using `routes.exclude` to manually
62+
exclude a set of prerendered pages without exceeding the 100 route limit, you may wish to
63+
use `spa` instead to avoid showing an unstyled 404 page to users.
64+
65+
See Cloudflare Pages' [Not Found behaviour](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior) for more info.
66+
4467
### routes
4568

46-
Allows you to customise the [`_routes.json`](https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file) file generated by `adapter-cloudflare`.
69+
Only for Cloudflare Pages. Allows you to customise the [`_routes.json`](https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file) file generated by `adapter-cloudflare`.
4770

4871
- `include` defines routes that will invoke a function, and defaults to `['/*']`
4972
- `exclude` defines routes that will _not_ invoke a function — this is a faster and cheaper way to serve your app's static assets. This array can include the following special values:
@@ -54,25 +77,55 @@ Allows you to customise the [`_routes.json`](https://developers.cloudflare.com/p
5477

5578
You can have up to 100 `include` and `exclude` rules combined. Generally you can omit the `routes` options, but if (for example) your `<prerendered>` paths exceed that limit, you may find it helpful to manually create an `exclude` list that includes `'/articles/*'` instead of the auto-generated `['/articles/foo', '/articles/bar', '/articles/baz', ...]`.
5679

57-
### platformProxy
80+
## Cloudflare Workers
5881

59-
Preferences for the emulated `platform.env` local bindings. See the [getPlatformProxy](https://developers.cloudflare.com/workers/wrangler/api/#parameters-1) Wrangler API documentation for a full list of options.
82+
### Basic configuration
6083

61-
## Deployment
84+
When building for Cloudflare Workers, this adapter expects to find a [Wrangler configuration file](https://developers.cloudflare.com/workers/configuration/sites/configuration/) in the project root. It should look something like this:
85+
86+
```jsonc
87+
/// file: wrangler.jsonc
88+
{
89+
"name": "<any-name-you-want>",
90+
"main": ".svelte-kit/cloudflare/_worker.js",
91+
"compatibility_date": "2025-01-01",
92+
"assets": {
93+
"binding": "ASSETS",
94+
"directory": ".svelte-kit/cloudflare",
95+
}
96+
}
97+
```
98+
99+
### Deployment
100+
101+
Please follow the [framework guide](https://developers.cloudflare.com/workers/frameworks/framework-guides/svelte/) for Cloudflare Workers to begin.
102+
103+
## Cloudflare Pages
104+
105+
### Deployment
62106

63107
Please follow the [Get Started Guide](https://developers.cloudflare.com/pages/get-started/) for Cloudflare Pages to begin.
64108

65-
When configuring your project settings, you must use the following settings:
109+
If you're using the [Git integration](https://developers.cloudflare.com/pages/get-started/git-integration/), your build settings should look like this:
66110

67111
- **Framework preset** – SvelteKit
68112
- **Build command** – `npm run build` or `vite build`
69113
- **Build output directory** – `.svelte-kit/cloudflare`
70114

115+
71116
Once configured, go to the **Runtime** section of your project settings, and add the `nodejs_als` compability flag to enable the [Node.js AsyncLocalStorage](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#nodejs-asynclocalstorage).
72117

118+
### Further reading
119+
120+
You may wish to refer to [Cloudflare's documentation for deploying a SvelteKit site on Cloudflare Pages](https://developers.cloudflare.com/pages/framework-guides/deploy-a-svelte-kit-site/).
121+
122+
### Notes
123+
124+
Functions contained in the [`/functions` directory](https://developers.cloudflare.com/pages/functions/routing/) at the project's root will _not_ be included in the deployment. Instead, functions should be implemented as [server endpoints](routing#server) in your SvelteKit app, which is compiled to a [single `_worker.js` file](https://developers.cloudflare.com/pages/functions/advanced-mode/).
125+
73126
## Runtime APIs
74127

75-
The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object contains your project's [bindings](https://developers.cloudflare.com/pages/functions/bindings/), which consist of KV/DO namespaces, etc. It is passed to SvelteKit via the `platform` property, along with [`context`](https://developers.cloudflare.com/workers/runtime-apis/context/), [`caches`](https://developers.cloudflare.com/workers/runtime-apis/cache/), and [`cf`](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties), meaning that you can access it in hooks and endpoints:
128+
The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object contains your project's [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/), which consist of KV/DO namespaces, etc. It is passed to SvelteKit via the `platform` property, along with [`context`](https://developers.cloudflare.com/workers/runtime-apis/context/), [`caches`](https://developers.cloudflare.com/workers/runtime-apis/cache/), and [`cf`](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties), meaning that you can access it in hooks and endpoints:
76129

77130
```js
78131
// @errors: 7031
@@ -103,26 +156,20 @@ declare global {
103156
export {};
104157
```
105158

106-
### Testing Locally
107-
108-
Cloudflare Workers specific values in the `platform` property are emulated during dev and preview modes. Local [bindings](https://developers.cloudflare.com/pages/functions/bindings/) are created based on your [Wrangler configuration file](https://developers.cloudflare.com/pages/functions/wrangler-configuration/#local-development) and are used to populate `platform.env` during development and preview. Use the adapter config [`platformProxy` option](#Options-platformProxy) to change your preferences for the bindings.
159+
### Testing locally
109160

110-
For testing the build, you should use [Wrangler](https://developers.cloudflare.com/workers/wrangler/) **version 3**. Once you have built your site, run `wrangler pages dev .svelte-kit/cloudflare --compatibility-flag=nodejs_als`.
161+
Cloudflare specific values in the `platform` property are emulated during dev and preview modes. Local [bindings](https://developers.cloudflare.com/workers/wrangler/configuration/#bindings) are created based on your [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/) and are used to populate `platform.env` during development and preview. Use the adapter config [`platformProxy` option](#Options-platformProxy) to change your preferences for the bindings.
111162

112-
## Notes
163+
For testing the build, you should use [Wrangler](https://developers.cloudflare.com/workers/wrangler/) **version 4**. Once you have built your site, run `wrangler dev .svelte-kit/cloudflare --compatibility-flag=nodejs_als` if you're testing for Cloudflare Workers or `wrangler pages dev .svelte-kit/cloudflare` for Cloudflare Pages.
113164

114-
Functions contained in the [`/functions` directory](https://developers.cloudflare.com/pages/functions/routing/) at the project's root will _not_ be included in the deployment. Instead, functions should be implemented as [server endpoints](routing#server) in your SvelteKit app, which is compiled to a [single `_worker.js` file](https://developers.cloudflare.com/pages/functions/advanced-mode/).
165+
## Headers and redirects
115166

116-
The [`_headers`](https://developers.cloudflare.com/pages/configuration/headers/) and [`_redirects`](https://developers.cloudflare.com/pages/configuration/redirects/) files specific to Cloudflare Pages can be used for static asset responses (like images) by putting them into the `/static` folder.
167+
The [`_headers`](https://developers.cloudflare.com/pages/configuration/headers/) and [`_redirects`](https://developers.cloudflare.com/pages/configuration/redirects/) files, specific to Cloudflare, can be used for static asset responses (like images) by putting them into the project root folder.
117168

118169
However, they will have no effect on responses dynamically rendered by SvelteKit, which should return custom headers or redirect responses from [server endpoints](routing#server) or with the [`handle`](hooks#Server-hooks-handle) hook.
119170

120171
## Troubleshooting
121172

122-
### Further reading
123-
124-
You may wish to refer to [Cloudflare's documentation for deploying a SvelteKit site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-svelte-kit-site/).
125-
126173
### Node.js compatibility
127174

128175
If you would like to enable [Node.js compatibility](https://developers.cloudflare.com/workers/runtime-apis/nodejs/), you can add the `nodejs_compat` compatibility flag to your Wrangler configuration file:
@@ -141,3 +188,45 @@ When deploying your application, the server generated by SvelteKit is bundled in
141188
### Accessing the file system
142189

143190
You can't use `fs` in Cloudflare Workers — you must [prerender](page-options#prerender) the routes in question.
191+
192+
## Migrating from Workers Sites
193+
194+
Cloudflare no longer recommends using [Workers Sites](https://developers.cloudflare.com/workers/configuration/sites/configuration/) and instead recommends using [Workers Static Assets](https://developers.cloudflare.com/workers/static-assets/). To migrate, replace `@sveltejs/adapter-cloudflare-workers` with `@sveltejs/adapter-cloudflare` and remove all `site` configuration settings from your Wrangler configuration file, then add the `assets.directory` and `assets.binding` configuration settings:
195+
196+
### svelte.config.js
197+
198+
```js
199+
/// file: svelte.config.js
200+
---import adapter from '@sveltejs/adapter-cloudflare-workers';---
201+
+++import adapter from '@sveltejs/adapter-cloudflare';+++
202+
203+
export default {
204+
kit: {
205+
adapter: adapter()
206+
}
207+
};
208+
```
209+
210+
### wrangler.toml
211+
212+
```toml
213+
/// file: wrangler.toml
214+
---site.bucket = ".cloudflare/public"---
215+
+++assets.directory = ".cloudflare/public"
216+
assets.binding = "ASSETS"+++
217+
```
218+
219+
### wrangler.jsonc
220+
221+
```jsonc
222+
/// file: wrangler.jsonc
223+
{
224+
--- "site": {
225+
"bucket": ".cloudflare/public"
226+
},---
227+
+++ "assets": {
228+
"directory": ".cloudflare/public",
229+
"binding": "ASSETS"
230+
}+++
231+
}
232+
```

0 commit comments

Comments
 (0)