From dc787f79e15263ed8d392895a90296a4502be8ac Mon Sep 17 00:00:00 2001
From: Simon Holthausen <simon.holthausen@vercel.com>
Date: Fri, 13 Jan 2023 11:40:40 +0100
Subject: [PATCH] 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 @@
 				<img src={azure} alt="" />
 				<span>Azure</span>
 			</a>
-			<a target="_blank" rel="noreferrer" href="https://kit.svelte.dev/docs/adapters">
+			<a target="_blank" rel="noreferrer" href="https://kit.svelte.dev/docs/building-your-app">
 				<img src={plus} alt="" />
 				<span>More...</span>
 			</a>