Merge branch 'master' into gh-6868

Author: Rich-Harris

.github/workflows/ci.yml

@@ -38,16 +38,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [16]
-        os: [ubuntu-latest, windows-latest]
-        e2e-browser: ['chromium']
         include:
           - node-version: 16
             os: ubuntu-latest
-            e2e-browser: 'firefox'
-          - node-version: 16
-            os: macOS-latest
-            e2e-browser: 'webkit'
+            e2e-browser: 'chromium'
           - node-version: 18
             os: ubuntu-latest
             e2e-browser: 'chromium'
@@ -76,3 +70,41 @@ jobs:
           retention-days: 3
           name: test-failure-${{ github.run_id }}-${{ matrix.os }}-${{ matrix.node-version }}-${{ matrix.e2e-browser }}
           path: test-results.tar.gz
+  Cross-browser-test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - node-version: 16
+            os: windows-2019 # slowness reported on newer versions https://github.com/actions/runner-images/issues/5166
+            e2e-browser: 'firefox'
+          - node-version: 16
+            os: macOS-latest
+            e2e-browser: 'webkit'
+    env:
+      TURBO_CACHE_KEY: ${{ matrix.os }}-${{ matrix.node-version }}
+      KIT_E2E_BROWSER: ${{matrix.e2e-browser}}
+    steps:
+      - run: git config --global core.autocrlf false
+      - uses: actions/checkout@v3
+      - uses: pnpm/[email protected]
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm playwright install ${{ matrix.e2e-browser }}
+      - run: pnpm test:cross-platform
+      - name: Archive test results
+        if: failure()
+        shell: bash
+        run: find packages -type d -name test-results -not -empty | tar -czf test-results-cross-platform.tar.gz --files-from=-
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v3
+        with:
+          retention-days: 3
+          name: test-failure-cross-platform-${{ github.run_id }}-${{ matrix.os }}-${{ matrix.node-version }}-${{ matrix.e2e-browser }}
+          path: test-results-cross-platform.tar.gz

CONTRIBUTING.md

