From 1c5681e27074a0b1380f4a8b0118ed5ab7c6ebd7 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Mon, 28 Nov 2022 15:18:12 -0500 Subject: [PATCH] maybe improve types documentation a bit (#7003) * throwing some ideas at the wall * better doc visuals from interface definitions * move types representation * tweak visuals * silence type error * please? * why don't I get these errors locally * boxes * border-radius * auto-prepend "ignore any", remove jsdoc types hack which wrecks jsdoc hover code in editors * remove this file in case we forget later * visually group things more tightly * collapse interface blocks * dont run twoslash on ts blocks * add links, fix some css * minor fixes * config types * remove unused code * move type extraction script as a precursor to reducing some of the indirection, to make it easier to work on nested properties * distinguish between ts and dts * hopefully fix deploy * consistent format * reduce indirection a bit * nested properties, albeit with terrible styling at the moment * more docs * improve styles a tiny bit * flesh out some stuff * more stuff * couple more * move SubmitFunction into @sveltejs/kit types * use /// type, so type hints get syntax highlighting * add some defaults * more defaults * remove unused typedef * consistency * fix code snippet * small tweaks * small fixes * tweaks * rename API reference to just reference * okay ts doesnt like that * missed a spot * changeset * fix link * refactor code in the direction of separating out config reference * remove unused code * systematise some stuff * generate config docs * get site building again * hackiest possible workaround * tweak some css * tweaks Co-authored-by: Simon Holthausen --- .changeset/bright-pianos-flow.md | 5 + .changeset/light-toes-rush.md | 5 + .changeset/young-needles-attack.md | 5 + .../docs/20-core-concepts/20-load.md | 4 +- .../docs/30-advanced/70-packaging.md | 10 +- .../docs/50-api-reference/10-configuration.md | 307 ------------- documentation/docs/50-api-reference/meta.json | 3 - .../docs/50-reference/10-configuration.md | 25 + .../20-cli.md | 0 .../30-modules.md | 2 +- .../40-types.md | 16 +- documentation/docs/50-reference/meta.json | 3 + packages/adapter-node/README.md | 2 +- .../templates/default/src/app.d.ts | 7 +- .../templates/skeleton/src/app.d.ts | 2 +- .../templates/skeletonlib/src/app.d.ts | 2 +- packages/kit/package.json | 6 +- packages/kit/scripts/extract-types.js | 166 ------- packages/kit/src/core/sync/write_ambient.js | 6 +- packages/kit/tsconfig.json | 7 +- packages/kit/types/ambient.d.ts | 55 +-- packages/kit/types/index.d.ts | 432 ++++++++++++++++-- packages/kit/types/private.d.ts | 9 + sites/kit.svelte.dev/.gitignore | 3 +- sites/kit.svelte.dev/package.json | 5 +- .../scripts}/check-doc-links.js | 10 +- sites/kit.svelte.dev/scripts/types/index.js | 279 +++++++++++ .../special-types/$env+dynamic+private.md | 0 .../special-types/$env+dynamic+public.md | 0 .../special-types/$env+static+private.md | 0 .../special-types/$env+static+public.md | 0 .../scripts/types}/special-types/$lib.md | 0 .../src/lib/docs/client/docs.css | 76 +++ .../src/lib/docs/client/shiki.css | 2 +- .../src/lib/docs/server/index.js | 32 +- .../src/lib/docs/server/modules.js | 18 - .../src/lib/docs/server/render.js | 158 +++++++ .../src/lib/docs/server/types.d.ts | 8 + .../src/lib/search/content.server.js | 13 +- .../kit.svelte.dev/src/routes/+layout.svelte | 4 +- 40 files changed, 1057 insertions(+), 630 deletions(-) create mode 100644 .changeset/bright-pianos-flow.md create mode 100644 .changeset/light-toes-rush.md create mode 100644 .changeset/young-needles-attack.md delete mode 100644 documentation/docs/50-api-reference/10-configuration.md delete mode 100644 documentation/docs/50-api-reference/meta.json create mode 100644 documentation/docs/50-reference/10-configuration.md rename documentation/docs/{50-api-reference => 50-reference}/20-cli.md (100%) rename documentation/docs/{50-api-reference => 50-reference}/30-modules.md (88%) rename documentation/docs/{50-api-reference => 50-reference}/40-types.md (93%) create mode 100644 documentation/docs/50-reference/meta.json delete mode 100644 packages/kit/scripts/extract-types.js rename {scripts => sites/kit.svelte.dev/scripts}/check-doc-links.js (85%) create mode 100644 sites/kit.svelte.dev/scripts/types/index.js rename {packages/kit/scripts => sites/kit.svelte.dev/scripts/types}/special-types/$env+dynamic+private.md (100%) rename {packages/kit/scripts => sites/kit.svelte.dev/scripts/types}/special-types/$env+dynamic+public.md (100%) rename {packages/kit/scripts => sites/kit.svelte.dev/scripts/types}/special-types/$env+static+private.md (100%) rename {packages/kit/scripts => sites/kit.svelte.dev/scripts/types}/special-types/$env+static+public.md (100%) rename {packages/kit/scripts => sites/kit.svelte.dev/scripts/types}/special-types/$lib.md (100%) delete mode 100644 sites/kit.svelte.dev/src/lib/docs/server/modules.js create mode 100644 sites/kit.svelte.dev/src/lib/docs/server/render.js diff --git a/.changeset/bright-pianos-flow.md b/.changeset/bright-pianos-flow.md new file mode 100644 index 000000000000..e804f42b3442 --- /dev/null +++ b/.changeset/bright-pianos-flow.md @@ -0,0 +1,5 @@ +--- +'create-svelte': patch +--- + +Update app.d.ts files diff --git a/.changeset/light-toes-rush.md b/.changeset/light-toes-rush.md new file mode 100644 index 000000000000..c908ad67c373 --- /dev/null +++ b/.changeset/light-toes-rush.md @@ -0,0 +1,5 @@ +--- +'@sveltejs/kit': patch +--- + +Add more type documentation diff --git a/.changeset/young-needles-attack.md b/.changeset/young-needles-attack.md new file mode 100644 index 000000000000..2b276242b7e3 --- /dev/null +++ b/.changeset/young-needles-attack.md @@ -0,0 +1,5 @@ +--- +'@sveltejs/kit': patch +--- + +[breaking] move SubmitFunction into @sveltejs/kit diff --git a/documentation/docs/20-core-concepts/20-load.md b/documentation/docs/20-core-concepts/20-load.md index 58a4b1685782..625a6b94040e 100644 --- a/documentation/docs/20-core-concepts/20-load.md +++ b/documentation/docs/20-core-concepts/20-load.md @@ -243,7 +243,7 @@ export async function load({ fetch, params }) { ### Cookies and headers -A server-only `load` function can get and set [`cookies`](/docs/types#sveltejs-kit-cookies). +A server-only `load` function can get and set [`cookies`](/docs/types#public-types-cookies). ```js /// file: src/routes/+layout.server.js @@ -544,7 +544,7 @@ To summarize, a `load` function will re-run in the following situations: - It references a property of `params` whose value has changed - It references a property of `url` (such as `url.pathname` or `url.search`) whose value has changed - It calls `await parent()` and a parent `load` function re-ran -- It declared a dependency on a specific URL via [`fetch`](#making-fetch-requests) or [`depends`](/docs/types#sveltejs-kit-loadevent), and that URL was marked invalid with [`invalidate(url)`](/docs/modules#$app-navigation-invalidate) +- It declared a dependency on a specific URL via [`fetch`](#making-fetch-requests) or [`depends`](/docs/types#public-types-loadevent), and that URL was marked invalid with [`invalidate(url)`](/docs/modules#$app-navigation-invalidate) - All active `load` functions were forcibly re-run with [`invalidateAll()`](/docs/modules#$app-navigation-invalidateall) Note that re-running a `load` function will update the `data` prop inside the corresponding `+layout.svelte` or `+page.svelte`; it does _not_ cause the component to be recreated. As a result, internal state is preserved. If this isn't what you want, you can reset whatever you need to reset inside an [`afterNavigate`](/docs/modules#$app-navigation-afternavigate) callback, and/or wrap your component in a [`{#key ...}`](https://svelte.dev/docs#template-syntax-key) block. diff --git a/documentation/docs/30-advanced/70-packaging.md b/documentation/docs/30-advanced/70-packaging.md index 2b61424f5081..b4507e3edcd8 100644 --- a/documentation/docs/30-advanced/70-packaging.md +++ b/documentation/docs/30-advanced/70-packaging.md @@ -10,13 +10,13 @@ When you're creating an app, the contents of `src/routes` is the public-facing s A component library has the exact same structure as a SvelteKit app, except that `src/lib` is the public-facing bit. `src/routes` might be a documentation or demo site that accompanies the library, or it might just be a sandbox you use during development. -Running the `svelte-package` command from `@sveltejs/package` will take the contents of `src/lib` and generate a `package` directory (which can be [configured](/docs/configuration#package)) containing the following: +Running the `svelte-package` command from `@sveltejs/package` will take the contents of `src/lib` and generate a `package` directory (which can be [configured](/docs/configuration)) containing the following: -- All the files in `src/lib`, unless you [configure](/docs/configuration#package) custom `include`/`exclude` options. Svelte components will be preprocessed, TypeScript files will be transpiled to JavaScript. -- Type definitions (`d.ts` files) which are generated for Svelte, JavaScript and TypeScript files. You need to install `typescript >= 4.0.0` for this. Type definitions are placed next to their implementation, hand-written `d.ts` files are copied over as is. You can [disable generation](/docs/configuration#package), but we strongly recommend against it. +- All the files in `src/lib`, unless you [configure](/docs/configuration) custom `include`/`exclude` options. Svelte components will be preprocessed, TypeScript files will be transpiled to JavaScript. +- Type definitions (`d.ts` files) which are generated for Svelte, JavaScript and TypeScript files. You need to install `typescript >= 4.0.0` for this. Type definitions are placed next to their implementation, hand-written `d.ts` files are copied over as is. You can [disable generation](/docs/configuration), but we strongly recommend against it. - A `package.json` copied from the project root with all fields except `"scripts"`, `"publishConfig.directory"` and `"publishConfig.linkDirectory"`. The `"dependencies"` field is included, which means you should add packages that you only need for your documentation or demo site to `"devDependencies"`. A `"type": "module"` and an `"exports"` field will be added if it's not defined in the original file. -The `"exports"` field contains the package's entry points. By default, all files in `src/lib` will be treated as an entry point unless they start with (or live in a directory that starts with) an underscore, but you can [configure](/docs/configuration#package) this behaviour. If you have a `src/lib/index.js` or `src/lib/index.svelte` file, it will be treated as the package root. +The `"exports"` field contains the package's entry points. By default, all files in `src/lib` will be treated as an entry point unless they start with (or live in a directory that starts with) an underscore, but you can [configure](/docs/configuration) this behaviour. If you have a `src/lib/index.js` or `src/lib/index.svelte` file, it will be treated as the package root. For example, if you had a `src/lib/Foo.svelte` component and a `src/lib/index.js` module that re-exported it, a consumer of your library could do either of the following: @@ -54,7 +54,7 @@ To publish the generated package: npm publish ./package ``` -The `./package` above is referring to the directory name generated, change accordingly if you configure a custom [`package.dir`](/docs/configuration#package). +The `./package` above is referring to the directory name generated, change accordingly if you configure a custom [`package.dir`](/docs/configuration). ### Caveats diff --git a/documentation/docs/50-api-reference/10-configuration.md b/documentation/docs/50-api-reference/10-configuration.md deleted file mode 100644 index ea2f80eefe11..000000000000 --- a/documentation/docs/50-api-reference/10-configuration.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -title: Configuration ---- - -Your project's configuration lives in a `svelte.config.js` file. All values are optional. The complete list of options, with defaults, is shown here: - -```js -/// file: svelte.config.js -/** @type {import('@sveltejs/kit').Config} */ -const config = { - // options passed to svelte.compile (https://svelte.dev/docs#compile-time-svelte-compile) - compilerOptions: {}, - - // an array of file extensions that should be treated as Svelte components - extensions: ['.svelte'], - - kit: { - adapter: undefined, - alias: {}, - appDir: '_app', - csp: { - mode: 'auto', - directives: { - 'default-src': undefined - // ... - } - }, - csrf: { - checkOrigin: true - }, - env: { - dir: process.cwd(), - publicPrefix: 'PUBLIC_' - }, - files: { - assets: 'static', - hooks: { - client: 'src/hooks.client', - server: 'src/hooks.server' - }, - lib: 'src/lib', - params: 'src/params', - routes: 'src/routes', - serviceWorker: 'src/service-worker', - appTemplate: 'src/app.html', - errorTemplate: 'src/error.html' - }, - inlineStyleThreshold: 0, - moduleExtensions: ['.js', '.ts'], - outDir: '.svelte-kit', - paths: { - assets: '', - base: '' - }, - prerender: { - concurrency: 1, - crawl: true, - entries: ['*'], - handleHttpError: 'fail', - handleMissingId: 'fail', - origin: 'http://sveltekit-prerender' - }, - serviceWorker: { - register: true, - files: (filepath) => !/\.DS_Store/.test(filepath) - }, - version: { - name: Date.now().toString(), - pollInterval: 0 - } - }, - - // options passed to @sveltejs/package - package: { - source: 'value of kit.files.lib, if available, else src/lib', - dir: 'package', - emitTypes: true, - // excludes all .d.ts and files starting with _ as the name - exports: (filepath) => !/^_|\/_|\.d\.ts$/.test(filepath), - files: () => true - }, - - // options passed to svelte.preprocess (https://svelte.dev/docs#compile-time-svelte-preprocess) - preprocess: null -}; - -export default config; -``` - -### adapter - -Run when executing `vite build` and determines how the output is converted for different platforms. See [Adapters](/docs/adapters). - -### alias - -An object containing zero or more aliases used to replace values in `import` statements. These aliases are automatically passed to Vite and TypeScript. - -```js -/// file: svelte.config.js -/** @type {import('@sveltejs/kit').Config} */ -const config = { - kit: { - alias: { - // this will match a file - 'my-file': 'path/to/my-file.js', - - // this will match a directory and its contents - // (`my-directory/x` resolves to `path/to/my-directory/x`) - 'my-directory': 'path/to/my-directory', - - // an alias ending /* will only match - // the contents of a directory, not the directory itself - 'my-directory/*': 'path/to/my-directory/*' - } - } -}; -``` - -> The built-in `$lib` alias is controlled by `config.kit.files.lib` as it is used for packaging. - -> You will need to run `npm run dev` to have SvelteKit automatically generate the required alias configuration in `jsconfig.json` or `tsconfig.json`. - -### appDir - -The directory relative to `paths.assets` where the built JS and CSS (and imported assets) are served from. (The filenames therein contain content-based hashes, meaning they can be cached indefinitely). Must not start or end with `/`. - -### csp - -An object containing zero or more of the following values: - -- `mode` — 'hash', 'nonce' or 'auto' -- `directives` — an object of `[directive]: value[]` pairs -- `reportOnly` — an object of `[directive]: value[]` pairs for CSP report-only mode - -[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) configuration. CSP helps to protect your users against cross-site scripting (XSS) attacks, by limiting the places resources can be loaded from. For example, a configuration like this... - -```js -/// file: svelte.config.js -/** @type {import('@sveltejs/kit').Config} */ -const config = { - kit: { - csp: { - directives: { - 'script-src': ['self'] - }, - reportOnly: { - 'script-src': ['self'] - } - } - } -}; - -export default config; -``` - -...would prevent scripts loading from external sites. SvelteKit will augment the specified directives with nonces or hashes (depending on `mode`) for any inline styles and scripts it generates. - -To add a nonce for scripts and links manually included in `app.html`, you may use the placeholder `%sveltekit.nonce%` (for example `