diff --git a/documentation/docs/14-configuration.md b/documentation/docs/14-configuration.md index 1623136623b1..43a45fd9a5f5 100644 --- a/documentation/docs/14-configuration.md +++ b/documentation/docs/14-configuration.md @@ -25,13 +25,22 @@ const config = { serviceWorker: 'src/service-worker', template: 'src/app.html' }, - serviceWorker: { - exclude: [] - }, floc: false, host: null, hostHeader: null, hydrate: true, + package: { + dir: 'package', + emitTypes: true, + exports: { + include: ['**'], + exclude: ['_*', '**/_*'] + }, + files: { + include: ['**'], + exclude: [] + } + }, paths: { assets: '', base: '' @@ -43,21 +52,12 @@ const config = { pages: ['*'] }, router: true, + serviceWorker: { + exclude: [] + }, ssr: true, target: null, trailingSlash: 'never', - package: { - dir: 'package', - exports: { - include: ['**'], - exclude: ['_*', '**/_*'] - }, - files: { - include: ['**'], - exclude: [] - }, - emitTypes: true - }, vite: () => ({}) }, @@ -85,18 +85,12 @@ The directory relative to `paths.assets` where the built JS and CSS (and importe An object containing zero or more of the following `string` values: - `assets` — a place to put static files that should have stable URLs and undergo no processing, such as `favicon.ico` or `manifest.json` +- `hooks` — the location of your hooks module (see [Hooks](#hooks)) - `lib` — your app's internal library, accessible throughout the codebase as `$lib` - `routes` — the files that define the structure of your app (see [Routing](#routing)) - `serviceWorker` — the location of your service worker's entry point (see [Service workers](#service-workers)) -- `hooks` — the location of your hooks module (see [Hooks](#hooks)) - `template` — the location of the template for HTML responses -### serviceWorker - -An object containing zero or more of the following values: - -- `exclude` - an array of glob patterns relative to `files.assets` dir. Files matching any of these would not be available in `$service-worker.files` e.g. if `files.assets` has value `static` then ['og-tags-images/**/*'] would match all files under `static/og-tags-images` dir. - ### floc Google's [FLoC](https://github.com/WICG/floc) is a technology for targeted advertising that the [Electronic Frontier Foundation](https://www.eff.org/) has deemed [harmful](https://www.eff.org/deeplinks/2021/03/googles-floc-terrible-idea) to user privacy. [Browsers other than Chrome](https://www.theverge.com/2021/4/16/22387492/google-floc-ad-tech-privacy-browsers-brave-vivaldi-edge-mozilla-chrome-safari) have declined to implement it. @@ -132,6 +126,15 @@ export default { Whether to [hydrate](#ssr-and-javascript-hydrate) the server-rendered HTML with a client-side app. (It's rare that you would set this to `false` on an app-wide basis.) +### package + +Options related to [creating a package](#packaging). + +- `dir` - output directory +- `emitTypes` - by default, `svelte-kit package` will automatically generate types for your package in the form of `d.ts.` files. While generating types is configurable, we believe it is best for the ecosystem quality to generate types, always. Please make sure you have a good reason when setting it to `false` (for example when you want to provide handwritten type definitions instead). +- `exports` - contains a `includes` and a `excludes` array which specifies which files to mark as exported from the `exports` field of the `package.json` +- `files` - contains a `includes` and a `excludes` array which specifies which files to process and copy over when packaging + ### paths An object containing zero or more of the following `string` values: @@ -152,6 +155,12 @@ See [Prerendering](#ssr-and-javascript-prerender). An object containing zero or Enables or disables the client-side [router](#ssr-and-javascript-router) app-wide. +### serviceWorker + +An object containing zero or more of the following values: + +- `exclude` - an array of glob patterns relative to `files.assets` dir. Files matching any of these would not be available in `$service-worker.files` e.g. if `files.assets` has value `static` then ['og-tags-images/**/*'] would match all files under `static/og-tags-images` dir. + ### ssr Enables or disables [server-side rendering](#ssr-and-javascript-ssr) app-wide. @@ -170,15 +179,6 @@ Whether to remove, append, or ignore trailing slashes when resolving URLs to rou > Ignoring trailing slashes is not recommended — the semantics of relative paths differ between the two cases (`./y` from `/x` is `/y`, but from `/x/` is `/x/y`), and `/x` and `/x/` are treated as separate URLs which is harmful to SEO. If you use this option, ensure that you implement logic for conditionally adding or removing trailing slashes from `request.path` inside your [`handle`](#hooks-handle) function. -### package - -Options related to [creating a package](#packaging). - -- `dir` - output directory -- `exports` - contains a `includes` and a `excludes` array which specifies which files to mark as exported from the `exports` field of the `package.json` -- `files` - contains a `includes` and a `excludes` array which specifies which files to process and copy over when packaging -- `emitTypes` - by default, `svelte-kit package` will automatically generate types for your package in the form of `d.ts.` files. While generating types is configurable, we believe it is best for the ecosystem quality to generate types, always. Please make sure you have a good reason when setting it to `false` (for example when you want to provide handwritten type definitions instead). - ### vite A [Vite config object](https://vitejs.dev/config), or a function that returns one. Not all configuration options can be set, since SvelteKit depends on certain values being configured internally. diff --git a/documentation/docs/80-adapter-api.md b/documentation/docs/80-adapter-api.md index 410a1da26876..0f14a4d275b3 100644 --- a/documentation/docs/80-adapter-api.md +++ b/documentation/docs/80-adapter-api.md @@ -5,15 +5,17 @@ title: Writing an Adapter 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 /** * @param {AdapterSpecificOptions} options */ export default function (options) { /** @type {import('@sveltejs/kit').Adapter} */ return { - name: '', + name: 'adapter-package-name', async adapt({ utils, config }) { + // adapter implementation } }; } @@ -22,6 +24,7 @@ export default function (options) { The types for `Adapter` and its parameters are available in [types/config.d.ts](https://github.com/sveltejs/kit/blob/master/packages/kit/types/config.d.ts). Within the `adapt` method, there are a number of things that an adapter should do: + - Clear out the build directory - Output code that: - Calls `init` diff --git a/packages/kit/types/config.d.ts b/packages/kit/types/config.d.ts index 365cf1f741b1..45482dddb12f 100644 --- a/packages/kit/types/config.d.ts +++ b/packages/kit/types/config.d.ts @@ -44,11 +44,9 @@ export type Config = { host?: string; hostHeader?: string; hydrate?: boolean; - serviceWorker?: { - exclude?: string[]; - }; package?: { dir?: string; + emitTypes?: boolean; exports?: { include?: string[]; exclude?: string[]; @@ -57,11 +55,10 @@ export type Config = { include?: string[]; exclude?: string[]; }; - emitTypes?: boolean; }; paths?: { - base?: string; assets?: string; + base?: string; }; prerender?: { crawl?: boolean; @@ -70,6 +67,9 @@ export type Config = { pages?: string[]; }; router?: boolean; + serviceWorker?: { + exclude?: string[]; + }; ssr?: boolean; target?: string; trailingSlash?: TrailingSlash; @@ -98,11 +98,9 @@ export type ValidatedConfig = { host: string; hostHeader: string; hydrate: boolean; - serviceWorker: { - exclude: string[]; - }; package: { dir: string; + emitTypes: boolean; exports: { include: string[]; exclude: string[]; @@ -111,11 +109,10 @@ export type ValidatedConfig = { include: string[]; exclude: string[]; }; - emitTypes: boolean; }; paths: { - base: string; assets: string; + base: string; }; prerender: { crawl: boolean; @@ -124,6 +121,9 @@ export type ValidatedConfig = { pages: string[]; }; router: boolean; + serviceWorker: { + exclude: string[]; + }; ssr: boolean; target: string; trailingSlash: TrailingSlash;