From dc787f79e15263ed8d392895a90296a4502be8ac Mon Sep 17 00:00:00 2001 From: Simon Holthausen Date: Fri, 13 Jan 2023 11:40:40 +0100 Subject: [PATCH 01/23] docs: more build docs Transforming the adapters document into a more general build doc closes #8500 --- .changeset/hungry-singers-tease.md | 10 +++++ .../10-getting-started/40-web-standards.md | 2 +- .../docs/20-core-concepts/20-load.md | 2 +- ...50-adapters.md => 50-building-your-app.md} | 37 ++++++++++++++++++- .../docs/60-appendix/10-migrating.md | 8 ++-- packages/adapter-auto/index.js | 2 +- packages/adapter-cloudflare/README.md | 2 +- packages/adapter-node/README.md | 2 +- packages/adapter-static/README.md | 2 +- .../adapter-static/test/apps/spa/README.md | 2 +- packages/create-svelte/shared/README.md | 2 +- packages/kit/src/core/config/options.js | 2 +- packages/kit/src/exports/vite/index.js | 2 +- packages/kit/types/ambient.d.ts | 2 +- packages/kit/types/index.d.ts | 4 +- sites/kit.svelte.dev/src/hooks.server.js | 3 +- .../src/routes/home/Deployment.svelte | 2 +- 17 files changed, 65 insertions(+), 21 deletions(-) create mode 100644 .changeset/hungry-singers-tease.md rename documentation/docs/20-core-concepts/{50-adapters.md => 50-building-your-app.md} (80%) diff --git a/.changeset/hungry-singers-tease.md b/.changeset/hungry-singers-tease.md new file mode 100644 index 000000000000..e72c9b29f353 --- /dev/null +++ b/.changeset/hungry-singers-tease.md @@ -0,0 +1,10 @@ +--- +'@sveltejs/adapter-auto': patch +'@sveltejs/adapter-cloudflare': patch +'@sveltejs/adapter-node': patch +'@sveltejs/adapter-static': patch +'create-svelte': patch +'@sveltejs/kit': patch +--- + +docs: add more indepth docs on building your app diff --git a/documentation/docs/10-getting-started/40-web-standards.md b/documentation/docs/10-getting-started/40-web-standards.md index a12f534cfae3..d847ccbb486c 100644 --- a/documentation/docs/10-getting-started/40-web-standards.md +++ b/documentation/docs/10-getting-started/40-web-standards.md @@ -4,7 +4,7 @@ title: Web standards Throughout this documentation, you'll see references to the standard [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) that SvelteKit builds on top of. Rather than reinventing the wheel, we _use the platform_, which means your existing web development skills are applicable to SvelteKit. Conversely, time spent learning SvelteKit will help you be a better web developer elsewhere. -These APIs are available in all modern browsers and in many non-browser environments like Cloudflare Workers, Deno and Vercel Edge Functions. During development, and in [adapters](/docs/adapters) for Node-based environments (including AWS Lambda), they're made available via polyfills where necessary (for now, that is — Node is rapidly adding support for more web standards). +These APIs are available in all modern browsers and in many non-browser environments like Cloudflare Workers, Deno and Vercel Edge Functions. During development, and in [adapters](/docs/building-your-app) for Node-based environments (including AWS Lambda), they're made available via polyfills where necessary (for now, that is — Node is rapidly adding support for more web standards). In particular, you'll get comfortable with the following: diff --git a/documentation/docs/20-core-concepts/20-load.md b/documentation/docs/20-core-concepts/20-load.md index 834f4101ccd1..4da80292be46 100644 --- a/documentation/docs/20-core-concepts/20-load.md +++ b/documentation/docs/20-core-concepts/20-load.md @@ -192,7 +192,7 @@ Often the `load` function depends on the URL in one way or another. For this, th An instance of [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL), containing properties like the `origin`, `hostname`, `pathname` and `searchParams` (which contains the parsed query string as a [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object). `url.hash` cannot be accessed during `load`, since it is unavailable on the server. -> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](/docs/adapters#supported-environments-node-js), for example, you may need to configure the adapter in order for the URL to be correct. +> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](/docs/building-your-app#supported-environments-node-js), for example, you may need to configure the adapter in order for the URL to be correct. ### route diff --git a/documentation/docs/20-core-concepts/50-adapters.md b/documentation/docs/20-core-concepts/50-building-your-app.md similarity index 80% rename from documentation/docs/20-core-concepts/50-adapters.md rename to documentation/docs/20-core-concepts/50-building-your-app.md index 9315e47cb709..0e67c98eac9a 100644 --- a/documentation/docs/20-core-concepts/50-adapters.md +++ b/documentation/docs/20-core-concepts/50-building-your-app.md @@ -1,10 +1,43 @@ --- -title: Adapters +title: Building Your App --- +Building a SvelteKit consists of two stages. First the production build is run. This will create a client and a server build which are later consumed by the corresponding environments. [Prerendering](/docs/page-options#prerender) is executed at this stage, if enabled. The second step is to _adapt_ the output to your deployment target using adapters (more on that in the later sections). + +## During the build + +SvelteKit will load your `+page/layout(.server).js` files (and all files they import) for analysis during the build. This could lead to code eagerly running which you want to avoid at that stage. Wrap the code in question with `building` from `$app/environment`: + +```js +/// file: +layout.server.js +// @filename: ambient.d.ts +declare module '$lib/server/database' { + export function setupMyDatabase(): void; +} + +// @filename: index.js +// ---cut--- +import { building } from '$app/environment'; +import { setupMyDatabase } from '$lib/server/database'; + +if (!building) { + setupMyDatabase(); +} + +export const load() { + // ... +} +``` + +## Preview your app + +Run the `preview` script to look at your app locally after the production build is done. Note that this does not yet include adapter-specific adjustments like the [`platform` object](#supported-environments-platform-specific-context). + +## Adapters + Before you can deploy your SvelteKit app, you need to _adapt_ it for your deployment target. Adapters are small plugins that take the built app as input and generate output for deployment. -By default, projects are configured to use `@sveltejs/adapter-auto`, which detects your production environment and selects the appropriate adapter where possible. If your platform isn't (yet) supported, you may need to [install a custom adapter](/docs/adapters#community-adapters) or [write one](/docs/adapters#writing-custom-adapters). +By default, projects are configured to use `@sveltejs/adapter-auto`, which detects your production environment and selects the appropriate adapter where possible. If your platform isn't (yet) supported, you may need to [install a custom adapter](#community-adapters) or [write one](#writing-custom-adapters). > See the [adapter-auto README](https://github.com/sveltejs/kit/tree/master/packages/adapter-auto) for information on adding support for new environments. diff --git a/documentation/docs/60-appendix/10-migrating.md b/documentation/docs/60-appendix/10-migrating.md index 2e04f115c2b7..4bf104cb6726 100644 --- a/documentation/docs/60-appendix/10-migrating.md +++ b/documentation/docs/60-appendix/10-migrating.md @@ -20,14 +20,14 @@ Remove `polka` or `express`, if you're using one of those, and any middleware su ### devDependencies -Remove `sapper` from your `devDependencies` and replace it with `@sveltejs/kit` and whichever [adapter](/docs/adapters) you plan to use (see [next section](/docs/migrating#project-files-configuration)). +Remove `sapper` from your `devDependencies` and replace it with `@sveltejs/kit` and whichever [adapter](/docs/building-your-app) you plan to use (see [next section](/docs/migrating#project-files-configuration)). ### scripts Any scripts that reference `sapper` should be updated: -- `sapper build` should become `vite build` using the Node [adapter](/docs/adapters) -- `sapper export` should become `vite build` using the static [adapter](/docs/adapters) +- `sapper build` should become `vite build` using the Node [adapter](/docs/building-your-app) +- `sapper export` should become `vite build` using the static [adapter](/docs/building-your-app) - `sapper dev` should become `vite dev` - `node __sapper__/build` should become `node build` @@ -39,7 +39,7 @@ The bulk of your app, in `src/routes`, can be left where it is, but several proj Your `webpack.config.js` or `rollup.config.js` should be replaced with a `svelte.config.js`, as documented [here](/docs/configuration). Svelte preprocessor options should be moved to `config.preprocess`. -You will need to add an [adapter](/docs/adapters). `sapper build` is roughly equivalent to [adapter-node](https://github.com/sveltejs/kit/tree/master/packages/adapter-node) while `sapper export` is roughly equivalent to [adapter-static](https://github.com/sveltejs/kit/tree/master/packages/adapter-static), though you might prefer to use an adapter designed for the platform you're deploying to. +You will need to add an [adapter](/docs/building-your-app). `sapper build` is roughly equivalent to [adapter-node](https://github.com/sveltejs/kit/tree/master/packages/adapter-node) while `sapper export` is roughly equivalent to [adapter-static](https://github.com/sveltejs/kit/tree/master/packages/adapter-static), though you might prefer to use an adapter designed for the platform you're deploying to. If you were using plugins for filetypes that are not automatically handled by [Vite](https://vitejs.dev), you will need to find Vite equivalents and add them to the [Vite config](/docs/project-structure#project-files-vite-config-js). diff --git a/packages/adapter-auto/index.js b/packages/adapter-auto/index.js index 6caacb8b7db9..3dfdc37dae1d 100644 --- a/packages/adapter-auto/index.js +++ b/packages/adapter-auto/index.js @@ -114,7 +114,7 @@ export default () => ({ if (adapter) return adapter.adapt(builder); builder.log.warn( - 'Could not detect a supported production environment. See https://kit.svelte.dev/docs/adapters to learn how to configure your app to run on the platform of your choosing' + 'Could not detect a supported production environment. See https://kit.svelte.dev/docs/building-your-app to learn how to configure your app to run on the platform of your choosing' ); } }); diff --git a/packages/adapter-cloudflare/README.md b/packages/adapter-cloudflare/README.md index ccfe906bcd1f..5843bb29b12c 100644 --- a/packages/adapter-cloudflare/README.md +++ b/packages/adapter-cloudflare/README.md @@ -1,6 +1,6 @@ # adapter-cloudflare -[Adapter](https://kit.svelte.dev/docs/adapters) for building SvelteKit applications on [Cloudflare Pages](https://developers.cloudflare.com/pages/) with [Workers integration](https://developers.cloudflare.com/pages/platform/functions). +[Adapter](https://kit.svelte.dev/docs/building-your-app) for building SvelteKit applications on [Cloudflare Pages](https://developers.cloudflare.com/pages/) with [Workers integration](https://developers.cloudflare.com/pages/platform/functions). If you're using [adapter-auto](../adapter-auto), you don't need to install this — it's already included. diff --git a/packages/adapter-node/README.md b/packages/adapter-node/README.md index d02c8465e8b8..e4837adeddc3 100644 --- a/packages/adapter-node/README.md +++ b/packages/adapter-node/README.md @@ -1,6 +1,6 @@ # @sveltejs/adapter-node -[Adapter](https://kit.svelte.dev/docs/adapters) for SvelteKit apps that generates a standalone Node server. +[Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that generates a standalone Node server. ## Usage diff --git a/packages/adapter-static/README.md b/packages/adapter-static/README.md index abb0eb5c0859..54cfd6afb717 100644 --- a/packages/adapter-static/README.md +++ b/packages/adapter-static/README.md @@ -1,6 +1,6 @@ # @sveltejs/adapter-static -[Adapter](https://kit.svelte.dev/docs/adapters) for SvelteKit apps that prerenders your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with [the `prerender` option](https://kit.svelte.dev/docs/page-options#prerender). +[Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that prerenders your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with [the `prerender` option](https://kit.svelte.dev/docs/page-options#prerender). ## Usage diff --git a/packages/adapter-static/test/apps/spa/README.md b/packages/adapter-static/test/apps/spa/README.md index c7f00c26d735..89ab789a9f1d 100644 --- a/packages/adapter-static/test/apps/spa/README.md +++ b/packages/adapter-static/test/apps/spa/README.md @@ -27,7 +27,7 @@ npm run dev -- --open ## Building -Before creating a production version of your app, install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment. Then: +Before creating a production version of your app, install an [adapter](https://kit.svelte.dev/docs/building-your-app) for your target environment. Then: ```bash npm run build diff --git a/packages/create-svelte/shared/README.md b/packages/create-svelte/shared/README.md index 5c91169b0ca6..ccebf0fe042c 100644 --- a/packages/create-svelte/shared/README.md +++ b/packages/create-svelte/shared/README.md @@ -35,4 +35,4 @@ npm run build You can preview the production build with `npm run preview`. -> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment. +> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/building-your-app) for your target environment. diff --git a/packages/kit/src/core/config/options.js b/packages/kit/src/core/config/options.js index 2aa87c8a291b..a188ec0cbf76 100644 --- a/packages/kit/src/core/config/options.js +++ b/packages/kit/src/core/config/options.js @@ -67,7 +67,7 @@ const options = object( message += ', rather than the name of an adapter'; } - throw new Error(`${message}. See https://kit.svelte.dev/docs/adapters`); + throw new Error(`${message}. See https://kit.svelte.dev/docs/building-your-app`); } return input; diff --git a/packages/kit/src/exports/vite/index.js b/packages/kit/src/exports/vite/index.js index 03956dd3b2d2..f76a89b7788b 100644 --- a/packages/kit/src/exports/vite/index.js +++ b/packages/kit/src/exports/vite/index.js @@ -612,7 +612,7 @@ function kit({ svelte_config }) { } else { console.log(colors.bold().yellow('\nNo adapter specified')); - const link = colors.bold().cyan('https://kit.svelte.dev/docs/adapters'); + const link = colors.bold().cyan('https://kit.svelte.dev/docs/building-your-app'); console.log( `See ${link} to learn how to configure your app to run on the platform of your choosing` ); diff --git a/packages/kit/types/ambient.d.ts b/packages/kit/types/ambient.d.ts index a8bd4cf9fc06..772f0b2c0ca3 100644 --- a/packages/kit/types/ambient.d.ts +++ b/packages/kit/types/ambient.d.ts @@ -59,7 +59,7 @@ declare namespace App { export interface PageData {} /** - * If your adapter provides [platform-specific context](https://kit.svelte.dev/docs/adapters#supported-environments-platform-specific-context) via `event.platform`, you can specify it here. + * If your adapter provides [platform-specific context](https://kit.svelte.dev/docs/building-your-app#supported-environments-platform-specific-context) via `event.platform`, you can specify it here. */ export interface Platform {} } diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts index 2944b989c348..6d773d5105e8 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -21,7 +21,7 @@ import { SSRNodeLoader, SSRRoute, ValidatedConfig } from './internal.js'; export { PrerenderOption } from './private.js'; /** - * [Adapters](https://kit.svelte.dev/docs/adapters) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing. + * [Adapters](https://kit.svelte.dev/docs/building-your-app) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing. */ export interface Adapter { /** @@ -227,7 +227,7 @@ export interface Cookies { export interface KitConfig { /** - * Your [adapter](https://kit.svelte.dev/docs/adapters) is run when executing `vite build`. It determines how the output is converted for different platforms. + * Your [adapter](https://kit.svelte.dev/docs/building-your-app) is run when executing `vite build`. It determines how the output is converted for different platforms. * @default undefined */ adapter?: Adapter; diff --git a/sites/kit.svelte.dev/src/hooks.server.js b/sites/kit.svelte.dev/src/hooks.server.js index c7e8742e90e9..f064da48dda7 100644 --- a/sites/kit.svelte.dev/src/hooks.server.js +++ b/sites/kit.svelte.dev/src/hooks.server.js @@ -1,6 +1,7 @@ const redirects = { '/docs/typescript': '/docs/types', - '/docs/amp': '/docs/seo#manual-setup-amp' + '/docs/amp': '/docs/seo#manual-setup-amp', + '/docs/adapters': '/docs/building-your-app' }; const preload_types = ['js', 'css', 'font']; diff --git a/sites/kit.svelte.dev/src/routes/home/Deployment.svelte b/sites/kit.svelte.dev/src/routes/home/Deployment.svelte index ff6b326ee7be..7b905ea02441 100644 --- a/sites/kit.svelte.dev/src/routes/home/Deployment.svelte +++ b/sites/kit.svelte.dev/src/routes/home/Deployment.svelte @@ -103,7 +103,7 @@ Azure - + More... From b5889181fbdf11805bb5243ad42e6e23d893623a Mon Sep 17 00:00:00 2001 From: Simon Holthausen Date: Fri, 13 Jan 2023 11:53:11 +0100 Subject: [PATCH 02/23] fix --- documentation/docs/20-core-concepts/50-building-your-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/20-core-concepts/50-building-your-app.md b/documentation/docs/20-core-concepts/50-building-your-app.md index 0e67c98eac9a..b4d0c9e78a0d 100644 --- a/documentation/docs/20-core-concepts/50-building-your-app.md +++ b/documentation/docs/20-core-concepts/50-building-your-app.md @@ -24,7 +24,7 @@ if (!building) { setupMyDatabase(); } -export const load() { +export function load() { // ... } ``` From 9fca4b7d382c112741891e14910a07950ac45970 Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Sat, 14 Jan 2023 15:35:34 -0800 Subject: [PATCH 03/23] docs: move adapter docs to site --- .../docs/20-core-concepts/20-load.md | 2 +- .../10-building-your-app.md | 34 +++ .../20-adapters.md} | 35 +--- .../25-building-your-app/30-adapter-auto.md | 22 ++ .../40-adapter-cloudflare.md | 100 +++++++++ .../50-adapter-cloudflare-workers.md | 124 +++++++++++ .../60-adapter-netlify.md | 117 +++++++++++ .../25-building-your-app/70-adapter-node.md | 194 ++++++++++++++++++ .../25-building-your-app/80-adapter-static.md | 186 +++++++++++++++++ .../25-building-your-app/90-adapter-vercel.md | 87 ++++++++ .../docs/25-building-your-app/meta.json | 3 + packages/adapter-auto/README.md | 15 +- packages/adapter-cloudflare-workers/README.md | 113 +--------- packages/adapter-cloudflare/README.md | 91 +------- packages/adapter-netlify/README.md | 108 +--------- packages/adapter-node/README.md | 187 +---------------- packages/adapter-static/README.md | 179 +--------------- packages/adapter-vercel/README.md | 78 +------ packages/kit/types/ambient.d.ts | 2 +- 19 files changed, 889 insertions(+), 788 deletions(-) create mode 100644 documentation/docs/25-building-your-app/10-building-your-app.md rename documentation/docs/{20-core-concepts/50-building-your-app.md => 25-building-your-app/20-adapters.md} (81%) create mode 100644 documentation/docs/25-building-your-app/30-adapter-auto.md create mode 100644 documentation/docs/25-building-your-app/40-adapter-cloudflare.md create mode 100644 documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md create mode 100644 documentation/docs/25-building-your-app/60-adapter-netlify.md create mode 100644 documentation/docs/25-building-your-app/70-adapter-node.md create mode 100644 documentation/docs/25-building-your-app/80-adapter-static.md create mode 100644 documentation/docs/25-building-your-app/90-adapter-vercel.md create mode 100644 documentation/docs/25-building-your-app/meta.json diff --git a/documentation/docs/20-core-concepts/20-load.md b/documentation/docs/20-core-concepts/20-load.md index 4da80292be46..f547c7833c15 100644 --- a/documentation/docs/20-core-concepts/20-load.md +++ b/documentation/docs/20-core-concepts/20-load.md @@ -192,7 +192,7 @@ Often the `load` function depends on the URL in one way or another. For this, th An instance of [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL), containing properties like the `origin`, `hostname`, `pathname` and `searchParams` (which contains the parsed query string as a [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object). `url.hash` cannot be accessed during `load`, since it is unavailable on the server. -> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](/docs/building-your-app#supported-environments-node-js), for example, you may need to configure the adapter in order for the URL to be correct. +> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](adapters#supported-environments-node-js), for example, you may need to configure the adapter in order for the URL to be correct. ### route diff --git a/documentation/docs/25-building-your-app/10-building-your-app.md b/documentation/docs/25-building-your-app/10-building-your-app.md new file mode 100644 index 000000000000..862b9b23207a --- /dev/null +++ b/documentation/docs/25-building-your-app/10-building-your-app.md @@ -0,0 +1,34 @@ +--- +title: Building Your App +--- + +Building a SvelteKit consists of two stages. First the production build is run. This will create a client and a server build which are later consumed by the corresponding environments. [Prerendering](/docs/page-options#prerender) is executed at this stage, if enabled. The second step is to _adapt_ the output to your deployment target using adapters (more on that in the later sections). + +## During the build + +SvelteKit will load your `+page/layout(.server).js` files (and all files they import) for analysis during the build. This could lead to code eagerly running which you want to avoid at that stage. Wrap the code in question with `building` from `$app/environment`: + +```js +/// file: +layout.server.js +// @filename: ambient.d.ts +declare module '$lib/server/database' { + export function setupMyDatabase(): void; +} + +// @filename: index.js +// ---cut--- +import { building } from '$app/environment'; +import { setupMyDatabase } from '$lib/server/database'; + +if (!building) { + setupMyDatabase(); +} + +export function load() { + // ... +} +``` + +## Preview your app + +Run the `preview` script to look at your app locally after the production build is done. Note that this does not yet include adapter-specific adjustments like the [`platform` object](adapters#supported-environments-platform-specific-context). diff --git a/documentation/docs/20-core-concepts/50-building-your-app.md b/documentation/docs/25-building-your-app/20-adapters.md similarity index 81% rename from documentation/docs/20-core-concepts/50-building-your-app.md rename to documentation/docs/25-building-your-app/20-adapters.md index b4d0c9e78a0d..b3885d50bf0a 100644 --- a/documentation/docs/20-core-concepts/50-building-your-app.md +++ b/documentation/docs/25-building-your-app/20-adapters.md @@ -1,40 +1,7 @@ --- -title: Building Your App +title: Adapters --- -Building a SvelteKit consists of two stages. First the production build is run. This will create a client and a server build which are later consumed by the corresponding environments. [Prerendering](/docs/page-options#prerender) is executed at this stage, if enabled. The second step is to _adapt_ the output to your deployment target using adapters (more on that in the later sections). - -## During the build - -SvelteKit will load your `+page/layout(.server).js` files (and all files they import) for analysis during the build. This could lead to code eagerly running which you want to avoid at that stage. Wrap the code in question with `building` from `$app/environment`: - -```js -/// file: +layout.server.js -// @filename: ambient.d.ts -declare module '$lib/server/database' { - export function setupMyDatabase(): void; -} - -// @filename: index.js -// ---cut--- -import { building } from '$app/environment'; -import { setupMyDatabase } from '$lib/server/database'; - -if (!building) { - setupMyDatabase(); -} - -export function load() { - // ... -} -``` - -## Preview your app - -Run the `preview` script to look at your app locally after the production build is done. Note that this does not yet include adapter-specific adjustments like the [`platform` object](#supported-environments-platform-specific-context). - -## Adapters - Before you can deploy your SvelteKit app, you need to _adapt_ it for your deployment target. Adapters are small plugins that take the built app as input and generate output for deployment. By default, projects are configured to use `@sveltejs/adapter-auto`, which detects your production environment and selects the appropriate adapter where possible. If your platform isn't (yet) supported, you may need to [install a custom adapter](#community-adapters) or [write one](#writing-custom-adapters). diff --git a/documentation/docs/25-building-your-app/30-adapter-auto.md b/documentation/docs/25-building-your-app/30-adapter-auto.md new file mode 100644 index 000000000000..e701e764061d --- /dev/null +++ b/documentation/docs/25-building-your-app/30-adapter-auto.md @@ -0,0 +1,22 @@ +--- +title: adapter-auto +--- + +Automatically chooses the adapter for your current environment, if possible. + +## Supported environments + +The following environments are supported out-of-the-box, meaning a newly created project can be deployed on one of these platforms without any additional configuration: + +- [Cloudflare Pages](https://developers.cloudflare.com/pages/) via [adapter-cloudflare](adapter-cloudflare) +- [Netlify](https://netlify.com/) via [adapter-netlify](adapter-netlify) +- [Vercel](https://vercel.com/) via [adapter-vercel](adapter-vercel) +- [Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/) via [svelte-adapter-azure-swa](https://github.com/geoffrich/svelte-adapter-azure-swa) + +## Community adapters + +Support for additional environments can be added in [adapters.js](https://github.com/sveltejs/kit/blob/master/packages/adapter-auto/adapters.js). To avoid this package ballooning in size, community-supported adapters should not be added as dependencies — adapter-auto will instead prompt users to install missing packages as needed. + +## Changelog + +[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-auto/CHANGELOG.md). diff --git a/documentation/docs/25-building-your-app/40-adapter-cloudflare.md b/documentation/docs/25-building-your-app/40-adapter-cloudflare.md new file mode 100644 index 000000000000..6679fa2bc317 --- /dev/null +++ b/documentation/docs/25-building-your-app/40-adapter-cloudflare.md @@ -0,0 +1,100 @@ +--- +title: adapter-cloudflare +--- + +[Adapter](https://kit.svelte.dev/docs/building-your-app) for building SvelteKit applications on [Cloudflare Pages](https://developers.cloudflare.com/pages/) with [Workers integration](https://developers.cloudflare.com/pages/platform/functions). + +If you're using [adapter-auto](adapter-auto), you don't need to install this — it's already included. + +_**Comparisons**_ + +- `adapter-cloudflare` – supports all SvelteKit features; builds for + [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) +- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for + Cloudflare Workers +- `adapter-static` – only produces client-side static assets; compatible with + Cloudflare Pages + +> **Note:** Cloudflare Pages' new Workers integration is currently in beta.
+> Compared to `adapter-cloudflare-workers`, this adapter will be the preferred approach for most users since building on top of Pages unlocks automatic builds and deploys, preview deployments, instant rollbacks, etc.
+> From SvelteKit's perspective, there is no difference and no functionality loss when migrating to/from the Workers and the Pages adapters. + +## Installation + +```sh +$ npm i --save-dev @sveltejs/adapter-cloudflare +``` + +## Usage + +You can include these changes in your `svelte.config.js` configuration file: + +```js +import adapter from '@sveltejs/adapter-cloudflare'; + +export default { + kit: { + adapter: adapter() + } +}; +``` + +## Deployment + +Please follow the [Get Started Guide](https://developers.cloudflare.com/pages/get-started) for Cloudflare Pages to begin. + +When configuring your project settings, you must use the following settings: + +- **Framework preset** – None +- **Build command** – `npm run build` or `svelte-kit build` +- **Build output directory** – `.svelte-kit/cloudflare` +- **Environment variables** + - `NODE_VERSION`: `16` + +> **Important:** You need to add a `NODE_VERSION` environment variable to both the "production" and "preview" environments. You can add this during project setup or later in the Pages project settings. SvelteKit requires Node `16.14` or later, so you should use `16` as the `NODE_VERSION` value. + +## Environment variables + +The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object, containing KV/DO namespaces etc, is passed to SvelteKit via the `platform` property along with `context` and `caches`, meaning you can access it in hooks and endpoints: + +```js +export async function POST({ request, platform }) { + const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); +} +``` + +To make these types available to your app, reference them in your `src/app.d.ts`: + +```diff +/// ++/// + +declare namespace App { + interface Platform { ++ env?: { ++ YOUR_KV_NAMESPACE: KVNamespace; ++ YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace; ++ }; + } +} +``` + +> `platform.env` is only available in the production build. Use [wrangler](https://developers.cloudflare.com/workers/cli-wrangler) to test it locally + +## Notes + +Functions contained in the `/functions` directory at the project's root will _not_ be included in the deployment, which is compiled to a [single `_worker.js` file](https://developers.cloudflare.com/pages/platform/functions/#advanced-mode). Functions should be implemented as [server endpoints](https://kit.svelte.dev/docs/routing#server) in your SvelteKit app. + +The `_headers` and `_redirects` files specific to Cloudflare Pages can be used for static asset responses (like images) by putting them into the `/static` folder. + +However, they will have no effect on responses dynamically rendered by SvelteKit, which should return custom headers or redirect responses from [server endpoints](https://kit.svelte.dev/docs/routing#server) or with the [`handle`](https://kit.svelte.dev/docs/hooks#server-hooks-handle) hook. + +## Troubleshooting + +### Accessing the file system + +You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. + +## Changelog + +[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-cloudflare/CHANGELOG.md). diff --git a/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md b/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md new file mode 100644 index 000000000000..e0e67bc86e11 --- /dev/null +++ b/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md @@ -0,0 +1,124 @@ +--- +title: adapter-cloudflare-workers +--- + +SvelteKit adapter that creates a Cloudflare Workers site using a function for dynamic server rendering. + +**Requires [Wrangler v2](https://developers.cloudflare.com/workers/wrangler/get-started/).** Wrangler v1 is no longer supported. + +_**Comparisons**_ + +- `adapter-cloudflare` – supports all SvelteKit features; builds for + [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) +- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for + Cloudflare Workers +- `adapter-static` – only produces client-side static assets; compatible with + Cloudflare Pages + +> **Note:** Cloudflare Pages' new Workers integration is currently in beta.
+> Compared to `adapter-cloudflare-workers`, `adapter-cloudflare` is the preferred approach for most users since building on top of Pages unlocks automatic builds and deploys, preview deployments, instant rollbacks, etc.
+> From SvelteKit's perspective, there is no difference and no functionality loss when migrating to/from the Workers and the Pages adapters. + +## Usage + +Install with `npm i -D @sveltejs/adapter-cloudflare-workers`, then add the adapter to your `svelte.config.js`: + +```js +import adapter from '@sveltejs/adapter-cloudflare-workers'; + +export default { + kit: { + adapter: adapter() + } +}; +``` + +## Basic Configuration + +This adapter expects to find a [wrangler.toml](https://developers.cloudflare.com/workers/platform/sites/configuration) file in the project root. It should look something like this: + +```toml +name = "" +account_id = "" + +main = "./.cloudflare/worker.js" +site.bucket = "./.cloudflare/public" + +build.command = "npm run build" + +compatibility_date = "2021-11-12" +workers_dev = true +``` + +`` can be anything. `` can be found by logging into your [Cloudflare dashboard](https://dash.cloudflare.com) and grabbing it from the end of the URL: + +``` +https://dash.cloudflare.com/ +``` + +> It's recommended that you add the `.cloudflare` directory (or whichever directories you specified for `main` and `site.bucket`) to your `.gitignore`. + +You will need to install [wrangler](https://developers.cloudflare.com/workers/wrangler/get-started/) and log in, if you haven't already: + +``` +npm i -g wrangler +wrangler login +``` + +Then, you can build your app and deploy it: + +```sh +wrangler publish +``` + +## Custom config + +If you would like to use a config file other than `wrangler.toml`, you can do like so: + +```js +import adapter from '@sveltejs/adapter-cloudflare-workers'; + +export default { + kit: { + adapter: adapter({ config: '.toml' }) + } +}; +``` + +## Environment variables + +The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object, containing KV/DO namespaces etc, is passed to SvelteKit via the `platform` property along with `context` and `caches`, meaning you can access it in hooks and endpoints: + +```js +export async function POST({ request, platform }) { + const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); +} +``` + +To make these types available to your app, reference them in your `src/app.d.ts`: + +```diff +/// ++/// + +declare namespace App { + interface Platform { ++ env?: { ++ YOUR_KV_NAMESPACE: KVNamespace; ++ YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace; ++ }; + } +} +``` + +> `platform.env` is only available in the production build. Use [wrangler](https://developers.cloudflare.com/workers/cli-wrangler) to test it locally + +## Troubleshooting + +### Accessing the file system + +You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. + +## Changelog + +[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-cloudflare-workers/CHANGELOG.md). diff --git a/documentation/docs/25-building-your-app/60-adapter-netlify.md b/documentation/docs/25-building-your-app/60-adapter-netlify.md new file mode 100644 index 000000000000..f4c6355b603e --- /dev/null +++ b/documentation/docs/25-building-your-app/60-adapter-netlify.md @@ -0,0 +1,117 @@ +--- +title: adapter-netlify +--- + +A SvelteKit adapter that creates a Netlify app. + +If you're using [adapter-auto](adapter-auto), you don't need to install this unless you need to specify Netlify-specific options, since it's already included. + +## Installation + +```bash +npm i -D @sveltejs/adapter-netlify +``` + +You can then configure it inside of `svelte.config.js`: + +```js +import adapter from '@sveltejs/adapter-netlify'; + +export default { + kit: { + // default options are shown + adapter: adapter({ + // if true, will create a Netlify Edge Function rather + // than using standard Node-based functions + edge: false, + + // if true, will split your app into multiple functions + // instead of creating a single one for the entire app. + // if `edge` is true, this option cannot be used + split: false + }) + } +}; +``` + +Then, make sure you have a [netlify.toml](https://docs.netlify.com/configure-builds/file-based-configuration) file in the project root. This will determine where to write static assets based on the `build.publish` settings, as per this sample configuration: + +```toml +[build] + command = "npm run build" + publish = "build" +``` + +If the `netlify.toml` file or the `build.publish` value is missing, a default value of `"build"` will be used. Note that if you have set the publish directory in the Netlify UI to something else then you will need to set it in `netlify.toml` too, or use the default value of `"build"`. + +### Node version + +New projects will use Node 16 by default. However, if you're upgrading a project you created a while ago it may be stuck on an older version. See [the Netlify docs](https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript) for details on manually specifying Node 16 or newer. + +## Netlify Edge Functions (beta) + +SvelteKit supports the beta release of [Netlify Edge Functions](https://docs.netlify.com/netlify-labs/experimental-features/edge-functions/). If you pass the option `edge: true` to the `adapter` function, server-side rendering will happen in a Deno-based edge function that's deployed close to the site visitor. If set to `false` (the default), the site will deploy to standard Node-based Netlify Functions. + +```js +import adapter from '@sveltejs/adapter-netlify'; + +export default { + kit: { + adapter: adapter({ + // will create a Netlify Edge Function using Deno-based + // rather than using standard Node-based functions + edge: true + }) + } +}; +``` + +## Netlify alternatives to SvelteKit functionality + +You may build your app using functionality provided directly by SvelteKit without relying on any Netlify functionality. Using the SvelteKit versions of these features will allow them to be used in dev mode, tested with integration tests, and to work with other adapters should you ever decide to switch away from Netlify. However, in some scenarios you may find it beneficial to use the Netlify versions of these features. One example would be if you're migrating an app that's already hosted on Netlify to SvelteKit. + +### Using Netlify Redirect Rules + +During compilation, redirect rules are automatically appended to your `_redirects` file. (If it doesn't exist yet, it will be created.) That means: + +- `[[redirects]]` in `netlify.toml` will never match as `_redirects` has a [higher priority](https://docs.netlify.com/routing/redirects/#rule-processing-order). So always put your rules in the [`_redirects` file](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file). +- `_redirects` shouldn't have any custom "catch all" rules such as `/* /foobar/:splat`. Otherwise the automatically appended rule will never be applied as Netlify is only processing [the first matching rule](https://docs.netlify.com/routing/redirects/#rule-processing-order). + +### Using Netlify Forms + +1. Create your Netlify HTML form as described [here](https://docs.netlify.com/forms/setup/#html-forms), e.g. as `/routes/contact.svelte`. (Don't forget to add the hidden `form-name` input element!) +2. Netlify's build bot parses your HTML files at deploy time, which means your form must be [prerendered](https://kit.svelte.dev/docs/page-options#prerender) as HTML. You can either add `export const prerender = true` to your `contact.svelte` to prerender just that page or set the `kit.prerender.force: true` option to prerender all pages. +3. If your Netlify form has a [custom success message](https://docs.netlify.com/forms/setup/#success-messages) like `
` then ensure the corresponding `/routes/success.svelte` exists and is prerendered. + +### Using Netlify Functions + +With this adapter, SvelteKit endpoints are hosted as [Netlify Functions](https://docs.netlify.com/functions/overview/). Netlify function handlers have additional context, including [Netlify Identity](https://docs.netlify.com/visitor-access/identity/) information. You can access this context via the `event.platform.context` field inside your hooks and `+page.server` or `+layout.server` endpoints. These are [serverless functions](https://docs.netlify.com/functions/overview/) when the `edge` property is `false` in the adapter config or [edge functions](https://docs.netlify.com/edge-functions/overview/#app) when it is `true`. + +```js +// +page.server.js +export const load = async (event) => { + const context = event.platform.context; + console.log(context); // shows up in your functions log in the Netlify app +}; +``` + +Additionally, you can add your own Netlify functions by creating a directory for them and adding the configuration to your `netlify.toml` file. For example: + +```toml +[build] + command = "npm run build" + publish = "build" + +[functions] + directory = "functions" +``` + +## Troubleshooting + +### Accessing the file system + +You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. + +## Changelog + +[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-netlify/CHANGELOG.md). diff --git a/documentation/docs/25-building-your-app/70-adapter-node.md b/documentation/docs/25-building-your-app/70-adapter-node.md new file mode 100644 index 000000000000..bd9082cc39ae --- /dev/null +++ b/documentation/docs/25-building-your-app/70-adapter-node.md @@ -0,0 +1,194 @@ +--- +title: adapter-node +--- + +[Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that generates a standalone Node server. + +## Usage + +Install with `npm i -D @sveltejs/adapter-node`, then add the adapter to your `svelte.config.js`: + +```js +// svelte.config.js +import adapter from '@sveltejs/adapter-node'; + +export default { + kit: { + adapter: adapter() + } +}; +``` + +## Deploying + +You will need the output directory (`build` by default), the project's `package.json`, and the production dependencies in `node_modules` to run the application. Production dependencies can be generated with `npm ci --prod` (you can skip this step if your app doesn't have any dependencies). You can then start your app with + +```bash +node build +``` + +Development dependencies will be bundled into your app using `rollup`. To control whether a given package is bundled or externalised, place it in `devDependencies` or `dependencies` respectively in your `package.json`. + +## Environment variables + +In `dev` and `preview`, SvelteKit will read environent variables from your `.env` file (or `.env.local`, or `.env.[mode]`, [as determined by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files).) + +In production, `.env` files are _not_ automatically loaded. To do so, install `dotenv` in your project... + +```bash +npm install dotenv +``` + +...and invoke it before running the built app: + +```diff +-node build ++node -r dotenv/config build +``` + +### `PORT` and `HOST` + +By default, the server will accept connections on `0.0.0.0` using port 3000. These can be customised with the `PORT` and `HOST` environment variables: + +``` +HOST=127.0.0.1 PORT=4000 node build +``` + +### `ORIGIN`, `PROTOCOL_HEADER` and `HOST_HEADER` + +HTTP doesn't give SvelteKit a reliable way to know the URL that is currently being requested. The simplest way to tell SvelteKit where the app is being served is to set the `ORIGIN` environment variable: + +``` +ORIGIN=https://my.site node build +``` + +With this, a request for the `/stuff` pathname will correctly resolve to `https://my.site/stuff`. Alternatively, you can specify headers that tell SvelteKit about the request protocol and host, from which it can construct the origin URL: + +``` +PROTOCOL_HEADER=x-forwarded-proto HOST_HEADER=x-forwarded-host node build +``` + +> [`x-forwarded-proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) and [`x-forwarded-host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) are de facto standard headers that forward the original protocol and host if you're using a reverse proxy (think load balancers and CDNs). You should only set these variables if your server is behind a trusted reverse proxy; otherwise, it'd be possible for clients to spoof these headers. + +If `adapter-node` can't correctly determine the URL of your deployment, you may experience this error when using [form actions](https://kit.svelte.dev/docs/form-actions): + +> Cross-site POST form submissions are forbidden + +### `ADDRESS_HEADER` and `XFF_DEPTH` + +The [RequestEvent](https://kit.svelte.dev/docs/types#public-types-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: + +``` +ADDRESS_HEADER=True-Client-IP node build +``` + +> Headers can easily be spoofed. As with `PROTOCOL_HEADER` and `HOST_HEADER`, you should [know what you're doing](https://adam-p.ca/blog/2022/03/x-forwarded-for/) before setting these. + +If the `ADDRESS_HEADER` is `X-Forwarded-For`, the header value will contain a comma-separated list of IP addresses. The `XFF_DEPTH` environment variable should specify how many trusted proxies sit in front of your server. E.g. if there are three trusted proxies, proxy 3 will forward the addresses of the original connection and the first two proxies: + +``` +, , +``` + +Some guides will tell you to read the left-most address, but this leaves you [vulnerable to spoofing](https://adam-p.ca/blog/2022/03/x-forwarded-for/): + +``` +, , , +``` + +Instead, we read from the _right_, accounting for the number of trusted proxies. In this case, we would use `XFF_DEPTH=3`. + +> If you need to read the left-most address instead (and don't care about spoofing) — for example, to offer a geolocation service, where it's more important for the IP address to be _real_ than _trusted_, you can do so by inspecting the `x-forwarded-for` header within your app. + +### `BODY_SIZE_LIMIT` + +The maximum request body size to accept in bytes including while streaming. Defaults to 512kb. You can disable this option with a value of 0 and implement a custom check in [`handle`](https://kit.svelte.dev/docs/hooks#server-hooks-handle) if you need something more advanced. + +## Options + +The adapter can be configured with various options: + +```js +// svelte.config.js +import adapter from '@sveltejs/adapter-node'; + +export default { + kit: { + adapter: adapter({ + // default options are shown + out: 'build', + precompress: false, + envPrefix: '' + }) + } +}; +``` + +### out + +The directory to build the server to. It defaults to `build` — i.e. `node build` would start the server locally after it has been created. + +### precompress + +Enables precompressing using gzip and brotli for assets and prerendered pages. It defaults to `false`. + +### envPrefix + +If you need to change the name of the environment variables used to configure the deployment (for example, to deconflict with environment variables you don't control), you can specify a prefix: + +```js +envPrefix: 'MY_CUSTOM_'; +``` + +``` +MY_CUSTOM_HOST=127.0.0.1 \ +MY_CUSTOM_PORT=4000 \ +MY_CUSTOM_ORIGIN=https://my.site \ +node build +``` + +## Custom server + +The adapter creates two files in your build directory — `index.js` and `handler.js`. Running `index.js` — e.g. `node build`, if you use the default build directory — will start a server on the configured port. + +Alternatively, you can import the `handler.js` file, which exports a handler suitable for use with [Express](https://github.com/expressjs/expressjs.com), [Connect](https://github.com/senchalabs/connect) or [Polka](https://github.com/lukeed/polka) (or even just the built-in [`http.createServer`](https://nodejs.org/dist/latest/docs/api/http.html#httpcreateserveroptions-requestlistener)) and set up your own server: + +```js +// my-server.js +import { handler } from './build/handler.js'; +import express from 'express'; + +const app = express(); + +// add a route that lives separately from the SvelteKit app +app.get('/healthcheck', (req, res) => { + res.end('ok'); +}); + +// let SvelteKit handle everything else, including serving prerendered pages and static assets +app.use(handler); + +app.listen(3000, () => { + console.log('listening on port 3000'); +}); +``` + +## Troubleshooting + +### Is there a hook for cleaning up before the server exits? + +There's nothing built-in to SvelteKit for this, because such a cleanup hook depends highly on the execution environment you're on. For Node, you can use its built-in `process.on(..)` to implement a callback that runs before the server exits: + +```js +function shutdownGracefully() { + // anything you need to clean up manually goes in here + db.shutdown(); +} + +process.on('SIGINT', shutdownGracefully); +process.on('SIGTERM', shutdownGracefully); +``` + +## Changelog + +[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-node/CHANGELOG.md). diff --git a/documentation/docs/25-building-your-app/80-adapter-static.md b/documentation/docs/25-building-your-app/80-adapter-static.md new file mode 100644 index 000000000000..8a5001be38b1 --- /dev/null +++ b/documentation/docs/25-building-your-app/80-adapter-static.md @@ -0,0 +1,186 @@ +--- +title: adapter-static +--- + +[Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that prerenders your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with [the `prerender` option](https://kit.svelte.dev/docs/page-options#prerender). + +## Usage + +Install with `npm i -D @sveltejs/adapter-static`, then add the adapter to your `svelte.config.js`... + +```js +// svelte.config.js +import adapter from '@sveltejs/adapter-static'; + +export default { + kit: { + adapter: adapter({ + // default options are shown. On some platforms + // these options are set automatically — see below + pages: 'build', + assets: 'build', + fallback: null, + precompress: false, + strict: true + }) + } +}; +``` + +...and add the [`prerender`](https://kit.svelte.dev/docs/page-options#prerender) option to your root layout: + +```js +// src/routes/+layout.js + +// This can be false if you're using a fallback (i.e. SPA mode) +export const prerender = true; +``` + +> ⚠️ You must ensure SvelteKit's [`trailingSlash`](https://kit.svelte.dev/docs/page-options#trailingslash) option is set appropriately for your environment. If your host does not render `/a.html` upon receiving a request for `/a` then you will need to set `trailingSlash: 'always'` to create `/a/index.html` instead. + +## Zero-config support + +Some platforms have zero-config support (more to come in future): + +- [Vercel](https://vercel.com) + +On these platforms, you should omit the adapter options so that `adapter-static` can provide the optimal configuration: + +```diff +export default { + kit: { +- adapter: adapter({...}), ++ adapter: adapter(), + } + } +}; +``` + +## Options + +### pages + +The directory to write prerendered pages to. It defaults to `build`. + +### assets + +The directory to write static assets (the contents of `static`, plus client-side JS and CSS generated by SvelteKit) to. Ordinarily this should be the same as `pages`, and it will default to whatever the value of `pages` is, but in rare circumstances you might need to output pages and assets to separate locations. + +### fallback + +Specify a fallback page for SPA mode, e.g. `index.html` or `200.html` or `404.html`. + +### precompress + +If `true`, precompresses files with brotli and gzip. This will generate `.br` and `.gz` files. + +### strict + +By default, `adapter-static` checks that either all pages and endpoints (if any) of your app were prerendered, or you have the `fallback` option set. This check exists to prevent you from accidentally publishing an app where some parts of it are not accessible, because they are not contained in the final output. If you know this is ok (for example when a certain page only exists conditionally), you can set `strict` to `false` to turn off this check. + +## SPA mode + +You can use `adapter-static` to create a single-page app or SPA by specifying a **fallback page**. + +> In most situations this is not recommended: it harms SEO, tends to slow down perceived performance, and makes your app inaccessible to users if JavaScript fails or is disabled (which happens [more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)). + +If you want to create a simple SPA with no prerendered routes, the necessary config looks like this: + +```js +// svelte.config.js +import adapter from '@sveltejs/adapter-static'; + +export default { + kit: { + adapter: adapter({ + fallback: '200.html' + }), + prerender: { entries: [] } + } +}; +``` + +```js +// src/routes/+layout.js +export const ssr = false; +``` + +You can also turn only part of your app into an SPA. + +Let's go through these options one by one: + +### Add fallback page + +The fallback page is an HTML page created by SvelteKit that loads your app and navigates to the correct route. For example [Surge](https://surge.sh/help/adding-a-200-page-for-client-side-routing), a static web host, lets you add a `200.html` file that will handle any requests that don't correspond to static assets or prerendered pages. We can create that file like so: + +```js +// svelte.config.js +import adapter from '@sveltejs/adapter-static'; + +export default { + kit: { + adapter: adapter({ + fallback: '200.html' + }) + } +}; +``` + +> How to configure this behaviour does however depend on your hosting solution and is not part of SvelteKit. It is recommended to search the host's documentation on how to redirect requests. + +### Turn off prerendering + +When operating in SPA mode, you can omit the [`prerender`](https://kit.svelte.dev/docs/page-options#prerender) option from your root layout (or set it to `false`, its default value), and only pages that have the `prerender` option set will be prerendered at build time. + +SvelteKit will still crawl your app's entry points looking for prerenderable pages. If `svelte-kit build` fails because of pages that can't be loaded outside the browser, you can set `config.kit.prerender.entries` to `[]` to prevent this from happening. (Setting `config.kit.prerender.enabled` to `false` also has this effect, but would prevent the fallback page from being generated.) + +You can also add turn off prerendering only to parts of your app, if you want other parts to be prerendered. + +### Turn off ssr + +During development, SvelteKit will still attempt to server-side render your routes. This means accessing things that are only available in the browser (such as the `window` object) will result in errors, even though this would be valid in the output app. To align the behavior of SvelteKit's dev mode with your SPA, you can [add `export const ssr = false` to your root `+layout`](https://kit.svelte.dev/docs/page-options#ssr). You can also add this option only to parts of your app, if you want other parts to be prerendered. + +### Apache + +To run an SPA on [Apache](https://httpd.apache.org/), you should add a `static/.htaccess` file to route requests to the fallback page: + +``` + + RewriteEngine On + RewriteBase / + RewriteRule ^200\.html$ - [L] + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule . /200.html [L] + +``` + +## GitHub Pages + +When building for GitHub Pages, make sure to update [`paths.base`](https://kit.svelte.dev/docs/configuration#paths) to match your repo name, since the site will be served from rather than from the root. + +You will have to prevent GitHub's provided Jekyll from managing your site by putting an empty `.nojekyll` file in your static folder. If you do not want to disable Jekyll, change the kit's `appDir` configuration option to `'app_'` or anything not starting with an underscore. For more information, see GitHub's [Jekyll documentation](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#configuring-jekyll-in-your-github-pages-site). + +A config for GitHub Pages might look like the following: + +```js +const dev = process.argv.includes('dev'); + +/** @type {import('@sveltejs/kit').Config} */ +const config = { + ... + kit: { + ... + paths: { + base: dev ? '' : '/your-repo-name', + }, + // If you are not using a .nojekyll file, change your appDir to something not starting with an underscore. + // For example, instead of '_app', use 'app_', 'internal', etc. + appDir: 'internal', + } +}; +``` + +## Changelog + +[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-static/CHANGELOG.md). diff --git a/documentation/docs/25-building-your-app/90-adapter-vercel.md b/documentation/docs/25-building-your-app/90-adapter-vercel.md new file mode 100644 index 000000000000..737d020741b9 --- /dev/null +++ b/documentation/docs/25-building-your-app/90-adapter-vercel.md @@ -0,0 +1,87 @@ +--- +title: adapter-vercel +--- + +A SvelteKit adapter that creates a Vercel app. + +If you're using [adapter-auto](adapter-auto), you don't need to install this unless you need to specify Vercel-specific options, since it's already included. + +## Usage + +Add `"@sveltejs/adapter-vercel": "next"` to the `devDependencies` in your `package.json` and run `npm install`. + +Then in your `svelte.config.js`: + +```js +import vercel from '@sveltejs/adapter-vercel'; + +export default { + kit: { + // default options are shown + adapter: vercel({ + // if true, will deploy the app using edge functions + // (https://vercel.com/docs/concepts/functions/edge-functions) + // rather than serverless functions + edge: false, + + // an array of dependencies that esbuild should treat + // as external when bundling functions + external: [], + + // if true, will split your app into multiple functions + // instead of creating a single one for the entire app + split: false + }) + } +}; +``` + +## Environment Variables + +Vercel makes a set of [deployment-specific environment variables](https://vercel.com/docs/concepts/projects/environment-variables#system-environment-variables) available. Like other environment variables, these are accessible from `$env/static/private` and `$env/dynamic/private` (sometimes — more on that later), and inaccessible from their public counterparts. To access one of these variables from the client: + +```js +// +layout.server.js +import { VERCEL_COMMIT_REF } from '$env/static/private'; + +/** @type {import('./$types').LayoutServerLoad} */ +export function load() { + return { + deploymentGitBranch: VERCEL_COMMIT_REF + }; +} +``` + +```svelte + + + +

This staging environment was deployed from {data.deploymentGitBranch}.

+``` + +Since all of these variables are unchanged between build time and run time when building on Vercel, we recommend using `$env/static/private` — which will statically replace the variables, enabling optimisations like dead code elimination — rather than `$env/dynamic/private`. If you're deploying with `edge: true` you _must_ use `$env/static/private`, as `$env/dynamic/private` and `$env/dynamic/public` are not currently populated in edge functions on Vercel. + +## Notes + +### Vercel functions + +Vercel functions contained in the `/api` directory at the project's root will _not_ be included in the deployment — these should be implemented as [server endpoints](https://kit.svelte.dev/docs/routing#server) in your SvelteKit app. + +### Node version + +Projects created before a certain date will default to using Node 14, while SvelteKit requires Node 16 or later. You can change that in your project settings: + +![Vercel project settings](https://github.com/sveltejs/kit/blob/master/packages/adapter-vercel/settings.png) + +## Troubleshooting + +### Accessing the file system + +You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. + +## Changelog + +[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-vercel/CHANGELOG.md). diff --git a/documentation/docs/25-building-your-app/meta.json b/documentation/docs/25-building-your-app/meta.json new file mode 100644 index 000000000000..1a5b9dad7b23 --- /dev/null +++ b/documentation/docs/25-building-your-app/meta.json @@ -0,0 +1,3 @@ +{ + "title": "Building your app" +} diff --git a/packages/adapter-auto/README.md b/packages/adapter-auto/README.md index 6bc8e45dc025..c0e2ba93474c 100644 --- a/packages/adapter-auto/README.md +++ b/packages/adapter-auto/README.md @@ -1,19 +1,10 @@ # adapter-auto -Automatically chooses the adapter for your current environment, if possible. +Automatically chooses the SvelteKit adapter for your current environment, if possible. -## Supported environments +## Docs -The following environments are supported out-of-the-box, meaning a newly created project can be deployed on one of these platforms without any additional configuration: - -- [Cloudflare Pages](https://developers.cloudflare.com/pages/) via [adapter-cloudflare](../adapter-cloudflare) -- [Netlify](https://netlify.com/) via [adapter-netlify](../adapter-netlify) -- [Vercel](https://vercel.com/) via [adapter-vercel](../adapter-vercel) -- [Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/) via [svelte-adapter-azure-swa](https://github.com/geoffrich/svelte-adapter-azure-swa) - -## Community adapters - -Support for additional environments can be added in [adapters.js](adapters.js). To avoid this package ballooning in size, community-supported adapters should not be added as dependencies — adapter-auto will instead prompt users to install missing packages as needed. +[Docs](https://kit.svelte.dev/docs/adapter-auto) ## Changelog diff --git a/packages/adapter-cloudflare-workers/README.md b/packages/adapter-cloudflare-workers/README.md index d59cff039a6a..ab34b9418023 100644 --- a/packages/adapter-cloudflare-workers/README.md +++ b/packages/adapter-cloudflare-workers/README.md @@ -4,118 +4,9 @@ SvelteKit adapter that creates a Cloudflare Workers site using a function for dy **Requires [Wrangler v2](https://developers.cloudflare.com/workers/wrangler/get-started/).** Wrangler v1 is no longer supported. -_**Comparisons**_ +## Docs -- `adapter-cloudflare` – supports all SvelteKit features; builds for - [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) -- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for - Cloudflare Workers -- `adapter-static` – only produces client-side static assets; compatible with - Cloudflare Pages - -> **Note:** Cloudflare Pages' new Workers integration is currently in beta.
-> Compared to `adapter-cloudflare-workers`, `adapter-cloudflare` is the preferred approach for most users since building on top of Pages unlocks automatic builds and deploys, preview deployments, instant rollbacks, etc.
-> From SvelteKit's perspective, there is no difference and no functionality loss when migrating to/from the Workers and the Pages adapters. - -## Usage - -Install with `npm i -D @sveltejs/adapter-cloudflare-workers`, then add the adapter to your `svelte.config.js`: - -```js -import adapter from '@sveltejs/adapter-cloudflare-workers'; - -export default { - kit: { - adapter: adapter() - } -}; -``` - -## Basic Configuration - -This adapter expects to find a [wrangler.toml](https://developers.cloudflare.com/workers/platform/sites/configuration) file in the project root. It should look something like this: - -```toml -name = "" -account_id = "" - -main = "./.cloudflare/worker.js" -site.bucket = "./.cloudflare/public" - -build.command = "npm run build" - -compatibility_date = "2021-11-12" -workers_dev = true -``` - -`` can be anything. `` can be found by logging into your [Cloudflare dashboard](https://dash.cloudflare.com) and grabbing it from the end of the URL: - -``` -https://dash.cloudflare.com/ -``` - -> It's recommended that you add the `.cloudflare` directory (or whichever directories you specified for `main` and `site.bucket`) to your `.gitignore`. - -You will need to install [wrangler](https://developers.cloudflare.com/workers/wrangler/get-started/) and log in, if you haven't already: - -``` -npm i -g wrangler -wrangler login -``` - -Then, you can build your app and deploy it: - -```sh -wrangler publish -``` - -## Custom config - -If you would like to use a config file other than `wrangler.toml`, you can do like so: - -```js -import adapter from '@sveltejs/adapter-cloudflare-workers'; - -export default { - kit: { - adapter: adapter({ config: '.toml' }) - } -}; -``` - -## Environment variables - -The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object, containing KV/DO namespaces etc, is passed to SvelteKit via the `platform` property along with `context` and `caches`, meaning you can access it in hooks and endpoints: - -```js -export async function POST({ request, platform }) { - const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); -} -``` - -To make these types available to your app, reference them in your `src/app.d.ts`: - -```diff -/// -+/// - -declare namespace App { - interface Platform { -+ env?: { -+ YOUR_KV_NAMESPACE: KVNamespace; -+ YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace; -+ }; - } -} -``` - -> `platform.env` is only available in the production build. Use [wrangler](https://developers.cloudflare.com/workers/cli-wrangler) to test it locally - -## Troubleshooting - -### Accessing the file system - -You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. +[Docs](https://kit.svelte.dev/docs/adapter-cloudflare-workers) ## Changelog diff --git a/packages/adapter-cloudflare/README.md b/packages/adapter-cloudflare/README.md index 5843bb29b12c..775351116cc0 100644 --- a/packages/adapter-cloudflare/README.md +++ b/packages/adapter-cloudflare/README.md @@ -2,96 +2,9 @@ [Adapter](https://kit.svelte.dev/docs/building-your-app) for building SvelteKit applications on [Cloudflare Pages](https://developers.cloudflare.com/pages/) with [Workers integration](https://developers.cloudflare.com/pages/platform/functions). -If you're using [adapter-auto](../adapter-auto), you don't need to install this — it's already included. +## Docs -_**Comparisons**_ - -- `adapter-cloudflare` – supports all SvelteKit features; builds for - [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) -- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for - Cloudflare Workers -- `adapter-static` – only produces client-side static assets; compatible with - Cloudflare Pages - -> **Note:** Cloudflare Pages' new Workers integration is currently in beta.
-> Compared to `adapter-cloudflare-workers`, this adapter will be the preferred approach for most users since building on top of Pages unlocks automatic builds and deploys, preview deployments, instant rollbacks, etc.
-> From SvelteKit's perspective, there is no difference and no functionality loss when migrating to/from the Workers and the Pages adapters. - -## Installation - -```sh -$ npm i --save-dev @sveltejs/adapter-cloudflare -``` - -## Usage - -You can include these changes in your `svelte.config.js` configuration file: - -```js -import adapter from '@sveltejs/adapter-cloudflare'; - -export default { - kit: { - adapter: adapter() - } -}; -``` - -## Deployment - -Please follow the [Get Started Guide](https://developers.cloudflare.com/pages/get-started) for Cloudflare Pages to begin. - -When configuring your project settings, you must use the following settings: - -- **Framework preset** – None -- **Build command** – `npm run build` or `svelte-kit build` -- **Build output directory** – `.svelte-kit/cloudflare` -- **Environment variables** - - `NODE_VERSION`: `16` - -> **Important:** You need to add a `NODE_VERSION` environment variable to both the "production" and "preview" environments. You can add this during project setup or later in the Pages project settings. SvelteKit requires Node `16.14` or later, so you should use `16` as the `NODE_VERSION` value. - -## Environment variables - -The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object, containing KV/DO namespaces etc, is passed to SvelteKit via the `platform` property along with `context` and `caches`, meaning you can access it in hooks and endpoints: - -```js -export async function POST({ request, platform }) { - const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); -} -``` - -To make these types available to your app, reference them in your `src/app.d.ts`: - -```diff -/// -+/// - -declare namespace App { - interface Platform { -+ env?: { -+ YOUR_KV_NAMESPACE: KVNamespace; -+ YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace; -+ }; - } -} -``` - -> `platform.env` is only available in the production build. Use [wrangler](https://developers.cloudflare.com/workers/cli-wrangler) to test it locally - -## Notes - -Functions contained in the `/functions` directory at the project's root will _not_ be included in the deployment, which is compiled to a [single `_worker.js` file](https://developers.cloudflare.com/pages/platform/functions/#advanced-mode). Functions should be implemented as [server endpoints](https://kit.svelte.dev/docs/routing#server) in your SvelteKit app. - -The [`_headers` and `_redirects`](config files) files specific to Cloudflare Pages can be used for static asset responses (like images) by putting them into the `/static` folder. - -However, they will have no effect on responses dynamically rendered by SvelteKit, which should return custom headers or redirect responses from [server endpoints](https://kit.svelte.dev/docs/routing#server) or with the [`handle`](https://kit.svelte.dev/docs/hooks#server-hooks-handle) hook. - -## Troubleshooting - -### Accessing the file system - -You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. +[Docs](https://kit.svelte.dev/docs/adapter-cloudflare) ## Changelog diff --git a/packages/adapter-netlify/README.md b/packages/adapter-netlify/README.md index f6a34c470079..ccbd34426b0f 100644 --- a/packages/adapter-netlify/README.md +++ b/packages/adapter-netlify/README.md @@ -2,113 +2,11 @@ A SvelteKit adapter that creates a Netlify app. -If you're using [adapter-auto](../adapter-auto), you don't need to install this unless you need to specify Netlify-specific options, since it's already included. +If you're using [adapter-auto](https://kit.svelte.dev/docs/adapter-auto), you don't need to install this unless you need to specify Netlify-specific options, since it's already included. -## Installation +## Docs -```bash -npm i -D @sveltejs/adapter-netlify -``` - -You can then configure it inside of `svelte.config.js`: - -```js -import adapter from '@sveltejs/adapter-netlify'; - -export default { - kit: { - // default options are shown - adapter: adapter({ - // if true, will create a Netlify Edge Function rather - // than using standard Node-based functions - edge: false, - - // if true, will split your app into multiple functions - // instead of creating a single one for the entire app. - // if `edge` is true, this option cannot be used - split: false - }) - } -}; -``` - -Then, make sure you have a [netlify.toml](https://docs.netlify.com/configure-builds/file-based-configuration) file in the project root. This will determine where to write static assets based on the `build.publish` settings, as per this sample configuration: - -```toml -[build] - command = "npm run build" - publish = "build" -``` - -If the `netlify.toml` file or the `build.publish` value is missing, a default value of `"build"` will be used. Note that if you have set the publish directory in the Netlify UI to something else then you will need to set it in `netlify.toml` too, or use the default value of `"build"`. - -### Node version - -New projects will use Node 16 by default. However, if you're upgrading a project you created a while ago it may be stuck on an older version. See [the Netlify docs](https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript) for details on manually specifying Node 16 or newer. - -## Netlify Edge Functions (beta) - -SvelteKit supports the beta release of [Netlify Edge Functions](https://docs.netlify.com/netlify-labs/experimental-features/edge-functions/). If you pass the option `edge: true` to the `adapter` function, server-side rendering will happen in a Deno-based edge function that's deployed close to the site visitor. If set to `false` (the default), the site will deploy to standard Node-based Netlify Functions. - -```js -import adapter from '@sveltejs/adapter-netlify'; - -export default { - kit: { - adapter: adapter({ - // will create a Netlify Edge Function using Deno-based - // rather than using standard Node-based functions - edge: true - }) - } -}; -``` - -## Netlify alternatives to SvelteKit functionality - -You may build your app using functionality provided directly by SvelteKit without relying on any Netlify functionality. Using the SvelteKit versions of these features will allow them to be used in dev mode, tested with integration tests, and to work with other adapters should you ever decide to switch away from Netlify. However, in some scenarios you may find it beneficial to use the Netlify versions of these features. One example would be if you're migrating an app that's already hosted on Netlify to SvelteKit. - -### Using Netlify Redirect Rules - -During compilation, redirect rules are automatically appended to your `_redirects` file. (If it doesn't exist yet, it will be created.) That means: - -- `[[redirects]]` in `netlify.toml` will never match as `_redirects` has a [higher priority](https://docs.netlify.com/routing/redirects/#rule-processing-order). So always put your rules in the [`_redirects` file](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file). -- `_redirects` shouldn't have any custom "catch all" rules such as `/* /foobar/:splat`. Otherwise the automatically appended rule will never be applied as Netlify is only processing [the first matching rule](https://docs.netlify.com/routing/redirects/#rule-processing-order). - -### Using Netlify Forms - -1. Create your Netlify HTML form as described [here](https://docs.netlify.com/forms/setup/#html-forms), e.g. as `/routes/contact.svelte`. (Don't forget to add the hidden `form-name` input element!) -2. Netlify's build bot parses your HTML files at deploy time, which means your form must be [prerendered](https://kit.svelte.dev/docs/page-options#prerender) as HTML. You can either add `export const prerender = true` to your `contact.svelte` to prerender just that page or set the `kit.prerender.force: true` option to prerender all pages. -3. If your Netlify form has a [custom success message](https://docs.netlify.com/forms/setup/#success-messages) like `` then ensure the corresponding `/routes/success.svelte` exists and is prerendered. - -### Using Netlify Functions - -With this adapter, SvelteKit endpoints are hosted as [Netlify Functions](https://docs.netlify.com/functions/overview/). Netlify function handlers have additional context, including [Netlify Identity](https://docs.netlify.com/visitor-access/identity/) information. You can access this context via the `event.platform.context` field inside your hooks and `+page.server` or `+layout.server` endpoints. These are [serverless functions](https://docs.netlify.com/functions/overview/) when the `edge` property is `false` in the adapter config or [edge functions](https://docs.netlify.com/edge-functions/overview/#app) when it is `true`. - -```js -// +page.server.js -export const load = async (event) => { - const context = event.platform.context; - console.log(context); // shows up in your functions log in the Netlify app -}; -``` - -Additionally, you can add your own Netlify functions by creating a directory for them and adding the configuration to your `netlify.toml` file. For example: - -```toml -[build] - command = "npm run build" - publish = "build" - -[functions] - directory = "functions" -``` - -## Troubleshooting - -### Accessing the file system - -You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. +[Docs](https://kit.svelte.dev/docs/adapter-netlify) ## Changelog diff --git a/packages/adapter-node/README.md b/packages/adapter-node/README.md index e4837adeddc3..100a2687a4bb 100644 --- a/packages/adapter-node/README.md +++ b/packages/adapter-node/README.md @@ -1,191 +1,10 @@ # @sveltejs/adapter-node -[Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that generates a standalone Node server. +[Adapter](https://kit.svelte.dev/docs/adapters) for SvelteKit apps that generates a standalone Node server. -## Usage +## Docs -Install with `npm i -D @sveltejs/adapter-node`, then add the adapter to your `svelte.config.js`: - -```js -// svelte.config.js -import adapter from '@sveltejs/adapter-node'; - -export default { - kit: { - adapter: adapter() - } -}; -``` - -## Deploying - -You will need the output directory (`build` by default), the project's `package.json`, and the production dependencies in `node_modules` to run the application. Production dependencies can be generated with `npm ci --prod` (you can skip this step if your app doesn't have any dependencies). You can then start your app with - -```bash -node build -``` - -Development dependencies will be bundled into your app using `rollup`. To control whether a given package is bundled or externalised, place it in `devDependencies` or `dependencies` respectively in your `package.json`. - -## Environment variables - -In `dev` and `preview`, SvelteKit will read environent variables from your `.env` file (or `.env.local`, or `.env.[mode]`, [as determined by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files).) - -In production, `.env` files are _not_ automatically loaded. To do so, install `dotenv` in your project... - -```bash -npm install dotenv -``` - -...and invoke it before running the built app: - -```diff --node build -+node -r dotenv/config build -``` - -### `PORT` and `HOST` - -By default, the server will accept connections on `0.0.0.0` using port 3000. These can be customised with the `PORT` and `HOST` environment variables: - -``` -HOST=127.0.0.1 PORT=4000 node build -``` - -### `ORIGIN`, `PROTOCOL_HEADER` and `HOST_HEADER` - -HTTP doesn't give SvelteKit a reliable way to know the URL that is currently being requested. The simplest way to tell SvelteKit where the app is being served is to set the `ORIGIN` environment variable: - -``` -ORIGIN=https://my.site node build -``` - -With this, a request for the `/stuff` pathname will correctly resolve to `https://my.site/stuff`. Alternatively, you can specify headers that tell SvelteKit about the request protocol and host, from which it can construct the origin URL: - -``` -PROTOCOL_HEADER=x-forwarded-proto HOST_HEADER=x-forwarded-host node build -``` - -> [`x-forwarded-proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) and [`x-forwarded-host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) are de facto standard headers that forward the original protocol and host if you're using a reverse proxy (think load balancers and CDNs). You should only set these variables if your server is behind a trusted reverse proxy; otherwise, it'd be possible for clients to spoof these headers. - -If `adapter-node` can't correctly determine the URL of your deployment, you may experience this error when using [form actions](https://kit.svelte.dev/docs/form-actions): - -> Cross-site POST form submissions are forbidden - -### `ADDRESS_HEADER` and `XFF_DEPTH` - -The [RequestEvent](https://kit.svelte.dev/docs/types#public-types-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: - -``` -ADDRESS_HEADER=True-Client-IP node build -``` - -> Headers can easily be spoofed. As with `PROTOCOL_HEADER` and `HOST_HEADER`, you should [know what you're doing](https://adam-p.ca/blog/2022/03/x-forwarded-for/) before setting these. - -If the `ADDRESS_HEADER` is `X-Forwarded-For`, the header value will contain a comma-separated list of IP addresses. The `XFF_DEPTH` environment variable should specify how many trusted proxies sit in front of your server. E.g. if there are three trusted proxies, proxy 3 will forward the addresses of the original connection and the first two proxies: - -``` -, , -``` - -Some guides will tell you to read the left-most address, but this leaves you [vulnerable to spoofing](https://adam-p.ca/blog/2022/03/x-forwarded-for/): - -``` -, , , -``` - -Instead, we read from the _right_, accounting for the number of trusted proxies. In this case, we would use `XFF_DEPTH=3`. - -> If you need to read the left-most address instead (and don't care about spoofing) — for example, to offer a geolocation service, where it's more important for the IP address to be _real_ than _trusted_, you can do so by inspecting the `x-forwarded-for` header within your app. - -### `BODY_SIZE_LIMIT` - -The maximum request body size to accept in bytes including while streaming. Defaults to 512kb. You can disable this option with a value of 0 and implement a custom check in [`handle`](https://kit.svelte.dev/docs/hooks#server-hooks-handle) if you need something more advanced. - -## Options - -The adapter can be configured with various options: - -```js -// svelte.config.js -import adapter from '@sveltejs/adapter-node'; - -export default { - kit: { - adapter: adapter({ - // default options are shown - out: 'build', - precompress: false, - envPrefix: '' - }) - } -}; -``` - -### out - -The directory to build the server to. It defaults to `build` — i.e. `node build` would start the server locally after it has been created. - -### precompress - -Enables precompressing using gzip and brotli for assets and prerendered pages. It defaults to `false`. - -### envPrefix - -If you need to change the name of the environment variables used to configure the deployment (for example, to deconflict with environment variables you don't control), you can specify a prefix: - -```js -envPrefix: 'MY_CUSTOM_'; -``` - -``` -MY_CUSTOM_HOST=127.0.0.1 \ -MY_CUSTOM_PORT=4000 \ -MY_CUSTOM_ORIGIN=https://my.site \ -node build -``` - -## Custom server - -The adapter creates two files in your build directory — `index.js` and `handler.js`. Running `index.js` — e.g. `node build`, if you use the default build directory — will start a server on the configured port. - -Alternatively, you can import the `handler.js` file, which exports a handler suitable for use with [Express](https://github.com/expressjs/expressjs.com), [Connect](https://github.com/senchalabs/connect) or [Polka](https://github.com/lukeed/polka) (or even just the built-in [`http.createServer`](https://nodejs.org/dist/latest/docs/api/http.html#httpcreateserveroptions-requestlistener)) and set up your own server: - -```js -// my-server.js -import { handler } from './build/handler.js'; -import express from 'express'; - -const app = express(); - -// add a route that lives separately from the SvelteKit app -app.get('/healthcheck', (req, res) => { - res.end('ok'); -}); - -// let SvelteKit handle everything else, including serving prerendered pages and static assets -app.use(handler); - -app.listen(3000, () => { - console.log('listening on port 3000'); -}); -``` - -## Troubleshooting - -### Is there a hook for cleaning up before the server exits? - -There's nothing built-in to SvelteKit for this, because such a cleanup hook depends highly on the execution environment you're on. For Node, you can use its built-in `process.on(..)` to implement a callback that runs before the server exits: - -```js -function shutdownGracefully() { - // anything you need to clean up manually goes in here - db.shutdown(); -} - -process.on('SIGINT', shutdownGracefully); -process.on('SIGTERM', shutdownGracefully); -``` +[Docs](https://kit.svelte.dev/docs/adapter-cloudflare) ## Changelog diff --git a/packages/adapter-static/README.md b/packages/adapter-static/README.md index 54cfd6afb717..6db4b8a1b4a9 100644 --- a/packages/adapter-static/README.md +++ b/packages/adapter-static/README.md @@ -1,183 +1,10 @@ # @sveltejs/adapter-static -[Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that prerenders your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with [the `prerender` option](https://kit.svelte.dev/docs/page-options#prerender). +[Adapter](https://kit.svelte.dev/docs/adapters) for SvelteKit apps that prerenders your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with [the `prerender` option](https://kit.svelte.dev/docs/page-options#prerender). -## Usage +## Docs -Install with `npm i -D @sveltejs/adapter-static`, then add the adapter to your `svelte.config.js`... - -```js -// svelte.config.js -import adapter from '@sveltejs/adapter-static'; - -export default { - kit: { - adapter: adapter({ - // default options are shown. On some platforms - // these options are set automatically — see below - pages: 'build', - assets: 'build', - fallback: null, - precompress: false, - strict: true - }) - } -}; -``` - -...and add the [`prerender`](https://kit.svelte.dev/docs/page-options#prerender) option to your root layout: - -```js -// src/routes/+layout.js - -// This can be false if you're using a fallback (i.e. SPA mode) -export const prerender = true; -``` - -> ⚠️ You must ensure SvelteKit's [`trailingSlash`](https://kit.svelte.dev/docs/page-options#trailingslash) option is set appropriately for your environment. If your host does not render `/a.html` upon receiving a request for `/a` then you will need to set `trailingSlash: 'always'` to create `/a/index.html` instead. - -## Zero-config support - -Some platforms have zero-config support (more to come in future): - -- [Vercel](https://vercel.com) - -On these platforms, you should omit the adapter options so that `adapter-static` can provide the optimal configuration: - -```diff -export default { - kit: { -- adapter: adapter({...}), -+ adapter: adapter(), - } - } -}; -``` - -## Options - -### pages - -The directory to write prerendered pages to. It defaults to `build`. - -### assets - -The directory to write static assets (the contents of `static`, plus client-side JS and CSS generated by SvelteKit) to. Ordinarily this should be the same as `pages`, and it will default to whatever the value of `pages` is, but in rare circumstances you might need to output pages and assets to separate locations. - -### fallback - -Specify a fallback page for SPA mode, e.g. `index.html` or `200.html` or `404.html`. - -### precompress - -If `true`, precompresses files with brotli and gzip. This will generate `.br` and `.gz` files. - -### strict - -By default, `adapter-static` checks that either all pages and endpoints (if any) of your app were prerendered, or you have the `fallback` option set. This check exists to prevent you from accidentally publishing an app where some parts of it are not accessible, because they are not contained in the final output. If you know this is ok (for example when a certain page only exists conditionally), you can set `strict` to `false` to turn off this check. - -## SPA mode - -You can use `adapter-static` to create a single-page app or SPA by specifying a **fallback page**. - -> In most situations this is not recommended: it harms SEO, tends to slow down perceived performance, and makes your app inaccessible to users if JavaScript fails or is disabled (which happens [more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)). - -If you want to create a simple SPA with no prerendered routes, the necessary config looks like this: - -```js -// svelte.config.js -import adapter from '@sveltejs/adapter-static'; - -export default { - kit: { - adapter: adapter({ - fallback: '200.html' - }), - prerender: { entries: [] } - } -}; -``` - -```js -// src/routes/+layout.js -export const ssr = false; -``` - -You can also turn only part of your app into an SPA. - -Let's go through these options one by one: - -### Add fallback page - -The fallback page is an HTML page created by SvelteKit that loads your app and navigates to the correct route. For example [Surge](https://surge.sh/help/adding-a-200-page-for-client-side-routing), a static web host, lets you add a `200.html` file that will handle any requests that don't correspond to static assets or prerendered pages. We can create that file like so: - -```js -// svelte.config.js -import adapter from '@sveltejs/adapter-static'; - -export default { - kit: { - adapter: adapter({ - fallback: '200.html' - }) - } -}; -``` - -> How to configure this behaviour does however depend on your hosting solution and is not part of SvelteKit. It is recommended to search the host's documentation on how to redirect requests. - -### Turn off prerendering - -When operating in SPA mode, you can omit the [`prerender`](https://kit.svelte.dev/docs/page-options#prerender) option from your root layout (or set it to `false`, its default value), and only pages that have the `prerender` option set will be prerendered at build time. - -SvelteKit will still crawl your app's entry points looking for prerenderable pages. If `svelte-kit build` fails because of pages that can't be loaded outside the browser, you can set `config.kit.prerender.entries` to `[]` to prevent this from happening. (Setting `config.kit.prerender.enabled` to `false` also has this effect, but would prevent the fallback page from being generated.) - -You can also add turn off prerendering only to parts of your app, if you want other parts to be prerendered. - -### Turn off ssr - -During development, SvelteKit will still attempt to server-side render your routes. This means accessing things that are only available in the browser (such as the `window` object) will result in errors, even though this would be valid in the output app. To align the behavior of SvelteKit's dev mode with your SPA, you can [add `export const ssr = false` to your root `+layout`](https://kit.svelte.dev/docs/page-options#ssr). You can also add this option only to parts of your app, if you want other parts to be prerendered. - -### Apache - -To run an SPA on [Apache](https://httpd.apache.org/), you should add a `static/.htaccess` file to route requests to the fallback page: - -``` - - RewriteEngine On - RewriteBase / - RewriteRule ^200\.html$ - [L] - RewriteCond %{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_FILENAME} !-d - RewriteRule . /200.html [L] - -``` - -## GitHub Pages - -When building for GitHub Pages, make sure to update [`paths.base`](https://kit.svelte.dev/docs/configuration#paths) to match your repo name, since the site will be served from rather than from the root. - -You will have to prevent GitHub's provided Jekyll from managing your site by putting an empty `.nojekyll` file in your static folder. If you do not want to disable Jekyll, change the kit's `appDir` configuration option to `'app_'` or anything not starting with an underscore. For more information, see GitHub's [Jekyll documentation](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#configuring-jekyll-in-your-github-pages-site). - -A config for GitHub Pages might look like the following: - -```js -const dev = process.argv.includes('dev'); - -/** @type {import('@sveltejs/kit').Config} */ -const config = { - ... - kit: { - ... - paths: { - base: dev ? '' : '/your-repo-name', - }, - // If you are not using a .nojekyll file, change your appDir to something not starting with an underscore. - // For example, instead of '_app', use 'app_', 'internal', etc. - appDir: 'internal', - } -}; -``` +[Docs](https://kit.svelte.dev/docs/adapter-cloudflare) ## Changelog diff --git a/packages/adapter-vercel/README.md b/packages/adapter-vercel/README.md index 5a5e8a2c1b62..372dec3f27dc 100644 --- a/packages/adapter-vercel/README.md +++ b/packages/adapter-vercel/README.md @@ -2,83 +2,11 @@ A SvelteKit adapter that creates a Vercel app. -If you're using [adapter-auto](../adapter-auto), you don't need to install this unless you need to specify Vercel-specific options, since it's already included. +If you're using [adapter-auto](https://kit.svelte.dev/docs/adapter-auto), you don't need to install this unless you need to specify Vercel-specific options, since it's already included. -## Usage +## Docs -Add `"@sveltejs/adapter-vercel": "next"` to the `devDependencies` in your `package.json` and run `npm install`. - -Then in your `svelte.config.js`: - -```js -import vercel from '@sveltejs/adapter-vercel'; - -export default { - kit: { - // default options are shown - adapter: vercel({ - // if true, will deploy the app using edge functions - // (https://vercel.com/docs/concepts/functions/edge-functions) - // rather than serverless functions - edge: false, - - // an array of dependencies that esbuild should treat - // as external when bundling functions - external: [], - - // if true, will split your app into multiple functions - // instead of creating a single one for the entire app - split: false - }) - } -}; -``` - -## Environment Variables - -Vercel makes a set of [deployment-specific environment variables](https://vercel.com/docs/concepts/projects/environment-variables#system-environment-variables) available. Like other environment variables, these are accessible from `$env/static/private` and `$env/dynamic/private` (sometimes — more on that later), and inaccessible from their public counterparts. To access one of these variables from the client: - -```js -// +layout.server.js -import { VERCEL_COMMIT_REF } from '$env/static/private'; - -/** @type {import('./$types').LayoutServerLoad} */ -export function load() { - return { - deploymentGitBranch: VERCEL_COMMIT_REF - }; -} -``` - -```svelte - - - -

This staging environment was deployed from {data.deploymentGitBranch}.

-``` - -Since all of these variables are unchanged between build time and run time when building on Vercel, we recommend using `$env/static/private` — which will statically replace the variables, enabling optimisations like dead code elimination — rather than `$env/dynamic/private`. If you're deploying with `edge: true` you _must_ use `$env/static/private`, as `$env/dynamic/private` and `$env/dynamic/public` are not currently populated in edge functions on Vercel. - -## Notes - -### Vercel functions - -Vercel functions contained in the `/api` directory at the project's root will _not_ be included in the deployment — these should be implemented as [server endpoints](https://kit.svelte.dev/docs/routing#server) in your SvelteKit app. - -### Node version - -Projects created before a certain date will default to using Node 14, while SvelteKit requires Node 16 or later. You can change that in your project settings: - -![Vercel project settings](settings.png) - -## Troubleshooting - -### Accessing the file system - -You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. +[Docs](https://kit.svelte.dev/docs/adapter-cloudflare) ## Changelog diff --git a/packages/kit/types/ambient.d.ts b/packages/kit/types/ambient.d.ts index 772f0b2c0ca3..a8bd4cf9fc06 100644 --- a/packages/kit/types/ambient.d.ts +++ b/packages/kit/types/ambient.d.ts @@ -59,7 +59,7 @@ declare namespace App { export interface PageData {} /** - * If your adapter provides [platform-specific context](https://kit.svelte.dev/docs/building-your-app#supported-environments-platform-specific-context) via `event.platform`, you can specify it here. + * If your adapter provides [platform-specific context](https://kit.svelte.dev/docs/adapters#supported-environments-platform-specific-context) via `event.platform`, you can specify it here. */ export interface Platform {} } From 9e976e3cb7ddda896d5ce2259bc45c20e2df9989 Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Sat, 14 Jan 2023 15:59:20 -0800 Subject: [PATCH 04/23] update page titles --- .../docs/25-building-your-app/40-adapter-cloudflare.md | 2 +- .../docs/25-building-your-app/50-adapter-cloudflare-workers.md | 2 +- documentation/docs/25-building-your-app/60-adapter-netlify.md | 2 +- documentation/docs/25-building-your-app/70-adapter-node.md | 2 +- documentation/docs/25-building-your-app/90-adapter-vercel.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/docs/25-building-your-app/40-adapter-cloudflare.md b/documentation/docs/25-building-your-app/40-adapter-cloudflare.md index 6679fa2bc317..9035f71a04df 100644 --- a/documentation/docs/25-building-your-app/40-adapter-cloudflare.md +++ b/documentation/docs/25-building-your-app/40-adapter-cloudflare.md @@ -1,5 +1,5 @@ --- -title: adapter-cloudflare +title: Cloudflare --- [Adapter](https://kit.svelte.dev/docs/building-your-app) for building SvelteKit applications on [Cloudflare Pages](https://developers.cloudflare.com/pages/) with [Workers integration](https://developers.cloudflare.com/pages/platform/functions). diff --git a/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md b/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md index e0e67bc86e11..eccf8f01ebb2 100644 --- a/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md +++ b/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md @@ -1,5 +1,5 @@ --- -title: adapter-cloudflare-workers +title: Cloudflare Workers --- SvelteKit adapter that creates a Cloudflare Workers site using a function for dynamic server rendering. diff --git a/documentation/docs/25-building-your-app/60-adapter-netlify.md b/documentation/docs/25-building-your-app/60-adapter-netlify.md index f4c6355b603e..33cb34e9b555 100644 --- a/documentation/docs/25-building-your-app/60-adapter-netlify.md +++ b/documentation/docs/25-building-your-app/60-adapter-netlify.md @@ -1,5 +1,5 @@ --- -title: adapter-netlify +title: Netlify --- A SvelteKit adapter that creates a Netlify app. diff --git a/documentation/docs/25-building-your-app/70-adapter-node.md b/documentation/docs/25-building-your-app/70-adapter-node.md index bd9082cc39ae..0f8a64f59940 100644 --- a/documentation/docs/25-building-your-app/70-adapter-node.md +++ b/documentation/docs/25-building-your-app/70-adapter-node.md @@ -1,5 +1,5 @@ --- -title: adapter-node +title: Node --- [Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that generates a standalone Node server. diff --git a/documentation/docs/25-building-your-app/90-adapter-vercel.md b/documentation/docs/25-building-your-app/90-adapter-vercel.md index 737d020741b9..56a3864c6a5d 100644 --- a/documentation/docs/25-building-your-app/90-adapter-vercel.md +++ b/documentation/docs/25-building-your-app/90-adapter-vercel.md @@ -1,5 +1,5 @@ --- -title: adapter-vercel +title: Vercel --- A SvelteKit adapter that creates a Vercel app. From 26663c39b6a6a3737513829309ecd0f7421bd943 Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Sat, 14 Jan 2023 19:25:44 -0800 Subject: [PATCH 05/23] ignore typescript errors --- .../25-building-your-app/40-adapter-cloudflare.md | 3 +++ .../50-adapter-cloudflare-workers.md | 5 +++++ .../docs/25-building-your-app/60-adapter-netlify.md | 7 ++++++- .../docs/25-building-your-app/70-adapter-node.md | 10 +++++++--- .../docs/25-building-your-app/80-adapter-static.md | 12 +++++++----- .../docs/25-building-your-app/90-adapter-vercel.md | 5 ++++- 6 files changed, 32 insertions(+), 10 deletions(-) diff --git a/documentation/docs/25-building-your-app/40-adapter-cloudflare.md b/documentation/docs/25-building-your-app/40-adapter-cloudflare.md index 9035f71a04df..94a9fc3d728b 100644 --- a/documentation/docs/25-building-your-app/40-adapter-cloudflare.md +++ b/documentation/docs/25-building-your-app/40-adapter-cloudflare.md @@ -30,6 +30,8 @@ $ npm i --save-dev @sveltejs/adapter-cloudflare You can include these changes in your `svelte.config.js` configuration file: ```js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-cloudflare'; export default { @@ -58,6 +60,7 @@ When configuring your project settings, you must use the following settings: The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object, containing KV/DO namespaces etc, is passed to SvelteKit via the `platform` property along with `context` and `caches`, meaning you can access it in hooks and endpoints: ```js +// @errors: 7031 export async function POST({ request, platform }) { const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); } diff --git a/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md b/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md index eccf8f01ebb2..3be7e35eb3b2 100644 --- a/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md +++ b/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md @@ -24,6 +24,8 @@ _**Comparisons**_ Install with `npm i -D @sveltejs/adapter-cloudflare-workers`, then add the adapter to your `svelte.config.js`: ```js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-cloudflare-workers'; export default { @@ -76,6 +78,8 @@ wrangler publish If you would like to use a config file other than `wrangler.toml`, you can do like so: ```js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-cloudflare-workers'; export default { @@ -90,6 +94,7 @@ export default { The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#parameters) object, containing KV/DO namespaces etc, is passed to SvelteKit via the `platform` property along with `context` and `caches`, meaning you can access it in hooks and endpoints: ```js +// @errors: 7031 export async function POST({ request, platform }) { const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); } diff --git a/documentation/docs/25-building-your-app/60-adapter-netlify.md b/documentation/docs/25-building-your-app/60-adapter-netlify.md index 33cb34e9b555..8b2ee2284700 100644 --- a/documentation/docs/25-building-your-app/60-adapter-netlify.md +++ b/documentation/docs/25-building-your-app/60-adapter-netlify.md @@ -15,6 +15,8 @@ npm i -D @sveltejs/adapter-netlify You can then configure it inside of `svelte.config.js`: ```js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-netlify'; export default { @@ -53,6 +55,8 @@ New projects will use Node 16 by default. However, if you're upgrading a project SvelteKit supports the beta release of [Netlify Edge Functions](https://docs.netlify.com/netlify-labs/experimental-features/edge-functions/). If you pass the option `edge: true` to the `adapter` function, server-side rendering will happen in a Deno-based edge function that's deployed close to the site visitor. If set to `false` (the default), the site will deploy to standard Node-based Netlify Functions. ```js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-netlify'; export default { @@ -88,7 +92,8 @@ During compilation, redirect rules are automatically appended to your `_redirect With this adapter, SvelteKit endpoints are hosted as [Netlify Functions](https://docs.netlify.com/functions/overview/). Netlify function handlers have additional context, including [Netlify Identity](https://docs.netlify.com/visitor-access/identity/) information. You can access this context via the `event.platform.context` field inside your hooks and `+page.server` or `+layout.server` endpoints. These are [serverless functions](https://docs.netlify.com/functions/overview/) when the `edge` property is `false` in the adapter config or [edge functions](https://docs.netlify.com/edge-functions/overview/#app) when it is `true`. ```js -// +page.server.js +// @errors: 2705 7006 +/// file: +page.server.js export const load = async (event) => { const context = event.platform.context; console.log(context); // shows up in your functions log in the Netlify app diff --git a/documentation/docs/25-building-your-app/70-adapter-node.md b/documentation/docs/25-building-your-app/70-adapter-node.md index 0f8a64f59940..ba685092f407 100644 --- a/documentation/docs/25-building-your-app/70-adapter-node.md +++ b/documentation/docs/25-building-your-app/70-adapter-node.md @@ -9,7 +9,8 @@ title: Node Install with `npm i -D @sveltejs/adapter-node`, then add the adapter to your `svelte.config.js`: ```js -// svelte.config.js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-node'; export default { @@ -109,7 +110,8 @@ The maximum request body size to accept in bytes including while streaming. Defa The adapter can be configured with various options: ```js -// svelte.config.js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-node'; export default { @@ -154,7 +156,8 @@ The adapter creates two files in your build directory — `index.js` and `handle Alternatively, you can import the `handler.js` file, which exports a handler suitable for use with [Express](https://github.com/expressjs/expressjs.com), [Connect](https://github.com/senchalabs/connect) or [Polka](https://github.com/lukeed/polka) (or even just the built-in [`http.createServer`](https://nodejs.org/dist/latest/docs/api/http.html#httpcreateserveroptions-requestlistener)) and set up your own server: ```js -// my-server.js +// @errors: 2307 7006 +/// file: my-server.js import { handler } from './build/handler.js'; import express from 'express'; @@ -180,6 +183,7 @@ app.listen(3000, () => { There's nothing built-in to SvelteKit for this, because such a cleanup hook depends highly on the execution environment you're on. For Node, you can use its built-in `process.on(..)` to implement a callback that runs before the server exits: ```js +// @errors: 2304 2580 function shutdownGracefully() { // anything you need to clean up manually goes in here db.shutdown(); diff --git a/documentation/docs/25-building-your-app/80-adapter-static.md b/documentation/docs/25-building-your-app/80-adapter-static.md index 8a5001be38b1..b495dc13ff5e 100644 --- a/documentation/docs/25-building-your-app/80-adapter-static.md +++ b/documentation/docs/25-building-your-app/80-adapter-static.md @@ -9,7 +9,8 @@ title: adapter-static Install with `npm i -D @sveltejs/adapter-static`, then add the adapter to your `svelte.config.js`... ```js -// svelte.config.js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-static'; export default { @@ -87,7 +88,8 @@ You can use `adapter-static` to create a single-page app or SPA by specifying a If you want to create a simple SPA with no prerendered routes, the necessary config looks like this: ```js -// svelte.config.js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-static'; export default { @@ -114,7 +116,8 @@ Let's go through these options one by one: The fallback page is an HTML page created by SvelteKit that loads your app and navigates to the correct route. For example [Surge](https://surge.sh/help/adding-a-200-page-for-client-side-routing), a static web host, lets you add a `200.html` file that will handle any requests that don't correspond to static assets or prerendered pages. We can create that file like so: ```js -// svelte.config.js +// @errors: 2307 +/// file: svelte.config.js import adapter from '@sveltejs/adapter-static'; export default { @@ -164,13 +167,12 @@ You will have to prevent GitHub's provided Jekyll from managing your site by put A config for GitHub Pages might look like the following: ```js +/// file: svelte.config.js const dev = process.argv.includes('dev'); /** @type {import('@sveltejs/kit').Config} */ const config = { - ... kit: { - ... paths: { base: dev ? '' : '/your-repo-name', }, diff --git a/documentation/docs/25-building-your-app/90-adapter-vercel.md b/documentation/docs/25-building-your-app/90-adapter-vercel.md index 56a3864c6a5d..41121c4cdd21 100644 --- a/documentation/docs/25-building-your-app/90-adapter-vercel.md +++ b/documentation/docs/25-building-your-app/90-adapter-vercel.md @@ -13,6 +13,8 @@ Add `"@sveltejs/adapter-vercel": "next"` to the `devDependencies` in your `packa Then in your `svelte.config.js`: ```js +// @errors: 2307 +/// file: svelte.config.js import vercel from '@sveltejs/adapter-vercel'; export default { @@ -41,7 +43,8 @@ export default { Vercel makes a set of [deployment-specific environment variables](https://vercel.com/docs/concepts/projects/environment-variables#system-environment-variables) available. Like other environment variables, these are accessible from `$env/static/private` and `$env/dynamic/private` (sometimes — more on that later), and inaccessible from their public counterparts. To access one of these variables from the client: ```js -// +layout.server.js +// @errors: 2305 +/// file: +layout.server.js import { VERCEL_COMMIT_REF } from '$env/static/private'; /** @type {import('./$types').LayoutServerLoad} */ From 48c2ab082effb52b6bd644986881edee7e218165 Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Sat, 14 Jan 2023 19:29:28 -0800 Subject: [PATCH 06/23] revert url change --- packages/adapter-auto/index.js | 2 +- packages/kit/src/core/config/options.js | 2 +- packages/kit/src/exports/vite/index.js | 2 +- packages/kit/types/index.d.ts | 4 ++-- sites/kit.svelte.dev/src/hooks.server.js | 3 +-- sites/kit.svelte.dev/src/routes/home/Deployment.svelte | 2 +- 6 files changed, 7 insertions(+), 8 deletions(-) diff --git a/packages/adapter-auto/index.js b/packages/adapter-auto/index.js index 3dfdc37dae1d..6caacb8b7db9 100644 --- a/packages/adapter-auto/index.js +++ b/packages/adapter-auto/index.js @@ -114,7 +114,7 @@ export default () => ({ if (adapter) return adapter.adapt(builder); builder.log.warn( - 'Could not detect a supported production environment. See https://kit.svelte.dev/docs/building-your-app to learn how to configure your app to run on the platform of your choosing' + 'Could not detect a supported production environment. See https://kit.svelte.dev/docs/adapters to learn how to configure your app to run on the platform of your choosing' ); } }); diff --git a/packages/kit/src/core/config/options.js b/packages/kit/src/core/config/options.js index a188ec0cbf76..2aa87c8a291b 100644 --- a/packages/kit/src/core/config/options.js +++ b/packages/kit/src/core/config/options.js @@ -67,7 +67,7 @@ const options = object( message += ', rather than the name of an adapter'; } - throw new Error(`${message}. See https://kit.svelte.dev/docs/building-your-app`); + throw new Error(`${message}. See https://kit.svelte.dev/docs/adapters`); } return input; diff --git a/packages/kit/src/exports/vite/index.js b/packages/kit/src/exports/vite/index.js index f76a89b7788b..03956dd3b2d2 100644 --- a/packages/kit/src/exports/vite/index.js +++ b/packages/kit/src/exports/vite/index.js @@ -612,7 +612,7 @@ function kit({ svelte_config }) { } else { console.log(colors.bold().yellow('\nNo adapter specified')); - const link = colors.bold().cyan('https://kit.svelte.dev/docs/building-your-app'); + const link = colors.bold().cyan('https://kit.svelte.dev/docs/adapters'); console.log( `See ${link} to learn how to configure your app to run on the platform of your choosing` ); diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts index 6d773d5105e8..2944b989c348 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -21,7 +21,7 @@ import { SSRNodeLoader, SSRRoute, ValidatedConfig } from './internal.js'; export { PrerenderOption } from './private.js'; /** - * [Adapters](https://kit.svelte.dev/docs/building-your-app) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing. + * [Adapters](https://kit.svelte.dev/docs/adapters) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing. */ export interface Adapter { /** @@ -227,7 +227,7 @@ export interface Cookies { export interface KitConfig { /** - * Your [adapter](https://kit.svelte.dev/docs/building-your-app) is run when executing `vite build`. It determines how the output is converted for different platforms. + * Your [adapter](https://kit.svelte.dev/docs/adapters) is run when executing `vite build`. It determines how the output is converted for different platforms. * @default undefined */ adapter?: Adapter; diff --git a/sites/kit.svelte.dev/src/hooks.server.js b/sites/kit.svelte.dev/src/hooks.server.js index f064da48dda7..c7e8742e90e9 100644 --- a/sites/kit.svelte.dev/src/hooks.server.js +++ b/sites/kit.svelte.dev/src/hooks.server.js @@ -1,7 +1,6 @@ const redirects = { '/docs/typescript': '/docs/types', - '/docs/amp': '/docs/seo#manual-setup-amp', - '/docs/adapters': '/docs/building-your-app' + '/docs/amp': '/docs/seo#manual-setup-amp' }; const preload_types = ['js', 'css', 'font']; diff --git a/sites/kit.svelte.dev/src/routes/home/Deployment.svelte b/sites/kit.svelte.dev/src/routes/home/Deployment.svelte index 7b905ea02441..ff6b326ee7be 100644 --- a/sites/kit.svelte.dev/src/routes/home/Deployment.svelte +++ b/sites/kit.svelte.dev/src/routes/home/Deployment.svelte @@ -103,7 +103,7 @@ Azure - + More... From 617de981f819b80c8e90db394098eaeac360a72c Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Sat, 14 Jan 2023 19:33:14 -0800 Subject: [PATCH 07/23] some more reversions --- documentation/docs/10-getting-started/40-web-standards.md | 2 +- documentation/docs/20-core-concepts/20-load.md | 2 +- documentation/docs/60-appendix/10-migrating.md | 8 ++++---- packages/adapter-static/test/apps/spa/README.md | 2 +- packages/create-svelte/shared/README.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/documentation/docs/10-getting-started/40-web-standards.md b/documentation/docs/10-getting-started/40-web-standards.md index d847ccbb486c..a12f534cfae3 100644 --- a/documentation/docs/10-getting-started/40-web-standards.md +++ b/documentation/docs/10-getting-started/40-web-standards.md @@ -4,7 +4,7 @@ title: Web standards Throughout this documentation, you'll see references to the standard [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) that SvelteKit builds on top of. Rather than reinventing the wheel, we _use the platform_, which means your existing web development skills are applicable to SvelteKit. Conversely, time spent learning SvelteKit will help you be a better web developer elsewhere. -These APIs are available in all modern browsers and in many non-browser environments like Cloudflare Workers, Deno and Vercel Edge Functions. During development, and in [adapters](/docs/building-your-app) for Node-based environments (including AWS Lambda), they're made available via polyfills where necessary (for now, that is — Node is rapidly adding support for more web standards). +These APIs are available in all modern browsers and in many non-browser environments like Cloudflare Workers, Deno and Vercel Edge Functions. During development, and in [adapters](/docs/adapters) for Node-based environments (including AWS Lambda), they're made available via polyfills where necessary (for now, that is — Node is rapidly adding support for more web standards). In particular, you'll get comfortable with the following: diff --git a/documentation/docs/20-core-concepts/20-load.md b/documentation/docs/20-core-concepts/20-load.md index f547c7833c15..834f4101ccd1 100644 --- a/documentation/docs/20-core-concepts/20-load.md +++ b/documentation/docs/20-core-concepts/20-load.md @@ -192,7 +192,7 @@ Often the `load` function depends on the URL in one way or another. For this, th An instance of [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL), containing properties like the `origin`, `hostname`, `pathname` and `searchParams` (which contains the parsed query string as a [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object). `url.hash` cannot be accessed during `load`, since it is unavailable on the server. -> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](adapters#supported-environments-node-js), for example, you may need to configure the adapter in order for the URL to be correct. +> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](/docs/adapters#supported-environments-node-js), for example, you may need to configure the adapter in order for the URL to be correct. ### route diff --git a/documentation/docs/60-appendix/10-migrating.md b/documentation/docs/60-appendix/10-migrating.md index 4bf104cb6726..2e04f115c2b7 100644 --- a/documentation/docs/60-appendix/10-migrating.md +++ b/documentation/docs/60-appendix/10-migrating.md @@ -20,14 +20,14 @@ Remove `polka` or `express`, if you're using one of those, and any middleware su ### devDependencies -Remove `sapper` from your `devDependencies` and replace it with `@sveltejs/kit` and whichever [adapter](/docs/building-your-app) you plan to use (see [next section](/docs/migrating#project-files-configuration)). +Remove `sapper` from your `devDependencies` and replace it with `@sveltejs/kit` and whichever [adapter](/docs/adapters) you plan to use (see [next section](/docs/migrating#project-files-configuration)). ### scripts Any scripts that reference `sapper` should be updated: -- `sapper build` should become `vite build` using the Node [adapter](/docs/building-your-app) -- `sapper export` should become `vite build` using the static [adapter](/docs/building-your-app) +- `sapper build` should become `vite build` using the Node [adapter](/docs/adapters) +- `sapper export` should become `vite build` using the static [adapter](/docs/adapters) - `sapper dev` should become `vite dev` - `node __sapper__/build` should become `node build` @@ -39,7 +39,7 @@ The bulk of your app, in `src/routes`, can be left where it is, but several proj Your `webpack.config.js` or `rollup.config.js` should be replaced with a `svelte.config.js`, as documented [here](/docs/configuration). Svelte preprocessor options should be moved to `config.preprocess`. -You will need to add an [adapter](/docs/building-your-app). `sapper build` is roughly equivalent to [adapter-node](https://github.com/sveltejs/kit/tree/master/packages/adapter-node) while `sapper export` is roughly equivalent to [adapter-static](https://github.com/sveltejs/kit/tree/master/packages/adapter-static), though you might prefer to use an adapter designed for the platform you're deploying to. +You will need to add an [adapter](/docs/adapters). `sapper build` is roughly equivalent to [adapter-node](https://github.com/sveltejs/kit/tree/master/packages/adapter-node) while `sapper export` is roughly equivalent to [adapter-static](https://github.com/sveltejs/kit/tree/master/packages/adapter-static), though you might prefer to use an adapter designed for the platform you're deploying to. If you were using plugins for filetypes that are not automatically handled by [Vite](https://vitejs.dev), you will need to find Vite equivalents and add them to the [Vite config](/docs/project-structure#project-files-vite-config-js). diff --git a/packages/adapter-static/test/apps/spa/README.md b/packages/adapter-static/test/apps/spa/README.md index 89ab789a9f1d..c7f00c26d735 100644 --- a/packages/adapter-static/test/apps/spa/README.md +++ b/packages/adapter-static/test/apps/spa/README.md @@ -27,7 +27,7 @@ npm run dev -- --open ## Building -Before creating a production version of your app, install an [adapter](https://kit.svelte.dev/docs/building-your-app) for your target environment. Then: +Before creating a production version of your app, install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment. Then: ```bash npm run build diff --git a/packages/create-svelte/shared/README.md b/packages/create-svelte/shared/README.md index ccebf0fe042c..5c91169b0ca6 100644 --- a/packages/create-svelte/shared/README.md +++ b/packages/create-svelte/shared/README.md @@ -35,4 +35,4 @@ npm run build You can preview the production build with `npm run preview`. -> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/building-your-app) for your target environment. +> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment. From 818aa7e3bae5e7badb7d4d2fefe77ba071821d10 Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Sat, 14 Jan 2023 19:46:11 -0800 Subject: [PATCH 08/23] reorder sidebar --- .../{70-adapter-node.md => 40-adapter-node.md} | 2 +- .../{80-adapter-static.md => 50-adapter-static.md} | 0 .../{40-adapter-cloudflare.md => 60-adapter-cloudflare.md} | 0 ...r-cloudflare-workers.md => 70-adapter-cloudflare-workers.md} | 0 .../{60-adapter-netlify.md => 80-adapter-netlify.md} | 0 5 files changed, 1 insertion(+), 1 deletion(-) rename documentation/docs/25-building-your-app/{70-adapter-node.md => 40-adapter-node.md} (99%) rename documentation/docs/25-building-your-app/{80-adapter-static.md => 50-adapter-static.md} (100%) rename documentation/docs/25-building-your-app/{40-adapter-cloudflare.md => 60-adapter-cloudflare.md} (100%) rename documentation/docs/25-building-your-app/{50-adapter-cloudflare-workers.md => 70-adapter-cloudflare-workers.md} (100%) rename documentation/docs/25-building-your-app/{60-adapter-netlify.md => 80-adapter-netlify.md} (100%) diff --git a/documentation/docs/25-building-your-app/70-adapter-node.md b/documentation/docs/25-building-your-app/40-adapter-node.md similarity index 99% rename from documentation/docs/25-building-your-app/70-adapter-node.md rename to documentation/docs/25-building-your-app/40-adapter-node.md index ba685092f407..b5d48059b4b7 100644 --- a/documentation/docs/25-building-your-app/70-adapter-node.md +++ b/documentation/docs/25-building-your-app/40-adapter-node.md @@ -1,5 +1,5 @@ --- -title: Node +title: adapter-node --- [Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that generates a standalone Node server. diff --git a/documentation/docs/25-building-your-app/80-adapter-static.md b/documentation/docs/25-building-your-app/50-adapter-static.md similarity index 100% rename from documentation/docs/25-building-your-app/80-adapter-static.md rename to documentation/docs/25-building-your-app/50-adapter-static.md diff --git a/documentation/docs/25-building-your-app/40-adapter-cloudflare.md b/documentation/docs/25-building-your-app/60-adapter-cloudflare.md similarity index 100% rename from documentation/docs/25-building-your-app/40-adapter-cloudflare.md rename to documentation/docs/25-building-your-app/60-adapter-cloudflare.md diff --git a/documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md b/documentation/docs/25-building-your-app/70-adapter-cloudflare-workers.md similarity index 100% rename from documentation/docs/25-building-your-app/50-adapter-cloudflare-workers.md rename to documentation/docs/25-building-your-app/70-adapter-cloudflare-workers.md diff --git a/documentation/docs/25-building-your-app/60-adapter-netlify.md b/documentation/docs/25-building-your-app/80-adapter-netlify.md similarity index 100% rename from documentation/docs/25-building-your-app/60-adapter-netlify.md rename to documentation/docs/25-building-your-app/80-adapter-netlify.md From 02282044f6715d1bac479d3a18f9178a51295aac Mon Sep 17 00:00:00 2001 From: Ben McCann <322311+benmccann@users.noreply.github.com> Date: Sat, 14 Jan 2023 19:54:41 -0800 Subject: [PATCH 09/23] tweaks --- .../docs/25-building-your-app/20-adapters.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/documentation/docs/25-building-your-app/20-adapters.md b/documentation/docs/25-building-your-app/20-adapters.md index b3885d50bf0a..349a5c23a219 100644 --- a/documentation/docs/25-building-your-app/20-adapters.md +++ b/documentation/docs/25-building-your-app/20-adapters.md @@ -4,9 +4,9 @@ title: Adapters Before you can deploy your SvelteKit app, you need to _adapt_ it for your deployment target. Adapters are small plugins that take the built app as input and generate output for deployment. -By default, projects are configured to use `@sveltejs/adapter-auto`, which detects your production environment and selects the appropriate adapter where possible. If your platform isn't (yet) supported, you may need to [install a custom adapter](#community-adapters) or [write one](#writing-custom-adapters). +By default, projects are configured to use `@sveltejs/adapter-auto`, which detects your production environment and selects the appropriate adapter where possible. If your platform isn't (yet) supported, you may need to [install a platform-specific adapter](#community-adapters) or in rarer cases [write your own](#writing-custom-adapters). -> See the [adapter-auto README](https://github.com/sveltejs/kit/tree/master/packages/adapter-auto) for information on adding support for new environments. +> See the [adapter-auto README](adapter-auto) for information on adding support for new environments. ## Supported environments @@ -14,13 +14,13 @@ SvelteKit offers a number of officially supported adapters. You can deploy to the following platforms with the default adapter, `adapter-auto`: -- [Cloudflare Pages](https://developers.cloudflare.com/pages/) via [`adapter-cloudflare`](https://github.com/sveltejs/kit/tree/master/packages/adapter-cloudflare) -- [Netlify](https://netlify.com) via [`adapter-netlify`](https://github.com/sveltejs/kit/tree/master/packages/adapter-netlify) -- [Vercel](https://vercel.com) via [`adapter-vercel`](https://github.com/sveltejs/kit/tree/master/packages/adapter-vercel) +- [Cloudflare Pages](https://developers.cloudflare.com/pages/) via [`adapter-cloudflare`](adapter-cloudflare) +- [Netlify](https://netlify.com) via [`adapter-netlify`](adapter-netlify) +- [Vercel](https://vercel.com) via [`adapter-vercel`](adapter-vercel) ### Node.js -To create a simple Node server, install the [`@sveltejs/adapter-node`](https://github.com/sveltejs/kit/tree/master/packages/adapter-node) package and update your `svelte.config.js`: +To create a simple Node server, install the [`@sveltejs/adapter-node`](adapter-node) package and update your `svelte.config.js`: ```diff /// file: svelte.config.js @@ -44,7 +44,7 @@ export default { ### Static sites -Most adapters will generate static HTML for any [prerenderable](/docs/page-options#prerender) pages of your site. In some cases, your entire app might be prerenderable, in which case you can use [`@sveltejs/adapter-static`](https://github.com/sveltejs/kit/tree/master/packages/adapter-static) to generate static HTML for _all_ your pages. A fully static site can be hosted on a wide variety of platforms, including static hosts like [GitHub Pages](https://pages.github.com/). +Most adapters will generate static HTML for any [prerenderable](/docs/page-options#prerender) pages of your site. In some cases, your entire app might be prerenderable, in which case you can use [`@sveltejs/adapter-static`](adapter-static) to generate static HTML for _all_ your pages. A fully static site can be hosted on a wide variety of platforms, including static hosts like [GitHub Pages](https://pages.github.com/). ```diff /// file: svelte.config.js @@ -52,7 +52,7 @@ Most adapters will generate static HTML for any [prerenderable](/docs/page-optio +import adapter from '@sveltejs/adapter-static'; ``` -You can also use `adapter-static` to generate single-page apps (SPAs) by specifying a [fallback page and disabling SSR](https://github.com/sveltejs/kit/tree/master/packages/adapter-static#spa-mode). +You can also use `adapter-static` to generate single-page apps (SPAs) by specifying a [fallback page and disabling SSR](adapter-static#spa-mode). > You must ensure [`trailingSlash`](/docs/page-options#trailingslash) is set appropriately for your environment. If your host does not render `/a.html` upon receiving a request for `/a` then you will need to set `trailingSlash: 'always'` to create `/a/index.html` instead. From d41d97922d946d48537971a53b2606beee71ba39 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 11:43:19 -0500 Subject: [PATCH 10/23] rename to build and deploy --- .../10-building-your-app.md | 0 .../20-adapters.md | 0 .../30-adapter-auto.md | 0 .../40-adapter-node.md | 0 .../50-adapter-static.md | 0 .../60-adapter-cloudflare.md | 0 .../70-adapter-cloudflare-workers.md | 0 .../80-adapter-netlify.md | 0 .../90-adapter-vercel.md | 0 documentation/docs/25-build-and-deploy/meta.json | 3 +++ documentation/docs/25-building-your-app/meta.json | 3 --- 11 files changed, 3 insertions(+), 3 deletions(-) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/10-building-your-app.md (100%) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/20-adapters.md (100%) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/30-adapter-auto.md (100%) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/40-adapter-node.md (100%) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/50-adapter-static.md (100%) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/60-adapter-cloudflare.md (100%) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/70-adapter-cloudflare-workers.md (100%) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/80-adapter-netlify.md (100%) rename documentation/docs/{25-building-your-app => 25-build-and-deploy}/90-adapter-vercel.md (100%) create mode 100644 documentation/docs/25-build-and-deploy/meta.json delete mode 100644 documentation/docs/25-building-your-app/meta.json diff --git a/documentation/docs/25-building-your-app/10-building-your-app.md b/documentation/docs/25-build-and-deploy/10-building-your-app.md similarity index 100% rename from documentation/docs/25-building-your-app/10-building-your-app.md rename to documentation/docs/25-build-and-deploy/10-building-your-app.md diff --git a/documentation/docs/25-building-your-app/20-adapters.md b/documentation/docs/25-build-and-deploy/20-adapters.md similarity index 100% rename from documentation/docs/25-building-your-app/20-adapters.md rename to documentation/docs/25-build-and-deploy/20-adapters.md diff --git a/documentation/docs/25-building-your-app/30-adapter-auto.md b/documentation/docs/25-build-and-deploy/30-adapter-auto.md similarity index 100% rename from documentation/docs/25-building-your-app/30-adapter-auto.md rename to documentation/docs/25-build-and-deploy/30-adapter-auto.md diff --git a/documentation/docs/25-building-your-app/40-adapter-node.md b/documentation/docs/25-build-and-deploy/40-adapter-node.md similarity index 100% rename from documentation/docs/25-building-your-app/40-adapter-node.md rename to documentation/docs/25-build-and-deploy/40-adapter-node.md diff --git a/documentation/docs/25-building-your-app/50-adapter-static.md b/documentation/docs/25-build-and-deploy/50-adapter-static.md similarity index 100% rename from documentation/docs/25-building-your-app/50-adapter-static.md rename to documentation/docs/25-build-and-deploy/50-adapter-static.md diff --git a/documentation/docs/25-building-your-app/60-adapter-cloudflare.md b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md similarity index 100% rename from documentation/docs/25-building-your-app/60-adapter-cloudflare.md rename to documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md diff --git a/documentation/docs/25-building-your-app/70-adapter-cloudflare-workers.md b/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md similarity index 100% rename from documentation/docs/25-building-your-app/70-adapter-cloudflare-workers.md rename to documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md diff --git a/documentation/docs/25-building-your-app/80-adapter-netlify.md b/documentation/docs/25-build-and-deploy/80-adapter-netlify.md similarity index 100% rename from documentation/docs/25-building-your-app/80-adapter-netlify.md rename to documentation/docs/25-build-and-deploy/80-adapter-netlify.md diff --git a/documentation/docs/25-building-your-app/90-adapter-vercel.md b/documentation/docs/25-build-and-deploy/90-adapter-vercel.md similarity index 100% rename from documentation/docs/25-building-your-app/90-adapter-vercel.md rename to documentation/docs/25-build-and-deploy/90-adapter-vercel.md diff --git a/documentation/docs/25-build-and-deploy/meta.json b/documentation/docs/25-build-and-deploy/meta.json new file mode 100644 index 000000000000..528879bbebda --- /dev/null +++ b/documentation/docs/25-build-and-deploy/meta.json @@ -0,0 +1,3 @@ +{ + "title": "Build and deploy" +} diff --git a/documentation/docs/25-building-your-app/meta.json b/documentation/docs/25-building-your-app/meta.json deleted file mode 100644 index 1a5b9dad7b23..000000000000 --- a/documentation/docs/25-building-your-app/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "title": "Building your app" -} From df3ce07a7f463035be9c728b8384f3a21b0b871f Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 11:43:48 -0500 Subject: [PATCH 11/23] fix casing --- documentation/docs/25-build-and-deploy/10-building-your-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/25-build-and-deploy/10-building-your-app.md b/documentation/docs/25-build-and-deploy/10-building-your-app.md index 862b9b23207a..6b02f1daba88 100644 --- a/documentation/docs/25-build-and-deploy/10-building-your-app.md +++ b/documentation/docs/25-build-and-deploy/10-building-your-app.md @@ -1,5 +1,5 @@ --- -title: Building Your App +title: Building your app --- Building a SvelteKit consists of two stages. First the production build is run. This will create a client and a server build which are later consumed by the corresponding environments. [Prerendering](/docs/page-options#prerender) is executed at this stage, if enabled. The second step is to _adapt_ the output to your deployment target using adapters (more on that in the later sections). From 9fad876ac4d61af6fee28869a3ad876d9cce01e0 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 12:02:23 -0500 Subject: [PATCH 12/23] tweaks --- .../10-building-your-app.md | 26 ++++++++----------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/documentation/docs/25-build-and-deploy/10-building-your-app.md b/documentation/docs/25-build-and-deploy/10-building-your-app.md index 6b02f1daba88..8b093b0a4bb8 100644 --- a/documentation/docs/25-build-and-deploy/10-building-your-app.md +++ b/documentation/docs/25-build-and-deploy/10-building-your-app.md @@ -2,27 +2,23 @@ title: Building your app --- -Building a SvelteKit consists of two stages. First the production build is run. This will create a client and a server build which are later consumed by the corresponding environments. [Prerendering](/docs/page-options#prerender) is executed at this stage, if enabled. The second step is to _adapt_ the output to your deployment target using adapters (more on that in the later sections). +Building a SvelteKit app happens in two stages, which both happen when you run `vite build` (usually via `npm run build`). -## During the build +Firstly, Vite creates an optimized production build of your server code, your browser code, and your service worker (if you have one). [Prerendering](/docs/page-options#prerender) is executed at this stage, if appropriate. -SvelteKit will load your `+page/layout(.server).js` files (and all files they import) for analysis during the build. This could lead to code eagerly running which you want to avoid at that stage. Wrap the code in question with `building` from `$app/environment`: +Secondly, an _adapter_ takes this production build and tunes it for your target environment — more on this on the following pages. -```js -/// file: +layout.server.js -// @filename: ambient.d.ts -declare module '$lib/server/database' { - export function setupMyDatabase(): void; -} +## During the build -// @filename: index.js -// ---cut--- -import { building } from '$app/environment'; +SvelteKit will load your `+page/layout(.server).js` files (and all files they import) for analysis during the build. Any code that should _not_ be executed at this stage must check that `building` from [`$app/environment`](/docs/modules#$app-environment) is `false`: + +```diff ++import { building } from '$app/environment'; import { setupMyDatabase } from '$lib/server/database'; -if (!building) { ++if (!building) { setupMyDatabase(); -} ++} export function load() { // ... @@ -31,4 +27,4 @@ export function load() { ## Preview your app -Run the `preview` script to look at your app locally after the production build is done. Note that this does not yet include adapter-specific adjustments like the [`platform` object](adapters#supported-environments-platform-specific-context). +After building, you can view your production build locally with `vite preview` (via `npm run preview`). Note that this will run the app in Node, and so is not a perfect reproduction of your deployed app — adapter-specific adjustments like the [`platform` object](adapters#supported-environments-platform-specific-context) do not apply to previews. From 2ded97e0b6eee81118a8fb226ca9711f48b30623 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 13:30:35 -0500 Subject: [PATCH 13/23] separate out writing section --- .../docs/25-build-and-deploy/20-adapters.md | 43 ------------------ .../99-writing-adapters.md | 44 +++++++++++++++++++ 2 files changed, 44 insertions(+), 43 deletions(-) create mode 100644 documentation/docs/25-build-and-deploy/99-writing-adapters.md diff --git a/documentation/docs/25-build-and-deploy/20-adapters.md b/documentation/docs/25-build-and-deploy/20-adapters.md index 349a5c23a219..be243fc5eac5 100644 --- a/documentation/docs/25-build-and-deploy/20-adapters.md +++ b/documentation/docs/25-build-and-deploy/20-adapters.md @@ -69,46 +69,3 @@ Additional [community-provided adapters](https://sveltesociety.dev/components#ad -import adapter from '@sveltejs/adapter-auto'; +import adapter from 'svelte-adapter-[x]'; ``` - -## Writing custom adapters - -We recommend [looking at the source for an adapter](https://github.com/sveltejs/kit/tree/master/packages) to a platform similar to yours and copying it as a starting point. - -Adapters packages must implement the following API, which creates an `Adapter`: - -```js -// @filename: ambient.d.ts -type AdapterSpecificOptions = any; - -// @filename: index.js -// ---cut--- -/** @param {AdapterSpecificOptions} options */ -export default function (options) { - /** @type {import('@sveltejs/kit').Adapter} */ - const adapter = { - name: 'adapter-package-name', - async adapt(builder) { - // adapter implementation - } - }; - - return adapter; -} -``` - -The types for `Adapter` and its parameters are available in [types/index.d.ts](https://github.com/sveltejs/kit/blob/master/packages/kit/types/index.d.ts). - -Within the `adapt` method, there are a number of things that an adapter should do: - -- Clear out the build directory -- Write SvelteKit output with `builder.writeClient`, `builder.writeServer`, and `builder.writePrerendered` -- Output code that: - - Imports `Server` from `${builder.getServerDirectory()}/index.js` - - Instantiates the app with a manifest generated with `builder.generateManifest({ relativePath })` - - Listens for requests from the platform, converts them to a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) if necessary, calls the `server.respond(request, { getClientAddress })` function to generate a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) and responds with it - - expose any platform-specific information to SvelteKit via the `platform` option passed to `server.respond` - - Globally shims `fetch` to work on the target platform, if necessary. SvelteKit provides a `@sveltejs/kit/install-fetch` helper for platforms that can use `node-fetch` -- Bundle the output to avoid needing to install dependencies on the target platform, if necessary -- Put the user's static files and the generated JS/CSS in the correct location for the target platform - -Where possible, we recommend putting the adapter output under the `build/` directory with any intermediate output placed under `.svelte-kit/[adapter-name]`. diff --git a/documentation/docs/25-build-and-deploy/99-writing-adapters.md b/documentation/docs/25-build-and-deploy/99-writing-adapters.md new file mode 100644 index 000000000000..ac0082950f66 --- /dev/null +++ b/documentation/docs/25-build-and-deploy/99-writing-adapters.md @@ -0,0 +1,44 @@ +--- +title: Writing adapters +--- + +If an adapter for your preferred environment doesn't yet exist, you can build your own. We recommend [looking at the source for an adapter](https://github.com/sveltejs/kit/tree/master/packages) to a platform similar to yours and copying it as a starting point. + +Adapters packages must implement the following API, which creates an `Adapter`: + +```js +// @filename: ambient.d.ts +type AdapterSpecificOptions = any; + +// @filename: index.js +// ---cut--- +/** @param {AdapterSpecificOptions} options */ +export default function (options) { + /** @type {import('@sveltejs/kit').Adapter} */ + const adapter = { + name: 'adapter-package-name', + async adapt(builder) { + // adapter implementation + } + }; + + return adapter; +} +``` + +The types for `Adapter` and its parameters are available in [types/index.d.ts](https://github.com/sveltejs/kit/blob/master/packages/kit/types/index.d.ts). + +Within the `adapt` method, there are a number of things that an adapter should do: + +- Clear out the build directory +- Write SvelteKit output with `builder.writeClient`, `builder.writeServer`, and `builder.writePrerendered` +- Output code that: + - Imports `Server` from `${builder.getServerDirectory()}/index.js` + - Instantiates the app with a manifest generated with `builder.generateManifest({ relativePath })` + - Listens for requests from the platform, converts them to a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) if necessary, calls the `server.respond(request, { getClientAddress })` function to generate a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) and responds with it + - expose any platform-specific information to SvelteKit via the `platform` option passed to `server.respond` + - Globally shims `fetch` to work on the target platform, if necessary. SvelteKit provides a `@sveltejs/kit/install-fetch` helper for platforms that can use `node-fetch` +- Bundle the output to avoid needing to install dependencies on the target platform, if necessary +- Put the user's static files and the generated JS/CSS in the correct location for the target platform + +Where possible, we recommend putting the adapter output under the `build/` directory with any intermediate output placed under `.svelte-kit/[adapter-name]`. From 7904d2c31e6a96f8c7f7c323d2296f859c61f1b4 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 14:18:17 -0500 Subject: [PATCH 14/23] tweaks --- .../docs/25-build-and-deploy/20-adapters.md | 78 ++++++----------- .../25-build-and-deploy/30-adapter-auto.md | 24 +++--- .../25-build-and-deploy/40-adapter-node.md | 52 ++++++----- .../25-build-and-deploy/50-adapter-static.md | 86 +++++++++---------- .../60-adapter-cloudflare.md | 9 +- 5 files changed, 108 insertions(+), 141 deletions(-) diff --git a/documentation/docs/25-build-and-deploy/20-adapters.md b/documentation/docs/25-build-and-deploy/20-adapters.md index be243fc5eac5..3b7b8f782d82 100644 --- a/documentation/docs/25-build-and-deploy/20-adapters.md +++ b/documentation/docs/25-build-and-deploy/20-adapters.md @@ -4,68 +4,46 @@ title: Adapters Before you can deploy your SvelteKit app, you need to _adapt_ it for your deployment target. Adapters are small plugins that take the built app as input and generate output for deployment. -By default, projects are configured to use `@sveltejs/adapter-auto`, which detects your production environment and selects the appropriate adapter where possible. If your platform isn't (yet) supported, you may need to [install a platform-specific adapter](#community-adapters) or in rarer cases [write your own](#writing-custom-adapters). +Official adapters exist for a variety of platforms — these are documented on the following pages: -> See the [adapter-auto README](adapter-auto) for information on adding support for new environments. +- [`@sveltejs/adapter-cloudflare`](adapter-cloudflare) for Cloudflare Pages +- [`@sveltejs/adapter-cloudflare-workers`](adapter-cloudflare-workers) for Cloudflare Workers +- [`@sveltejs/adapter-netlify`](adapter-netlify) for Netlify +- [`@sveltejs/adapter-node`](adapter-node) for Node servers +- [`@sveltejs/adapter-static`](adapter-static) for static site generation (SSG) +- [`@sveltejs/adapter-vercel`](adapter-vercel) for Vercel -## Supported environments +Additional [community-provided adapters](https://sveltesociety.dev/components#adapters) exist for other platforms. -SvelteKit offers a number of officially supported adapters. +## Using adapters -You can deploy to the following platforms with the default adapter, `adapter-auto`: +Your adapter is specified in `svelte.config.js`: -- [Cloudflare Pages](https://developers.cloudflare.com/pages/) via [`adapter-cloudflare`](adapter-cloudflare) -- [Netlify](https://netlify.com) via [`adapter-netlify`](adapter-netlify) -- [Vercel](https://vercel.com) via [`adapter-vercel`](adapter-vercel) - -### Node.js - -To create a simple Node server, install the [`@sveltejs/adapter-node`](adapter-node) package and update your `svelte.config.js`: - -```diff +```js /// file: svelte.config.js --import adapter from '@sveltejs/adapter-auto'; -+import adapter from '@sveltejs/adapter-node'; -``` - -With this, `vite build` will generate a self-contained Node app inside the `build` directory. You can pass options to adapters, such as customising the output directory: - -```diff -/// file: svelte.config.js -import adapter from '@sveltejs/adapter-node'; - -export default { +// @filename: ambient.d.ts +declare module 'svelte-adapter-foo' { + const adapter: (opts: any) => import('@sveltejs/kit').Adapter; + export default adapter; +} + +// @filename: index.js +// ---cut--- +import adapter from 'svelte-adapter-foo'; + +/** @type {import('@sveltejs/kit').Config} */ +const config = { kit: { -- adapter: adapter() -+ adapter: adapter({ out: 'my-output-directory' }) + adapter: adapter({ + // adapter options go here + }) } }; -``` -### Static sites - -Most adapters will generate static HTML for any [prerenderable](/docs/page-options#prerender) pages of your site. In some cases, your entire app might be prerenderable, in which case you can use [`@sveltejs/adapter-static`](adapter-static) to generate static HTML for _all_ your pages. A fully static site can be hosted on a wide variety of platforms, including static hosts like [GitHub Pages](https://pages.github.com/). - -```diff -/// file: svelte.config.js --import adapter from '@sveltejs/adapter-auto'; -+import adapter from '@sveltejs/adapter-static'; +export default config; ``` -You can also use `adapter-static` to generate single-page apps (SPAs) by specifying a [fallback page and disabling SSR](adapter-static#spa-mode). - -> You must ensure [`trailingSlash`](/docs/page-options#trailingslash) is set appropriately for your environment. If your host does not render `/a.html` upon receiving a request for `/a` then you will need to set `trailingSlash: 'always'` to create `/a/index.html` instead. - -### Platform-specific context +## Platform-specific content Some adapters may have access to additional information about the request. For example, Cloudflare Workers can access an `env` object containing KV namespaces etc. This can be passed to the `RequestEvent` used in [hooks](/docs/hooks) and [server routes](/docs/routing#server) as the `platform` property — consult each adapter's documentation to learn more. -## Community adapters - -Additional [community-provided adapters](https://sveltesociety.dev/components#adapters) exist for other platforms. After installing the relevant adapter with your package manager, update your `svelte.config.js`: - -```diff -/// file: svelte.config.js --import adapter from '@sveltejs/adapter-auto'; -+import adapter from 'svelte-adapter-[x]'; -``` diff --git a/documentation/docs/25-build-and-deploy/30-adapter-auto.md b/documentation/docs/25-build-and-deploy/30-adapter-auto.md index e701e764061d..d0719ebafc3d 100644 --- a/documentation/docs/25-build-and-deploy/30-adapter-auto.md +++ b/documentation/docs/25-build-and-deploy/30-adapter-auto.md @@ -1,22 +1,20 @@ --- -title: adapter-auto +title: Zero-config deployments --- -Automatically chooses the adapter for your current environment, if possible. +When you create a new SvelteKit project with `npm create svelte@latest`, it installs [`adapter-auto`](https://github.com/sveltejs/kit/tree/master/packages/adapter-auto) by default. This adapter automatically installs and uses the correct adapter for supported environments when you deploy: -## Supported environments +- [`@sveltejs/adapter-cloudflare`](adapter-cloudflare) for [Cloudflare Pages](https://developers.cloudflare.com/pages/) +- [`@sveltejs/adapter-netlify`](adapter-netlify) for [Netlify](https://netlify.com/) +- [`@sveltejs/adapter-vercel`](adapter-vercel) for [Vercel](https://vercel.com/) +- [`svelte-adapter-azure-swa`](https://github.com/geoffrich/svelte-adapter-azure-swa) for [Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/) -The following environments are supported out-of-the-box, meaning a newly created project can be deployed on one of these platforms without any additional configuration: +It's recommended to install the appropriate adapter to your `devDependencies` once you've settled on a target environment, since this will add the adapter to your lockfile and slightly improve install times on CI. -- [Cloudflare Pages](https://developers.cloudflare.com/pages/) via [adapter-cloudflare](adapter-cloudflare) -- [Netlify](https://netlify.com/) via [adapter-netlify](adapter-netlify) -- [Vercel](https://vercel.com/) via [adapter-vercel](adapter-vercel) -- [Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/) via [svelte-adapter-azure-swa](https://github.com/geoffrich/svelte-adapter-azure-swa) +## Environment-specific configuration -## Community adapters +To add configuration options, such as `{ edge: true }` in [`adapter-vercel`](adapter-vercel) and [`adapter-netlify`](adapter-netlify), you must install the underlying adapter — `adapter-auto` does not take any options. -Support for additional environments can be added in [adapters.js](https://github.com/sveltejs/kit/blob/master/packages/adapter-auto/adapters.js). To avoid this package ballooning in size, community-supported adapters should not be added as dependencies — adapter-auto will instead prompt users to install missing packages as needed. +## Adding community adapters -## Changelog - -[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-auto/CHANGELOG.md). +You can add zero-config support for additional adapters by editing [adapters.js](https://github.com/sveltejs/kit/blob/master/packages/adapter-auto/adapters.js) and opening a pull request. \ No newline at end of file diff --git a/documentation/docs/25-build-and-deploy/40-adapter-node.md b/documentation/docs/25-build-and-deploy/40-adapter-node.md index b5d48059b4b7..8ca23baa73f1 100644 --- a/documentation/docs/25-build-and-deploy/40-adapter-node.md +++ b/documentation/docs/25-build-and-deploy/40-adapter-node.md @@ -1,8 +1,8 @@ --- -title: adapter-node +title: Node servers --- -[Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that generates a standalone Node server. +To generate a standalone Node server, use [`adapter-node`](https://github.com/sveltejs/kit/tree/master/packages/adapter-node). ## Usage @@ -14,21 +14,21 @@ Install with `npm i -D @sveltejs/adapter-node`, then add the adapter to your `sv import adapter from '@sveltejs/adapter-node'; export default { - kit: { - adapter: adapter() - } + kit: { + adapter: adapter() + } }; ``` ## Deploying -You will need the output directory (`build` by default), the project's `package.json`, and the production dependencies in `node_modules` to run the application. Production dependencies can be generated with `npm ci --prod` (you can skip this step if your app doesn't have any dependencies). You can then start your app with +You will need the output directory (`build` by default), the project's `package.json`, and the production dependencies in `node_modules` to run the application. Production dependencies can be generated with `npm ci --prod` (you can skip this step if your app doesn't have any dependencies). You can then start your app with this command: ```bash node build ``` -Development dependencies will be bundled into your app using `rollup`. To control whether a given package is bundled or externalised, place it in `devDependencies` or `dependencies` respectively in your `package.json`. +Development dependencies will be bundled into your app using [Rollup](https://rollupjs.org). To control whether a given package is bundled or externalised, place it in `devDependencies` or `dependencies` respectively in your `package.json`. ## Environment variables @@ -71,13 +71,13 @@ PROTOCOL_HEADER=x-forwarded-proto HOST_HEADER=x-forwarded-host node build > [`x-forwarded-proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) and [`x-forwarded-host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) are de facto standard headers that forward the original protocol and host if you're using a reverse proxy (think load balancers and CDNs). You should only set these variables if your server is behind a trusted reverse proxy; otherwise, it'd be possible for clients to spoof these headers. -If `adapter-node` can't correctly determine the URL of your deployment, you may experience this error when using [form actions](https://kit.svelte.dev/docs/form-actions): +If `adapter-node` can't correctly determine the URL of your deployment, you may experience this error when using [form actions](/docs/form-actions): > Cross-site POST form submissions are forbidden ### `ADDRESS_HEADER` and `XFF_DEPTH` -The [RequestEvent](https://kit.svelte.dev/docs/types#public-types-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: +The [RequestEvent](/docs/types#public-types-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: ``` ADDRESS_HEADER=True-Client-IP node build @@ -97,13 +97,13 @@ Some guides will tell you to read the left-most address, but this leaves you [vu , , , ``` -Instead, we read from the _right_, accounting for the number of trusted proxies. In this case, we would use `XFF_DEPTH=3`. +We instead read from the _right_, accounting for the number of trusted proxies. In this case, we would use `XFF_DEPTH=3`. > If you need to read the left-most address instead (and don't care about spoofing) — for example, to offer a geolocation service, where it's more important for the IP address to be _real_ than _trusted_, you can do so by inspecting the `x-forwarded-for` header within your app. ### `BODY_SIZE_LIMIT` -The maximum request body size to accept in bytes including while streaming. Defaults to 512kb. You can disable this option with a value of 0 and implement a custom check in [`handle`](https://kit.svelte.dev/docs/hooks#server-hooks-handle) if you need something more advanced. +The maximum request body size to accept in bytes including while streaming. Defaults to 512kb. You can disable this option with a value of 0 and implement a custom check in [`handle`](/docs/hooks#server-hooks-handle) if you need something more advanced. ## Options @@ -115,14 +115,14 @@ The adapter can be configured with various options: import adapter from '@sveltejs/adapter-node'; export default { - kit: { - adapter: adapter({ - // default options are shown - out: 'build', - precompress: false, - envPrefix: '' - }) - } + kit: { + adapter: adapter({ + // default options are shown + out: 'build', + precompress: false, + envPrefix: '' + }) + } }; ``` @@ -165,14 +165,14 @@ const app = express(); // add a route that lives separately from the SvelteKit app app.get('/healthcheck', (req, res) => { - res.end('ok'); + res.end('ok'); }); // let SvelteKit handle everything else, including serving prerendered pages and static assets app.use(handler); app.listen(3000, () => { - console.log('listening on port 3000'); + console.log('listening on port 3000'); }); ``` @@ -185,14 +185,10 @@ There's nothing built-in to SvelteKit for this, because such a cleanup hook depe ```js // @errors: 2304 2580 function shutdownGracefully() { - // anything you need to clean up manually goes in here - db.shutdown(); + // anything you need to clean up manually goes in here + db.shutdown(); } process.on('SIGINT', shutdownGracefully); process.on('SIGTERM', shutdownGracefully); -``` - -## Changelog - -[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-node/CHANGELOG.md). +``` \ No newline at end of file diff --git a/documentation/docs/25-build-and-deploy/50-adapter-static.md b/documentation/docs/25-build-and-deploy/50-adapter-static.md index b495dc13ff5e..2b5aa0d17175 100644 --- a/documentation/docs/25-build-and-deploy/50-adapter-static.md +++ b/documentation/docs/25-build-and-deploy/50-adapter-static.md @@ -1,8 +1,10 @@ --- -title: adapter-static +title: Static site generation --- -[Adapter](https://kit.svelte.dev/docs/building-your-app) for SvelteKit apps that prerenders your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with [the `prerender` option](https://kit.svelte.dev/docs/page-options#prerender). +To use SvelteKit as a static site generator (SSG), use [`adapter-static`](https://github.com/sveltejs/kit/tree/master/packages/adapter-static). + +This will prerender your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with [the `prerender` option](/docs/page-options#prerender). ## Usage @@ -14,21 +16,21 @@ Install with `npm i -D @sveltejs/adapter-static`, then add the adapter to your ` import adapter from '@sveltejs/adapter-static'; export default { - kit: { - adapter: adapter({ - // default options are shown. On some platforms - // these options are set automatically — see below - pages: 'build', - assets: 'build', - fallback: null, - precompress: false, - strict: true - }) - } + kit: { + adapter: adapter({ + // default options are shown. On some platforms + // these options are set automatically — see below + pages: 'build', + assets: 'build', + fallback: null, + precompress: false, + strict: true + }) + } }; ``` -...and add the [`prerender`](https://kit.svelte.dev/docs/page-options#prerender) option to your root layout: +...and add the [`prerender`](/docs/page-options#prerender) option to your root layout: ```js // src/routes/+layout.js @@ -37,7 +39,7 @@ export default { export const prerender = true; ``` -> ⚠️ You must ensure SvelteKit's [`trailingSlash`](https://kit.svelte.dev/docs/page-options#trailingslash) option is set appropriately for your environment. If your host does not render `/a.html` upon receiving a request for `/a` then you will need to set `trailingSlash: 'always'` to create `/a/index.html` instead. +> You must ensure SvelteKit's [`trailingSlash`](/docs/page-options#trailingslash) option is set appropriately for your environment. If your host does not render `/a.html` upon receiving a request for `/a` then you will need to set `trailingSlash: 'always'` to create `/a/index.html` instead. ## Zero-config support @@ -49,11 +51,11 @@ On these platforms, you should omit the adapter options so that `adapter-static` ```diff export default { - kit: { -- adapter: adapter({...}), -+ adapter: adapter(), - } - } + kit: { +- adapter: adapter({...}), ++ adapter: adapter(), + } + } }; ``` @@ -93,12 +95,12 @@ If you want to create a simple SPA with no prerendered routes, the necessary con import adapter from '@sveltejs/adapter-static'; export default { - kit: { - adapter: adapter({ - fallback: '200.html' - }), - prerender: { entries: [] } - } + kit: { + adapter: adapter({ + fallback: '200.html' + }), + prerender: { entries: [] } + } }; ``` @@ -121,11 +123,11 @@ The fallback page is an HTML page created by SvelteKit that loads your app and n import adapter from '@sveltejs/adapter-static'; export default { - kit: { - adapter: adapter({ - fallback: '200.html' - }) - } + kit: { + adapter: adapter({ + fallback: '200.html' + }) + } }; ``` @@ -133,7 +135,7 @@ export default { ### Turn off prerendering -When operating in SPA mode, you can omit the [`prerender`](https://kit.svelte.dev/docs/page-options#prerender) option from your root layout (or set it to `false`, its default value), and only pages that have the `prerender` option set will be prerendered at build time. +When operating in SPA mode, you can omit the [`prerender`](/docs/page-options#prerender) option from your root layout (or set it to `false`, its default value), and only pages that have the `prerender` option set will be prerendered at build time. SvelteKit will still crawl your app's entry points looking for prerenderable pages. If `svelte-kit build` fails because of pages that can't be loaded outside the browser, you can set `config.kit.prerender.entries` to `[]` to prevent this from happening. (Setting `config.kit.prerender.enabled` to `false` also has this effect, but would prevent the fallback page from being generated.) @@ -141,7 +143,7 @@ You can also add turn off prerendering only to parts of your app, if you want ot ### Turn off ssr -During development, SvelteKit will still attempt to server-side render your routes. This means accessing things that are only available in the browser (such as the `window` object) will result in errors, even though this would be valid in the output app. To align the behavior of SvelteKit's dev mode with your SPA, you can [add `export const ssr = false` to your root `+layout`](https://kit.svelte.dev/docs/page-options#ssr). You can also add this option only to parts of your app, if you want other parts to be prerendered. +During development, SvelteKit will still attempt to server-side render your routes. This means accessing things that are only available in the browser (such as the `window` object) will result in errors, even though this would be valid in the output app. To align the behavior of SvelteKit's dev mode with your SPA, you can [add `export const ssr = false` to your root `+layout`](/docs/page-options#ssr). You can also add this option only to parts of your app, if you want other parts to be prerendered. ### Apache @@ -149,18 +151,18 @@ To run an SPA on [Apache](https://httpd.apache.org/), you should add a `static/. ``` - RewriteEngine On - RewriteBase / - RewriteRule ^200\.html$ - [L] - RewriteCond %{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_FILENAME} !-d - RewriteRule . /200.html [L] + RewriteEngine On + RewriteBase / + RewriteRule ^200\.html$ - [L] + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule . /200.html [L] ``` ## GitHub Pages -When building for GitHub Pages, make sure to update [`paths.base`](https://kit.svelte.dev/docs/configuration#paths) to match your repo name, since the site will be served from rather than from the root. +When building for GitHub Pages, make sure to update [`paths.base`](/docs/configuration#paths) to match your repo name, since the site will be served from rather than from the root. You will have to prevent GitHub's provided Jekyll from managing your site by putting an empty `.nojekyll` file in your static folder. If you do not want to disable Jekyll, change the kit's `appDir` configuration option to `'app_'` or anything not starting with an underscore. For more information, see GitHub's [Jekyll documentation](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#configuring-jekyll-in-your-github-pages-site). @@ -182,7 +184,3 @@ const config = { } }; ``` - -## Changelog - -[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-static/CHANGELOG.md). diff --git a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md index 94a9fc3d728b..6fcb4678ce88 100644 --- a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md +++ b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md @@ -8,12 +8,9 @@ If you're using [adapter-auto](adapter-auto), you don't need to install this — _**Comparisons**_ -- `adapter-cloudflare` – supports all SvelteKit features; builds for - [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) -- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for - Cloudflare Workers -- `adapter-static` – only produces client-side static assets; compatible with - Cloudflare Pages +- `adapter-cloudflare` – supports all SvelteKit features; builds for [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) +- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for Cloudflare Workers +- `adapter-static` – only produces client-side static assets; compatible with Cloudflare Pages > **Note:** Cloudflare Pages' new Workers integration is currently in beta.
> Compared to `adapter-cloudflare-workers`, this adapter will be the preferred approach for most users since building on top of Pages unlocks automatic builds and deploys, preview deployments, instant rollbacks, etc.
From 8981b1fcedf7005637c76863a589210a27a632ee Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 14:19:01 -0500 Subject: [PATCH 15/23] formatting --- .../60-adapter-cloudflare.md | 10 ++-- .../70-adapter-cloudflare-workers.md | 20 +++---- .../25-build-and-deploy/80-adapter-netlify.md | 54 +++++++++---------- .../25-build-and-deploy/90-adapter-vercel.md | 42 +++++++-------- .../99-writing-adapters.md | 10 ++-- 5 files changed, 68 insertions(+), 68 deletions(-) diff --git a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md index 6fcb4678ce88..0f3100fe2501 100644 --- a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md +++ b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md @@ -32,9 +32,9 @@ You can include these changes in your `svelte.config.js` configuration file: import adapter from '@sveltejs/adapter-cloudflare'; export default { - kit: { - adapter: adapter() - } + kit: { + adapter: adapter() + } }; ``` @@ -48,7 +48,7 @@ When configuring your project settings, you must use the following settings: - **Build command** – `npm run build` or `svelte-kit build` - **Build output directory** – `.svelte-kit/cloudflare` - **Environment variables** - - `NODE_VERSION`: `16` + - `NODE_VERSION`: `16` > **Important:** You need to add a `NODE_VERSION` environment variable to both the "production" and "preview" environments. You can add this during project setup or later in the Pages project settings. SvelteKit requires Node `16.14` or later, so you should use `16` as the `NODE_VERSION` value. @@ -59,7 +59,7 @@ The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#p ```js // @errors: 7031 export async function POST({ request, platform }) { - const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); + const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); } ``` diff --git a/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md b/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md index 3be7e35eb3b2..d563fccbbaa9 100644 --- a/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md +++ b/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md @@ -9,11 +9,11 @@ SvelteKit adapter that creates a Cloudflare Workers site using a function for dy _**Comparisons**_ - `adapter-cloudflare` – supports all SvelteKit features; builds for - [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) + [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) - `adapter-cloudflare-workers` – supports all SvelteKit features; builds for - Cloudflare Workers + Cloudflare Workers - `adapter-static` – only produces client-side static assets; compatible with - Cloudflare Pages + Cloudflare Pages > **Note:** Cloudflare Pages' new Workers integration is currently in beta.
> Compared to `adapter-cloudflare-workers`, `adapter-cloudflare` is the preferred approach for most users since building on top of Pages unlocks automatic builds and deploys, preview deployments, instant rollbacks, etc.
@@ -29,9 +29,9 @@ Install with `npm i -D @sveltejs/adapter-cloudflare-workers`, then add the adapt import adapter from '@sveltejs/adapter-cloudflare-workers'; export default { - kit: { - adapter: adapter() - } + kit: { + adapter: adapter() + } }; ``` @@ -83,9 +83,9 @@ If you would like to use a config file other than `wrangler.toml`, you can do li import adapter from '@sveltejs/adapter-cloudflare-workers'; export default { - kit: { - adapter: adapter({ config: '.toml' }) - } + kit: { + adapter: adapter({ config: '.toml' }) + } }; ``` @@ -96,7 +96,7 @@ The [`env`](https://developers.cloudflare.com/workers/runtime-apis/fetch-event#p ```js // @errors: 7031 export async function POST({ request, platform }) { - const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); + const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x'); } ``` diff --git a/documentation/docs/25-build-and-deploy/80-adapter-netlify.md b/documentation/docs/25-build-and-deploy/80-adapter-netlify.md index 8b2ee2284700..1a14a2f0a062 100644 --- a/documentation/docs/25-build-and-deploy/80-adapter-netlify.md +++ b/documentation/docs/25-build-and-deploy/80-adapter-netlify.md @@ -20,19 +20,19 @@ You can then configure it inside of `svelte.config.js`: import adapter from '@sveltejs/adapter-netlify'; export default { - kit: { - // default options are shown - adapter: adapter({ - // if true, will create a Netlify Edge Function rather - // than using standard Node-based functions - edge: false, - - // if true, will split your app into multiple functions - // instead of creating a single one for the entire app. - // if `edge` is true, this option cannot be used - split: false - }) - } + kit: { + // default options are shown + adapter: adapter({ + // if true, will create a Netlify Edge Function rather + // than using standard Node-based functions + edge: false, + + // if true, will split your app into multiple functions + // instead of creating a single one for the entire app. + // if `edge` is true, this option cannot be used + split: false + }) + } }; ``` @@ -40,8 +40,8 @@ Then, make sure you have a [netlify.toml](https://docs.netlify.com/configure-bui ```toml [build] - command = "npm run build" - publish = "build" + command = "npm run build" + publish = "build" ``` If the `netlify.toml` file or the `build.publish` value is missing, a default value of `"build"` will be used. Note that if you have set the publish directory in the Netlify UI to something else then you will need to set it in `netlify.toml` too, or use the default value of `"build"`. @@ -60,13 +60,13 @@ SvelteKit supports the beta release of [Netlify Edge Functions](https://docs.net import adapter from '@sveltejs/adapter-netlify'; export default { - kit: { - adapter: adapter({ - // will create a Netlify Edge Function using Deno-based - // rather than using standard Node-based functions - edge: true - }) - } + kit: { + adapter: adapter({ + // will create a Netlify Edge Function using Deno-based + // rather than using standard Node-based functions + edge: true + }) + } }; ``` @@ -95,8 +95,8 @@ With this adapter, SvelteKit endpoints are hosted as [Netlify Functions](https:/ // @errors: 2705 7006 /// file: +page.server.js export const load = async (event) => { - const context = event.platform.context; - console.log(context); // shows up in your functions log in the Netlify app + const context = event.platform.context; + console.log(context); // shows up in your functions log in the Netlify app }; ``` @@ -104,11 +104,11 @@ Additionally, you can add your own Netlify functions by creating a directory for ```toml [build] - command = "npm run build" - publish = "build" + command = "npm run build" + publish = "build" [functions] - directory = "functions" + directory = "functions" ``` ## Troubleshooting diff --git a/documentation/docs/25-build-and-deploy/90-adapter-vercel.md b/documentation/docs/25-build-and-deploy/90-adapter-vercel.md index 41121c4cdd21..4232310b6de3 100644 --- a/documentation/docs/25-build-and-deploy/90-adapter-vercel.md +++ b/documentation/docs/25-build-and-deploy/90-adapter-vercel.md @@ -18,23 +18,23 @@ Then in your `svelte.config.js`: import vercel from '@sveltejs/adapter-vercel'; export default { - kit: { - // default options are shown - adapter: vercel({ - // if true, will deploy the app using edge functions - // (https://vercel.com/docs/concepts/functions/edge-functions) - // rather than serverless functions - edge: false, - - // an array of dependencies that esbuild should treat - // as external when bundling functions - external: [], - - // if true, will split your app into multiple functions - // instead of creating a single one for the entire app - split: false - }) - } + kit: { + // default options are shown + adapter: vercel({ + // if true, will deploy the app using edge functions + // (https://vercel.com/docs/concepts/functions/edge-functions) + // rather than serverless functions + edge: false, + + // an array of dependencies that esbuild should treat + // as external when bundling functions + external: [], + + // if true, will split your app into multiple functions + // instead of creating a single one for the entire app + split: false + }) + } }; ``` @@ -49,16 +49,16 @@ import { VERCEL_COMMIT_REF } from '$env/static/private'; /** @type {import('./$types').LayoutServerLoad} */ export function load() { - return { - deploymentGitBranch: VERCEL_COMMIT_REF - }; + return { + deploymentGitBranch: VERCEL_COMMIT_REF + }; } ``` ```svelte diff --git a/documentation/docs/25-build-and-deploy/99-writing-adapters.md b/documentation/docs/25-build-and-deploy/99-writing-adapters.md index ac0082950f66..e496bbad0634 100644 --- a/documentation/docs/25-build-and-deploy/99-writing-adapters.md +++ b/documentation/docs/25-build-and-deploy/99-writing-adapters.md @@ -33,11 +33,11 @@ Within the `adapt` method, there are a number of things that an adapter should d - Clear out the build directory - Write SvelteKit output with `builder.writeClient`, `builder.writeServer`, and `builder.writePrerendered` - Output code that: - - Imports `Server` from `${builder.getServerDirectory()}/index.js` - - Instantiates the app with a manifest generated with `builder.generateManifest({ relativePath })` - - Listens for requests from the platform, converts them to a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) if necessary, calls the `server.respond(request, { getClientAddress })` function to generate a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) and responds with it - - expose any platform-specific information to SvelteKit via the `platform` option passed to `server.respond` - - Globally shims `fetch` to work on the target platform, if necessary. SvelteKit provides a `@sveltejs/kit/install-fetch` helper for platforms that can use `node-fetch` + - Imports `Server` from `${builder.getServerDirectory()}/index.js` + - Instantiates the app with a manifest generated with `builder.generateManifest({ relativePath })` + - Listens for requests from the platform, converts them to a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) if necessary, calls the `server.respond(request, { getClientAddress })` function to generate a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) and responds with it + - expose any platform-specific information to SvelteKit via the `platform` option passed to `server.respond` + - Globally shims `fetch` to work on the target platform, if necessary. SvelteKit provides a `@sveltejs/kit/install-fetch` helper for platforms that can use `node-fetch` - Bundle the output to avoid needing to install dependencies on the target platform, if necessary - Put the user's static files and the generated JS/CSS in the correct location for the target platform From 642e67300023cc31967deb9cb1f831dc65478952 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 16:27:32 -0500 Subject: [PATCH 16/23] tweaks --- .../25-build-and-deploy/50-adapter-static.md | 2 +- .../60-adapter-cloudflare.md | 29 +++++-------------- .../70-adapter-cloudflare-workers.md | 28 ++++-------------- .../25-build-and-deploy/80-adapter-netlify.md | 28 +++++++----------- .../25-build-and-deploy/90-adapter-vercel.md | 18 ++++-------- 5 files changed, 29 insertions(+), 76 deletions(-) diff --git a/documentation/docs/25-build-and-deploy/50-adapter-static.md b/documentation/docs/25-build-and-deploy/50-adapter-static.md index 2b5aa0d17175..8ca4bf0ab254 100644 --- a/documentation/docs/25-build-and-deploy/50-adapter-static.md +++ b/documentation/docs/25-build-and-deploy/50-adapter-static.md @@ -8,7 +8,7 @@ This will prerender your entire site as a collection of static files. If you'd l ## Usage -Install with `npm i -D @sveltejs/adapter-static`, then add the adapter to your `svelte.config.js`... +Install with `npm i -D @sveltejs/adapter-static`, then add the adapter to your `svelte.config.js`: ```js // @errors: 2307 diff --git a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md index 0f3100fe2501..234881cefd38 100644 --- a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md +++ b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md @@ -1,30 +1,22 @@ --- -title: Cloudflare +title: Cloudflare Pages --- -[Adapter](https://kit.svelte.dev/docs/building-your-app) for building SvelteKit applications on [Cloudflare Pages](https://developers.cloudflare.com/pages/) with [Workers integration](https://developers.cloudflare.com/pages/platform/functions). +To deploy to [Cloudflare Pages](https://developers.cloudflare.com/pages/), use [`adapter-cloudflare`](https://github.com/sveltejs/kit/tree/master/packages/adapter-cloudflare). -If you're using [adapter-auto](adapter-auto), you don't need to install this — it's already included. +This adapter will be installed by default when you use [`adapter-auto`](/docs/adapter-auto), but adding it to your project is recommended so that `event.platform` is automatically typed. -_**Comparisons**_ +## Comparisons - `adapter-cloudflare` – supports all SvelteKit features; builds for [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) - `adapter-cloudflare-workers` – supports all SvelteKit features; builds for Cloudflare Workers - `adapter-static` – only produces client-side static assets; compatible with Cloudflare Pages -> **Note:** Cloudflare Pages' new Workers integration is currently in beta.
-> Compared to `adapter-cloudflare-workers`, this adapter will be the preferred approach for most users since building on top of Pages unlocks automatic builds and deploys, preview deployments, instant rollbacks, etc.
-> From SvelteKit's perspective, there is no difference and no functionality loss when migrating to/from the Workers and the Pages adapters. - -## Installation - -```sh -$ npm i --save-dev @sveltejs/adapter-cloudflare -``` +> Unless you have a specific reason to use `adapter-cloudflare-workers`, it's recommended that you use this adapter instead. Both adapters have equivalent functionality, but Cloudflare Pages offers features like GitHub integration with automatic builds and deploys, preview deployments, instant rollback and so on. ## Usage -You can include these changes in your `svelte.config.js` configuration file: +Install with `npm i -D @sveltejs/adapter-cloudflare`, then add the adapter to your `svelte.config.js`: ```js // @errors: 2307 @@ -50,7 +42,7 @@ When configuring your project settings, you must use the following settings: - **Environment variables** - `NODE_VERSION`: `16` -> **Important:** You need to add a `NODE_VERSION` environment variable to both the "production" and "preview" environments. You can add this during project setup or later in the Pages project settings. SvelteKit requires Node `16.14` or later, so you should use `16` as the `NODE_VERSION` value. +> You need to add a `NODE_VERSION` environment variable to both the "production" and "preview" environments. You can add this during project setup or later in the Pages project settings. SvelteKit requires Node `16.14` or later, so you should use `16` as the `NODE_VERSION` value. ## Environment variables @@ -66,9 +58,6 @@ export async function POST({ request, platform }) { To make these types available to your app, reference them in your `src/app.d.ts`: ```diff -/// -+/// - declare namespace App { interface Platform { + env?: { @@ -94,7 +83,3 @@ However, they will have no effect on responses dynamically rendered by SvelteKit ### Accessing the file system You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. - -## Changelog - -[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-cloudflare/CHANGELOG.md). diff --git a/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md b/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md index d563fccbbaa9..cb9a26226ad8 100644 --- a/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md +++ b/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md @@ -2,22 +2,11 @@ title: Cloudflare Workers --- -SvelteKit adapter that creates a Cloudflare Workers site using a function for dynamic server rendering. +To deploy to [Cloudflare Workers](https://workers.cloudflare.com/), use [`adapter-cloudflare-workers`](https://github.com/sveltejs/kit/tree/master/packages/adapter-cloudflare-workers). -**Requires [Wrangler v2](https://developers.cloudflare.com/workers/wrangler/get-started/).** Wrangler v1 is no longer supported. +Unless you have a specific reason to use this adapter, we recommend using [`adapter-cloudflare`](adapter-cloudflare) instead. -_**Comparisons**_ - -- `adapter-cloudflare` – supports all SvelteKit features; builds for - [Cloudflare Pages](https://blog.cloudflare.com/cloudflare-pages-goes-full-stack/) -- `adapter-cloudflare-workers` – supports all SvelteKit features; builds for - Cloudflare Workers -- `adapter-static` – only produces client-side static assets; compatible with - Cloudflare Pages - -> **Note:** Cloudflare Pages' new Workers integration is currently in beta.
-> Compared to `adapter-cloudflare-workers`, `adapter-cloudflare` is the preferred approach for most users since building on top of Pages unlocks automatic builds and deploys, preview deployments, instant rollbacks, etc.
-> From SvelteKit's perspective, there is no difference and no functionality loss when migrating to/from the Workers and the Pages adapters. +> Requires [Wrangler v2](https://developers.cloudflare.com/workers/wrangler/get-started/). ## Usage @@ -58,7 +47,7 @@ workers_dev = true https://dash.cloudflare.com/ ``` -> It's recommended that you add the `.cloudflare` directory (or whichever directories you specified for `main` and `site.bucket`) to your `.gitignore`. +> You should add the `.cloudflare` directory (or whichever directories you specified for `main` and `site.bucket`) to your `.gitignore`. You will need to install [wrangler](https://developers.cloudflare.com/workers/wrangler/get-started/) and log in, if you haven't already: @@ -103,9 +92,6 @@ export async function POST({ request, platform }) { To make these types available to your app, reference them in your `src/app.d.ts`: ```diff -/// -+/// - declare namespace App { interface Platform { + env?: { @@ -122,8 +108,4 @@ declare namespace App { ### Accessing the file system -You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. - -## Changelog - -[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-cloudflare-workers/CHANGELOG.md). +You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. \ No newline at end of file diff --git a/documentation/docs/25-build-and-deploy/80-adapter-netlify.md b/documentation/docs/25-build-and-deploy/80-adapter-netlify.md index 1a14a2f0a062..553f38b8e878 100644 --- a/documentation/docs/25-build-and-deploy/80-adapter-netlify.md +++ b/documentation/docs/25-build-and-deploy/80-adapter-netlify.md @@ -2,17 +2,13 @@ title: Netlify --- -A SvelteKit adapter that creates a Netlify app. +To deploy to Netlify, use [`adapter-netlify`](https://github.com/sveltejs/kit/tree/master/packages/adapter-netlify). -If you're using [adapter-auto](adapter-auto), you don't need to install this unless you need to specify Netlify-specific options, since it's already included. +This adapter will be installed by default when you use [`adapter-auto`](/docs/adapter-auto), but adding it to your project allows you to specify Netlify-specific options. -## Installation +## Usage -```bash -npm i -D @sveltejs/adapter-netlify -``` - -You can then configure it inside of `svelte.config.js`: +Install with `npm i -D @sveltejs/adapter-netlify`, then add the adapter to your `svelte.config.js`: ```js // @errors: 2307 @@ -74,20 +70,20 @@ export default { You may build your app using functionality provided directly by SvelteKit without relying on any Netlify functionality. Using the SvelteKit versions of these features will allow them to be used in dev mode, tested with integration tests, and to work with other adapters should you ever decide to switch away from Netlify. However, in some scenarios you may find it beneficial to use the Netlify versions of these features. One example would be if you're migrating an app that's already hosted on Netlify to SvelteKit. -### Using Netlify Redirect Rules +### Redirect rules During compilation, redirect rules are automatically appended to your `_redirects` file. (If it doesn't exist yet, it will be created.) That means: - `[[redirects]]` in `netlify.toml` will never match as `_redirects` has a [higher priority](https://docs.netlify.com/routing/redirects/#rule-processing-order). So always put your rules in the [`_redirects` file](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file). - `_redirects` shouldn't have any custom "catch all" rules such as `/* /foobar/:splat`. Otherwise the automatically appended rule will never be applied as Netlify is only processing [the first matching rule](https://docs.netlify.com/routing/redirects/#rule-processing-order). -### Using Netlify Forms +### Netlify Forms -1. Create your Netlify HTML form as described [here](https://docs.netlify.com/forms/setup/#html-forms), e.g. as `/routes/contact.svelte`. (Don't forget to add the hidden `form-name` input element!) +1. Create your Netlify HTML form as described [here](https://docs.netlify.com/forms/setup/#html-forms), e.g. as `/routes/contact/+page.svelte`. (Don't forget to add the hidden `form-name` input element!) 2. Netlify's build bot parses your HTML files at deploy time, which means your form must be [prerendered](https://kit.svelte.dev/docs/page-options#prerender) as HTML. You can either add `export const prerender = true` to your `contact.svelte` to prerender just that page or set the `kit.prerender.force: true` option to prerender all pages. -3. If your Netlify form has a [custom success message](https://docs.netlify.com/forms/setup/#success-messages) like `` then ensure the corresponding `/routes/success.svelte` exists and is prerendered. +3. If your Netlify form has a [custom success message](https://docs.netlify.com/forms/setup/#success-messages) like `` then ensure the corresponding `/routes/success/+page.svelte` exists and is prerendered. -### Using Netlify Functions +### Netlify Functions With this adapter, SvelteKit endpoints are hosted as [Netlify Functions](https://docs.netlify.com/functions/overview/). Netlify function handlers have additional context, including [Netlify Identity](https://docs.netlify.com/visitor-access/identity/) information. You can access this context via the `event.platform.context` field inside your hooks and `+page.server` or `+layout.server` endpoints. These are [serverless functions](https://docs.netlify.com/functions/overview/) when the `edge` property is `false` in the adapter config or [edge functions](https://docs.netlify.com/edge-functions/overview/#app) when it is `true`. @@ -115,8 +111,4 @@ Additionally, you can add your own Netlify functions by creating a directory for ### Accessing the file system -You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. - -## Changelog - -[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-netlify/CHANGELOG.md). +You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. \ No newline at end of file diff --git a/documentation/docs/25-build-and-deploy/90-adapter-vercel.md b/documentation/docs/25-build-and-deploy/90-adapter-vercel.md index 4232310b6de3..4bad752c5252 100644 --- a/documentation/docs/25-build-and-deploy/90-adapter-vercel.md +++ b/documentation/docs/25-build-and-deploy/90-adapter-vercel.md @@ -2,25 +2,23 @@ title: Vercel --- -A SvelteKit adapter that creates a Vercel app. +To deploy to Vercel, use [`adapter-vercel`](https://github.com/sveltejs/kit/tree/master/packages/adapter-vercel). -If you're using [adapter-auto](adapter-auto), you don't need to install this unless you need to specify Vercel-specific options, since it's already included. +This adapter will be installed by default when you use [`adapter-auto`](/docs/adapter-auto), but adding it to your project allows you to specify Vercel-specific options. ## Usage -Add `"@sveltejs/adapter-vercel": "next"` to the `devDependencies` in your `package.json` and run `npm install`. - -Then in your `svelte.config.js`: +Install with `npm i -D @sveltejs/adapter-vercel`, then add the adapter to your `svelte.config.js`: ```js // @errors: 2307 /// file: svelte.config.js -import vercel from '@sveltejs/adapter-vercel'; +import adapter from '@sveltejs/adapter-vercel'; export default { kit: { // default options are shown - adapter: vercel({ + adapter: adapter({ // if true, will deploy the app using edge functions // (https://vercel.com/docs/concepts/functions/edge-functions) // rather than serverless functions @@ -83,8 +81,4 @@ Projects created before a certain date will default to using Node 14, while Svel ### Accessing the file system -You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. - -## Changelog - -[The Changelog for this package is available on GitHub](https://github.com/sveltejs/kit/blob/master/packages/adapter-vercel/CHANGELOG.md). +You can't access the file system through methods like `fs.readFileSync` in Serverless/Edge environments. If you need to access files that way, do that during building the app through [prerendering](https://kit.svelte.dev/docs/page-options#prerender). If you have a blog for example and don't want to manage your content through a CMS, then you need to prerender the content (or prerender the endpoint from which you get it) and redeploy your blog everytime you add new content. \ No newline at end of file From 1aa5ddace58362a9551ed6d5cc070f3900d437ea Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 16:29:03 -0500 Subject: [PATCH 17/23] expose App.Platform automatically if adapter-cloudflare-workers is installed --- .changeset/afraid-schools-scream.md | 5 +++++ packages/adapter-cloudflare-workers/index.d.ts | 1 + 2 files changed, 6 insertions(+) create mode 100644 .changeset/afraid-schools-scream.md diff --git a/.changeset/afraid-schools-scream.md b/.changeset/afraid-schools-scream.md new file mode 100644 index 000000000000..c34528848bae --- /dev/null +++ b/.changeset/afraid-schools-scream.md @@ -0,0 +1,5 @@ +--- +'@sveltejs/adapter-cloudflare-workers': patch +--- + +feat: expose `App.Platform` interface automatically diff --git a/packages/adapter-cloudflare-workers/index.d.ts b/packages/adapter-cloudflare-workers/index.d.ts index 260ec62b75f9..8b90611b73c3 100644 --- a/packages/adapter-cloudflare-workers/index.d.ts +++ b/packages/adapter-cloudflare-workers/index.d.ts @@ -1,3 +1,4 @@ import { Adapter } from '@sveltejs/kit'; +import './ambient.js'; export default function plugin(options: { config?: string }): Adapter; From cf351f76bede48e7c7ae4303979776c0216c6fc9 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 16:32:27 -0500 Subject: [PATCH 18/23] Update .changeset/hungry-singers-tease.md --- .changeset/hungry-singers-tease.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.changeset/hungry-singers-tease.md b/.changeset/hungry-singers-tease.md index e72c9b29f353..ffca95519836 100644 --- a/.changeset/hungry-singers-tease.md +++ b/.changeset/hungry-singers-tease.md @@ -1,10 +1,11 @@ --- '@sveltejs/adapter-auto': patch '@sveltejs/adapter-cloudflare': patch +'@sveltejs/adapter-cloudflare-workers': patch +'@sveltejs/adapter-netlify': patch '@sveltejs/adapter-node': patch '@sveltejs/adapter-static': patch -'create-svelte': patch -'@sveltejs/kit': patch +'@sveltejs/adapter-vercel': patch --- docs: add more indepth docs on building your app From 27e6ba73bddfba57d363a84ceecd5a74c2c6bb99 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 16:32:32 -0500 Subject: [PATCH 19/23] Update .changeset/hungry-singers-tease.md --- .changeset/hungry-singers-tease.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/hungry-singers-tease.md b/.changeset/hungry-singers-tease.md index ffca95519836..8f4a695af256 100644 --- a/.changeset/hungry-singers-tease.md +++ b/.changeset/hungry-singers-tease.md @@ -8,4 +8,4 @@ '@sveltejs/adapter-vercel': patch --- -docs: add more indepth docs on building your app +docs: move adapter docs to site From 193791922ca4e14ec7028fcb30fb11ded3e2b2e6 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 16:39:02 -0500 Subject: [PATCH 20/23] fix links --- documentation/docs/20-core-concepts/20-load.md | 2 +- documentation/docs/25-build-and-deploy/10-building-your-app.md | 2 +- documentation/docs/25-build-and-deploy/20-adapters.md | 2 +- packages/kit/types/ambient.d.ts | 2 +- sites/kit.svelte.dev/package.json | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/docs/20-core-concepts/20-load.md b/documentation/docs/20-core-concepts/20-load.md index ebea67a8420f..3df805300c05 100644 --- a/documentation/docs/20-core-concepts/20-load.md +++ b/documentation/docs/20-core-concepts/20-load.md @@ -192,7 +192,7 @@ Often the `load` function depends on the URL in one way or another. For this, th An instance of [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL), containing properties like the `origin`, `hostname`, `pathname` and `searchParams` (which contains the parsed query string as a [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object). `url.hash` cannot be accessed during `load`, since it is unavailable on the server. -> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](/docs/adapters#supported-environments-node-js), for example, you may need to configure the adapter in order for the URL to be correct. +> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](/docs/adapter-node), for example, you may need to configure the adapter in order for the URL to be correct. ### route diff --git a/documentation/docs/25-build-and-deploy/10-building-your-app.md b/documentation/docs/25-build-and-deploy/10-building-your-app.md index 8b093b0a4bb8..60005f696c27 100644 --- a/documentation/docs/25-build-and-deploy/10-building-your-app.md +++ b/documentation/docs/25-build-and-deploy/10-building-your-app.md @@ -27,4 +27,4 @@ export function load() { ## Preview your app -After building, you can view your production build locally with `vite preview` (via `npm run preview`). Note that this will run the app in Node, and so is not a perfect reproduction of your deployed app — adapter-specific adjustments like the [`platform` object](adapters#supported-environments-platform-specific-context) do not apply to previews. +After building, you can view your production build locally with `vite preview` (via `npm run preview`). Note that this will run the app in Node, and so is not a perfect reproduction of your deployed app — adapter-specific adjustments like the [`platform` object](adapters#platform-specific-context) do not apply to previews. diff --git a/documentation/docs/25-build-and-deploy/20-adapters.md b/documentation/docs/25-build-and-deploy/20-adapters.md index 3b7b8f782d82..815cfab708bd 100644 --- a/documentation/docs/25-build-and-deploy/20-adapters.md +++ b/documentation/docs/25-build-and-deploy/20-adapters.md @@ -43,7 +43,7 @@ const config = { export default config; ``` -## Platform-specific content +## Platform-specific context Some adapters may have access to additional information about the request. For example, Cloudflare Workers can access an `env` object containing KV namespaces etc. This can be passed to the `RequestEvent` used in [hooks](/docs/hooks) and [server routes](/docs/routing#server) as the `platform` property — consult each adapter's documentation to learn more. diff --git a/packages/kit/types/ambient.d.ts b/packages/kit/types/ambient.d.ts index 57d62ce63eb7..8a81037954c4 100644 --- a/packages/kit/types/ambient.d.ts +++ b/packages/kit/types/ambient.d.ts @@ -40,7 +40,7 @@ declare namespace App { export interface PageData {} /** - * If your adapter provides [platform-specific context](https://kit.svelte.dev/docs/adapters#supported-environments-platform-specific-context) via `event.platform`, you can specify it here. + * If your adapter provides [platform-specific context](https://kit.svelte.dev/docs/adapters#platform-specific-context) via `event.platform`, you can specify it here. */ export interface Platform {} } diff --git a/sites/kit.svelte.dev/package.json b/sites/kit.svelte.dev/package.json index a374c460c258..fa89f6627b0d 100644 --- a/sites/kit.svelte.dev/package.json +++ b/sites/kit.svelte.dev/package.json @@ -3,7 +3,7 @@ "version": "0.0.1", "scripts": { "update": "node scripts/check-doc-links.js && node scripts/types", - "dev": "npm run update && vite dev", + "dev": "vite dev", "build": "npm run update && vite build", "prebuild": "test \"$CI\" = true && npx pnpm install --store=node_modules/.pnpm-store || echo skipping pnpm install", "preview": "vite preview", From a618303c3dd43c36525750b9e21a70e58ab76ec7 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 16:42:36 -0500 Subject: [PATCH 21/23] amend App.Platform --- .changeset/sixty-rabbits-speak.md | 5 +++++ packages/adapter-cloudflare-workers/ambient.d.ts | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 .changeset/sixty-rabbits-speak.md diff --git a/.changeset/sixty-rabbits-speak.md b/.changeset/sixty-rabbits-speak.md new file mode 100644 index 000000000000..cebd6640fc94 --- /dev/null +++ b/.changeset/sixty-rabbits-speak.md @@ -0,0 +1,5 @@ +--- +'@sveltejs/adapter-cloudflare-workers': patch +--- + +fix: amend `App.Platform` diff --git a/packages/adapter-cloudflare-workers/ambient.d.ts b/packages/adapter-cloudflare-workers/ambient.d.ts index e0ee9db199db..aa6e1b79ee35 100644 --- a/packages/adapter-cloudflare-workers/ambient.d.ts +++ b/packages/adapter-cloudflare-workers/ambient.d.ts @@ -3,10 +3,10 @@ import { Cache, CacheStorage } from '@cloudflare/workers-types'; declare global { namespace App { export interface Platform { - context?: { + context: { waitUntil(promise: Promise): void; }; - caches?: CacheStorage & { default: Cache }; + caches: CacheStorage; } } } From f17a42de1c32c92756c75ff8f711e857fc55a9c9 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 16:59:03 -0500 Subject: [PATCH 22/23] fix, hopefully --- packages/adapter-cloudflare-workers/ambient.d.ts | 2 +- packages/adapter-cloudflare-workers/files/entry.js | 7 ++++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/packages/adapter-cloudflare-workers/ambient.d.ts b/packages/adapter-cloudflare-workers/ambient.d.ts index aa6e1b79ee35..5978f0dd3850 100644 --- a/packages/adapter-cloudflare-workers/ambient.d.ts +++ b/packages/adapter-cloudflare-workers/ambient.d.ts @@ -1,4 +1,4 @@ -import { Cache, CacheStorage } from '@cloudflare/workers-types'; +import { CacheStorage } from '@cloudflare/workers-types'; declare global { namespace App { diff --git a/packages/adapter-cloudflare-workers/files/entry.js b/packages/adapter-cloudflare-workers/files/entry.js index 7501777152a4..0969ba1bbf07 100644 --- a/packages/adapter-cloudflare-workers/files/entry.js +++ b/packages/adapter-cloudflare-workers/files/entry.js @@ -67,7 +67,12 @@ export default { // dynamically-generated pages return await server.respond(req, { - platform: { env, context, caches }, + platform: { + env, + context, + // @ts-expect-error lib.dom is interfering with workers-types + caches + }, getClientAddress() { return req.headers.get('cf-connecting-ip'); } From e782c12ce1643cc6187131914829fb192cdc4123 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 18 Jan 2023 17:27:30 -0500 Subject: [PATCH 23/23] tweaks --- documentation/docs/25-build-and-deploy/50-adapter-static.md | 6 +++--- .../docs/25-build-and-deploy/60-adapter-cloudflare.md | 1 + .../25-build-and-deploy/70-adapter-cloudflare-workers.md | 2 ++ documentation/docs/25-build-and-deploy/90-adapter-vercel.md | 2 +- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/documentation/docs/25-build-and-deploy/50-adapter-static.md b/documentation/docs/25-build-and-deploy/50-adapter-static.md index 8ca4bf0ab254..cd2ce0566712 100644 --- a/documentation/docs/25-build-and-deploy/50-adapter-static.md +++ b/documentation/docs/25-build-and-deploy/50-adapter-static.md @@ -33,8 +33,7 @@ export default { ...and add the [`prerender`](/docs/page-options#prerender) option to your root layout: ```js -// src/routes/+layout.js - +/// file: src/routes/+layout.js // This can be false if you're using a fallback (i.e. SPA mode) export const prerender = true; ``` @@ -50,6 +49,7 @@ Some platforms have zero-config support (more to come in future): On these platforms, you should omit the adapter options so that `adapter-static` can provide the optimal configuration: ```diff +/// file: svelte.config.js export default { kit: { - adapter: adapter({...}), @@ -105,7 +105,7 @@ export default { ``` ```js -// src/routes/+layout.js +/// file: src/routes/+layout.js export const ssr = false; ``` diff --git a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md index 234881cefd38..c3c9d5b451fa 100644 --- a/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md +++ b/documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md @@ -58,6 +58,7 @@ export async function POST({ request, platform }) { To make these types available to your app, reference them in your `src/app.d.ts`: ```diff +/// file: src/app.d.ts declare namespace App { interface Platform { + env?: { diff --git a/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md b/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md index cb9a26226ad8..ad3ada052f78 100644 --- a/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md +++ b/documentation/docs/25-build-and-deploy/70-adapter-cloudflare-workers.md @@ -29,6 +29,7 @@ export default { This adapter expects to find a [wrangler.toml](https://developers.cloudflare.com/workers/platform/sites/configuration) file in the project root. It should look something like this: ```toml +/// file: wrangler.toml name = "" account_id = "" @@ -92,6 +93,7 @@ export async function POST({ request, platform }) { To make these types available to your app, reference them in your `src/app.d.ts`: ```diff +/// file: src/app.d.ts declare namespace App { interface Platform { + env?: { diff --git a/documentation/docs/25-build-and-deploy/90-adapter-vercel.md b/documentation/docs/25-build-and-deploy/90-adapter-vercel.md index 4bad752c5252..81bc7d5954de 100644 --- a/documentation/docs/25-build-and-deploy/90-adapter-vercel.md +++ b/documentation/docs/25-build-and-deploy/90-adapter-vercel.md @@ -54,7 +54,7 @@ export function load() { ``` ```svelte - +/// file: +layout.svelte