@@ -44,7 +44,7 @@ You can run the test server with `cd packages/kit/test/apps/basics; pnpm run dev
 
 You may need to install some dependencies first, e.g. with `npx playwright install-deps` (which only works on Ubuntu).
 
-If there are tests that fail on the CI, you can retrieve the failed screenshots by going to the summary page of the CI run. You can usually find this by clicking on "Details" of the check results, click "Summary" at the top-left corner, and then scroll to the bottom "Artifacts" section to download the archive.
+If there are tests that fail on the CI, you can retrieve the failed screenshots by going to the summary page of the CI run. You can usually find this by clicking on "Details" of the check results, clicking "Summary" at the top-left corner, and then scrolling to the bottom "Artifacts" section to download the archive.
 
 It is very easy to introduce flakiness in a browser test. If you try to fix the flakiness in a test, you can run it until failure to gain some confidence you've fixed the test with a command like:
 
@@ -85,15 +85,15 @@ There are a few guidelines we follow:
 - Avoid creating new test projects under `packages/kit/test/apps` but reuse an existing one when possible
 - Ensure `pnpm lint` and `pnpm check` pass. You can run `pnpm format` to format the code
 
-To use the git hooks in the repo, which will save you waiting for CI to tell you that you forgot to lint, run this:
+To use the git hooks in the repo, which will save you from waiting for CI to tell you that you forgot to lint, run this:
 
 ```bash
 git config core.hookspath .githooks
 ```
 
 ### Generating changelogs
 
-For changes to be reflected in package changelogs, run `pnpm changeset` and follow the prompts. All changesets should be `patch` until SvelteKit 1.0
+For changes to be reflected in package changelogs, run `pnpm changeset` and follow the prompts.
 
 ## Releases
 

documentation/docs/10-getting-started/10-introduction.md

@@ -10,7 +10,7 @@ title: Introduction
 
 ## What is SvelteKit?
 
-SvelteKit is a framework for rapidly developing robust, performant web applications using [Svelte](https://svelte.dev/).
+SvelteKit is a framework for rapidly developing robust, performant web applications using [Svelte](https://svelte.dev/). If you're coming from React, SvelteKit is similar to Next. If you're coming from Vue, SvelteKit is similar to Nuxt.
 
 ## What is Svelte?
 
@@ -20,6 +20,6 @@ In short, Svelte is a way of writing user interface components — like a naviga
 
 Svelte renders UI components. You can compose these components and render an entire page with just Svelte, but you need more than just Svelte to write an entire app.
 
-SvelteKit provides basic functionality like a [router](/docs/glossary#routing) — which updates the UI when a link is clicked — and [server-side rendering (SSR)](/docs/glossary#ssr). But beyond that, building an app with all the modern best practices is fiendishly complicated. Those practices include [build optimizations](https://vitejs.dev/guide/features.html#build-optimizations), so that you load only the minimal required code; [offline support](/docs/service-workers); [preloading](/docs/link-options#data-sveltekit-preload-data) pages before the user initiates navigation; [configurable rendering](/docs/page-options) that allows you to render different parts of your app on the server with [SSR](/docs/glossary#ssr), in the browser [client-side rendering](/docs/glossary#csr-and-spa), or at build-time with [prerendering](/docs/glossary#prerendering); and many other things. SvelteKit does all the boring stuff for you so that you can get on with the creative part.
+SvelteKit provides basic functionality like a [router](glossary#routing) — which updates the UI when a link is clicked — and [server-side rendering (SSR)](glossary#ssr). But beyond that, building an app with all the modern best practices is fiendishly complicated. Those practices include [build optimizations](https://vitejs.dev/guide/features.html#build-optimizations), so that you load only the minimal required code; [offline support](service-workers); [preloading](link-options#data-sveltekit-preload-data) pages before the user initiates navigation; [configurable rendering](page-options) that allows you to render different parts of your app on the server with [SSR](glossary#ssr), in the browser [client-side rendering](glossary#csr), or at build-time with [prerendering](glossary#prerendering); and many other things. SvelteKit does all the boring stuff for you so that you can get on with the creative part.
 
-It uses [Vite](https://vitejs.dev/) with a [Svelte plugin](https://github.com/sveltejs/vite-plugin-svelte) to provide a lightning-fast and feature-rich development experience with [Hot Module Replacement (HMR)](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#hot), where changes to your code are reflected in the browser instantly.
+It reflects changes to your code in the browser instantly to provide a lightning-fast and feature-rich development experience by leveraging [Vite](https://vitejs.dev/) with a [Svelte plugin](https://github.com/sveltejs/vite-plugin-svelte) to do [Hot Module Replacement (HMR)](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#hot).

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

@@ -17,7 +17,8 @@ my-project/
 │ │ └ [your routes]
 │ ├ app.html
 │ ├ error.html
-│ └ hooks.js
+│ ├ hooks.client.js
+│ └ hooks.server.js
 ├ static/
 │ └ [your static assets]
 ├ tests/
@@ -34,22 +35,24 @@ You'll also find common files like `.gitignore` and `.npmrc` (and `.prettierrc`
 
 ### src
 
-The `src` directory contains the meat of your project.
+The `src` directory contains the meat of your project. Everything except `src/routes` and `src/app.html` is optional.
 
-- `lib` contains your library code (utilities and components), 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. You can also colocate other components that are only used within a single route here
+- `lib` contains your library code (utilities and components), which can be imported via the [`$lib`](modules#$lib) alias, or packaged up for distribution using [`svelte-package`](packaging)
+  - `server` contains your server-only library code. It can be imported by using the [`$lib/server`](server-only-modules) alias. SvelteKit will prevent you from importing these in client code.
+- `params` contains any [param matchers](advanced-routing#matching) your app needs
+- `routes` contains the [routes](routing) of your application. You can also colocate other components that are only used within a single route here
 - `app.html` is your page template — an HTML document containing the following placeholders:
   - `%sveltekit.head%` — `<link>` and `<script>` elements needed by the app, plus any `<svelte:head>` content
   - `%sveltekit.body%` — the markup for a rendered page. This should live inside a `<div>` or other element, rather than directly inside `<body>`, to prevent bugs caused by browser extensions injecting elements that are then destroyed by the hydration process. SvelteKit will warn you in development if this is not the case
-  - `%sveltekit.assets%` — either [`paths.assets`](/docs/configuration#paths), if specified, or a relative path to [`paths.base`](/docs/configuration#paths)
-  - `%sveltekit.nonce%` — a [CSP](/docs/configuration#csp) nonce for manually included links and scripts, if used
-- `error.html` (optional) is the page that is rendered when everything else fails. It can contain the following placeholders:
+  - `%sveltekit.assets%` — either [`paths.assets`](configuration#paths), if specified, or a relative path to [`paths.base`](configuration#paths)
+  - `%sveltekit.nonce%` — a [CSP](configuration#csp) nonce for manually included links and scripts, if used
+  - `%sveltekit.env.[NAME]%` - this will be replaced at render time with the `[NAME]` environment variable, which must begin with the [`publicPrefix`](https://kit.svelte.dev/docs/configuration#env) (usually `PUBLIC_`). It will fallback to `''` if not matched.
+- `error.html` is the page that is rendered when everything else fails. It can contain the following placeholders:
   - `%sveltekit.status%` — the HTTP status
   - `%sveltekit.error.message%` — the error message
-- `hooks.js` (optional) contains your application's [hooks](/docs/hooks)
-- `service-worker.js` (optional) contains your [service worker](/docs/service-workers)
+- `hooks.client.js` contains your client [hooks](/docs/hooks)
+- `hooks.server.js` contains your server [hooks](/docs/hooks)
+- `service-worker.js` contains your [service worker](/docs/service-workers)
 
 You can use `.ts` files instead of `.js` files, if using TypeScript.
 
@@ -71,18 +74,18 @@ When you create a project with `npm create svelte@latest`, you'll also notice th
 
 ### svelte.config.js
 
-This file contains your Svelte and SvelteKit [configuration](/docs/configuration).
+This file contains your Svelte and SvelteKit [configuration](configuration).
 
 ### tsconfig.json
 
 This file (or `jsconfig.json`, if you prefer type-checked `.js` files over `.ts` files) configures TypeScript, if you added typechecking during `npm create svelte@latest`. Since SvelteKit relies on certain configuration being set a specific way, it generates its own `.svelte-kit/tsconfig.json` file which your own config `extends`.
 
 ### vite.config.js
 
-A SvelteKit project is really just a [Vite](https://vitejs.dev) project that uses the [`@sveltejs/kit/vite`](/docs/modules#sveltejs-kit-vite) plugin, along with any other [Vite configuration](https://vitejs.dev/config/).
+A SvelteKit project is really just a [Vite](https://vitejs.dev) project that uses the [`@sveltejs/kit/vite`](modules#sveltejs-kit-vite) plugin, along with any other [Vite configuration](https://vitejs.dev/config/).
 
 ## Other files
 
 ### .svelte-kit
 
-As you develop and build your project, SvelteKit will generate files in a `.svelte-kit` directory (configurable as [`outDir`](/docs/configuration#outdir)). You can ignore its contents, and delete them at any time (they will be regenerated when you next `dev` or `build`).
+As you develop and build your project, SvelteKit will generate files in a `.svelte-kit` directory (configurable as [`outDir`](configuration#outdir)). You can ignore its contents, and delete them at any time (they will be regenerated when you next `dev` or `build`).

documentation/docs/10-getting-started/40-web-standards.md

@@ -4,21 +4,21 @@ 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](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:
 
 ## Fetch APIs
 
-SvelteKit uses [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch) for getting data from the network. It's available in [hooks](/docs/hooks) and [server routes](/docs/routing#server) as well as in the browser.
+SvelteKit uses [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch) for getting data from the network. It's available in [hooks](hooks) and [server routes](routing#server) as well as in the browser.
 
-> A special version of `fetch` is available in [`load`](/docs/load) functions, [server hooks](/docs/hooks#server-hooks) and [API routes](/docs/routing#server) for invoking endpoints directly during server-side rendering, without making an HTTP call, while preserving credentials. (To make credentialled fetches in server-side code outside `load`, you must explicitly pass `cookie` and/or `authorization` headers.) It also allows you to make relative requests, whereas server-side `fetch` normally requires a fully qualified URL.
+> A special version of `fetch` is available in [`load`](load) functions, [server hooks](hooks#server-hooks) and [API routes](routing#server) for invoking endpoints directly during server-side rendering, without making an HTTP call, while preserving credentials. (To make credentialled fetches in server-side code outside `load`, you must explicitly pass `cookie` and/or `authorization` headers.) It also allows you to make relative requests, whereas server-side `fetch` normally requires a fully qualified URL.
 
 Besides `fetch` itself, the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) includes the following interfaces:
 
 ### Request
 
-An instance of [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) is accessible in [hooks](/docs/hooks) and [server routes](/docs/routing#server) as `event.request`. It contains useful methods like `request.json()` and `request.formData()` for getting data that was posted to an endpoint.
+An instance of [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) is accessible in [hooks](hooks) and [server routes](routing#server) as `event.request`. It contains useful methods like `request.json()` and `request.formData()` for getting data that was posted to an endpoint.
 
 ### Response
 
@@ -74,7 +74,7 @@ Most of the time, your endpoints will return complete data, as in the `userAgent
 
 ## URL APIs
 
