docs: Document $lib/server and *.server.* server-only modules (#6646)

* feat: Added server-only modules docs

* fix: Script blocks and naming

* feat: Other miscellaneous docs

* fix: Header level

* flesh out docs a bit more, amend stuff around dynamic imports

* reference public-facing code rather than client-side code

* small tweak

* merge

Co-authored-by: Rich Harris <hello@rich-harris.dev>

Author: elliott-with-the-longest-name-on-github

.changeset/gold-walls-rush.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+Change illegal import message to reference public-facing code rather than client-side code

documentation/docs/01-project-structure.md

@@ -8,6 +8,8 @@ A typical SvelteKit project looks like this:
 my-project/
 ├ src/
 │ ├ lib/
+│ │ ├ server/
+│ │ │ └ [your server-only lib files]
 │ │ └ [your lib files]
 │ ├ params/
 │ │ └ [your param matchers]
@@ -35,6 +37,7 @@ You'll also find common files like `.gitignore` and `.npmrc` (and `.prettierrc`
 The `src` directory contains the meat of your project.
 
 - `lib` contains your library code, which can be imported via the [`$lib`](/docs/modules#$lib) alias, or packaged up for distribution using [`svelte-package`](/docs/packaging)
+  - `server` contains your server-only library code. It can be imported by using the [`$lib/server`](/docs/server-only-modules) alias. SvelteKit will prevent you from importing these in client code.
 - `params` contains any [param matchers](/docs/advanced-routing#matching) your app needs
 - `routes` contains the [routes](/docs/routing) of your application
 - `app.html` is your page template — an HTML document containing the following placeholders:

documentation/docs/08-server-only-modules.md

@@ -0,0 +1,54 @@
+---
+title: Server-only modules
+---
+
+Like a good friend, SvelteKit keeps your secrets. When writing your backend and frontend in the same repository, it can be easy to accidentally import sensitive data into your front-end code (environment variables containing API keys, for example). SvelteKit provides a way to prevent this entirely: server-only modules.
+
+### Private environment variables
+
+The `$env/static/private` and `$env/dynamic/private` modules, which are covered in the [modules](/docs/modules) section, can only be imported into modules that only run on the server, such as [`hooks.server.js`](/docs/hooks#server-hooks) or [`+page.server.js`](/docs/routing#page-page-server-js).
+
+### Your modules
+
+You can make your own modules server-only in two ways:
+
+- adding `.server` to the filename, e.g. `secrets.server.js`
+- placing them in `$lib/server`, e.g. `$lib/server/secrets.js`
+
+### How it works
+
+Any time you have public-facing code that imports server-only code (whether directly or indirectly)...
+
+```js
+// @errors: 7005
+/// file: $lib/server/secrets.js
+export const atlantisCoordinates = [/* redacted */];
+```
+
+```js
+// @errors: 2307 7006
+/// file: src/routes/utils.js
+export { atlantisCoordinates } from '$lib/server/secrets.js';
+
+export const add = (a, b) => a + b;
+```
+
+```html
+/// file: src/routes/+page.svelte
+<script>
+	import { add } from './utils.js';
+</script>
+```
+
+...SvelteKit will error:
+
+```
+Cannot import $lib/server/secrets.js into public-facing code:
+- src/routes/+page.svelte
+	- src/routes/utils.js
+		- $lib/server/secrets.js
+```
+
+Even though the public-facing code — `src/routes/+page.svelte` — only uses the `add` export and not the secret `atlantisCoordinates` export, the secret code could end up in JavaScript that the browser downloads, and so the import chain is considered unsafe.
+
+This feature also works with dynamic imports, even interpolated ones like ``await import(`./${foo}.js`)``, with one small caveat: during development, if there are two or more dynamic imports between the public-facing code and the server-only module, the illegal import will not be detected the first time the code is loaded.