docs: more build docs

Transforming the adapters document into a more general build doc
closes #8500

.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

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:
 

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
 

documentation/docs/20-core-concepts/50-adapters.md → 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](#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.
 

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).
 

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'
 		);
 	}
 });

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.
 

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
 

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
 

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

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.

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;

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`
 					);

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 {}
 }

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;

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'];

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>