-URLs are represented by the [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) interface, which includes useful properties like `origin` and `pathname` (and, in the browser, `hash`). This interface shows up in various places — `event.url` in [hooks](/docs/hooks) and [server routes](/docs/routing#server), [`$page.url`](/docs/modules#$app-stores) in [pages](/docs/routing#page), `from` and `to` in [`beforeNavigate` and `afterNavigate`](/docs/modules#$app-navigation) and so on.
+URLs are represented by the [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) interface, which includes useful properties like `origin` and `pathname` (and, in the browser, `hash`). This interface shows up in various places — `event.url` in [hooks](hooks) and [server routes](routing#server), [`$page.url`](modules#$app-stores) in [pages](routing#page), `from` and `to` in [`beforeNavigate` and `afterNavigate`](modules#$app-navigation) and so on.
 
 ### URLSearchParams
 
@@ -95,7 +95,7 @@ const foo = url.searchParams.get('foo');
 
 ## Web Crypto
 
-The [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) is made available via the `crypto` global. It's used internally for [Content Security Policy](/docs/configuration#csp) headers, but you can also use it for things like generating UUIDs:
+The [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) is made available via the `crypto` global. It's used internally for [Content Security Policy](configuration#csp) headers, but you can also use it for things like generating UUIDs:
 
 ```js
 const uuid = crypto.randomUUID();