Skip to content

Commit 8ffd865

Browse files
bluwybluwy
authored
docs: Better documentation (#151)
* docs(config): add configuration docs * docs(options): match jsdoc to config docs * fix(options): make compilerOptions optional * docs(config): link to vite root * docs(faq): ask me anything * docs(config): fix link * docs: update readme * docs(faq): add info on cjs error
1 parent a6236dc commit 8ffd865

File tree

6 files changed

+396
-183
lines changed

6 files changed

+396
-183
lines changed

‎README.md

Lines changed: 41 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,57 @@
1-
# vite-plugin-svelte
1+
# @sveltejs/vite-plugin-svelte
22

3-
This is the official [svelte](https://svelte.dev) plugin for [vite](https://vitejs.dev)
3+
The official [Svelte](https://svelte.dev) plugin for [Vite](https://vitejs.dev).
4+
5+
## Installation
6+
7+
```bash
8+
npm install --save-dev @sveltejs/vite-plugin-svelte
9+
```
10+
11+
## Usage
12+
13+
```js
14+
// vite.config.js
15+
import { svelte } from '@sveltejs/vite-plugin-svelte';
16+
17+
export default defineConfig({
18+
plugins: [
19+
svelte({
20+
/* plugin options */
21+
})
22+
]
23+
});
24+
```
25+
26+
## Documentation
27+
28+
- [Plugin options](./docs/config.md)
29+
- [FAQ](./docs/faq.md)
430

531
## Packages
632

733
| Package | changelog |
834
| ----------------------------------------------------------- | ----------------------------------------------------- |
935
| [@sveltejs/vite-plugin-svelte](packages/vite-plugin-svelte) | [changelog](packages/vite-plugin-svelte/CHANGELOG.md) |
1036

11-
# Got a question? / Need help?
12-
13-
Join [svelte discord](https://svelte.dev/chat)
14-
15-
## Development of vite-plugin-svelte
37+
## Got a question? / Need help?
1638

17-
### dev
39+
Join the [Svelte Discord server](https://svelte.dev/chat)!
1840

19-
- run `pnpm i`to install
20-
- run `pnpm dev` in `packages/vite-plugin-svelte` to autobuild plugin
21-
- run `pnpm dev` in `packages/playground/xxx` to start vite
41+
## Development
2242

23-
changes in plugin need restart of dev server
43+
- Run `pnpm i` to install dependencies
44+
- Run `pnpm dev` in `packages/vite-plugin-svelte` to autobuild plugin
45+
- Run `pnpm dev` in `packages/playground/xxx` to start a Vite app
2446

25-
### some notes
47+
Note that changes in the plugin needs restart of the Vite dev server.
2648

27-
- For typescript, svelte components must use `<script lang="ts">`, not `<script lang="typescript">` otherwise vite dep scan fails. see https://discord.com/channels/804011606160703521/804062134051930222/806300072349270033
28-
- exclusions in optimizeDeps also cover children (x or startswith x+/)
29-
- svelte components should be sorted with style nodes last as js code may contain markup node positions
49+
## Credits
3050

31-
# Credits
32-
33-
- [svelte](https://svelte.dev) and [vite](https://github.com/vitejs/vite#readme) creators, maintainers and contributors
51+
- [Svelte](https://svelte.dev) and [Vite](https://github.com/vitejs/vite#readme) creators, maintainers and contributors
3452
- [rixo](https://github.com/rixo) - without svelte-hmr and your support this would not have been possible
3553
- [intrnl](https://github.com/intrnl) - initial inspiration from https://github.com/intrnl/vite-plugin-svelte
54+
55+
## License
56+
57+
[MIT](./LICENSE)

‎docs/README.md

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎docs/config.md

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# Configuration
2+
3+
`vite-plugin-svelte` accepts inline options that can be used to change its behaviour. An object can be passed to the first argument of the `svelte` plugin:
4+
5+
```js
6+
export default defineConfig({
7+
plugins: [
8+
svelte({
9+
/* plugin options */
10+
})
11+
]
12+
});
13+
```
14+
15+
Explore the various options below!
16+
17+
## Config file
18+
19+
### Config file resolving
20+
21+
Besides inline options, `vite-plugin-svelte` will also automatically resolve options from a Svelte config file if one exists. The default search paths are:
22+
23+
- `svelte.config.js`
24+
- `svelte.config.mjs`
25+
- `svelte.config.cjs`
26+
27+
To set a specific config file, use the `configFile` inline option. The path can be absolute or relative to the [Vite root](https://vitejs.dev/config/#root). For example:
28+
29+
```js
30+
export default defineConfig({
31+
plugins: [
32+
svelte({
33+
configFile: 'my-svelte.config.js'
34+
})
35+
]
36+
});
37+
```
38+
39+
A basic Svelte config looks like this:
40+
41+
```js
42+
// svelte.config.js
43+
export default {
44+
// config options
45+
};
46+
```
47+
48+
### Config file extension
49+
50+
Depending on Node's mode, make sure you're using the correct extension and syntax so it can be resolved safely.
51+
52+
- If `type: "module"` is defined in `package.json`, using `.js` only allows ESM code. Use `.cjs` to allow CJS code.
53+
- If `type: "module"` is not defined, using `.js` only allows CJS code. Use `.mjs` to allows ESM code.
54+
55+
> Try to stick with the `.js` extension whenever possible.
56+
57+
## Svelte options
58+
59+
These options are specific to the Svelte compiler and are generally shared across many bundler integrations.
60+
61+
<!-- TODO: Also note where these options can be placed in svelte.config.js -->
62+
63+
### compilerOptions
64+
65+
- **Type:** `CompileOptions` - See [svelte.compile](https://svelte.dev/docs#svelte_compile)
66+
67+
The options to be passed to the Svelte compiler. A few options are set by default, including `dev`, `format` and `css`. However, some options are non-configurable, like `filename`, `generate`, and `cssHash`.
68+
69+
### preprocess
70+
71+
- **Type:** `PreprocessorGroup | PreprocessorGroup[]` - See [svelte.preprocess](https://svelte.dev/docs#svelte_preprocess)
72+
73+
An array of preprocessors to transform the Svelte source code before compilation.
74+
75+
**Example:**
76+
77+
```js
78+
import sveltePreprocess from 'svelte-preprocess';
79+
80+
export default defineConfig({
81+
plugins: [
82+
svelte({
83+
preprocess: [sveltePreprocess({ typescript: true })]
84+
})
85+
]
86+
});
87+
```
88+
89+
## Plugin options
90+
91+
These options are specific to the Vite plugin itself.
92+
93+
### include
94+
95+
- **Type:** `string | string[]`
96+
97+
A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files the plugin should operate on. By default, all svelte files are included.
98+
99+
### exclude
100+
101+
- **Type:** `string | string[]`
102+
103+
A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files to be ignored by the plugin. By default, no files are ignored.
104+
105+
### extensions
106+
107+
- **Type:** `string[]`
108+
- **Default:** `['.svelte']`
109+
110+
A list of file extensions to be compiled by Svelte. Useful for custom extensions like `.svg` and `.svx`.
111+
112+
### emitCss
113+
114+
- **Type:** `boolean`
115+
- **Default:** `true`
116+
117+
Emit Svelte styles as virtual CSS files for Vite and other plugins to process.
118+
119+
### onwarn
120+
121+
- **Type:**: `(warning: Warning, defaultHandler?: (warning: Warning) => void) => void` - See [Warning](https://github.com/sveltejs/svelte/blob/ce550adef65a7e04c381b11c24f07a2ae1c25783/src/compiler/interfaces.ts#L121-L130)
122+
123+
Handles warning emitted from the Svelte compiler. Useful to suppress warning messages.
124+
125+
**Example:**
126+
127+
```js
128+
export default defineConfig({
129+
plugins: [
130+
svelte({
131+
onwarn(warning, defaultHandler) {
132+
// don't warn on <marquee> elements, cos they're cool
133+
if (warning.code === 'a11y-distracting-elements') return;
134+
135+
// handle all other warnings normally
136+
defaultHandler(warning);
137+
}
138+
})
139+
]
140+
});
141+
```
142+
143+
### hot
144+
145+
- **Type:** `boolean | SvelteHotOptions` - See [svelte-hmr](https://github.com/sveltejs/svelte-hmr#options)
146+
- **Default:** `true` for development, always `false` for production
147+
148+
Enable or disable Hot Module Replacement ([HMR](https://github.com/sveltejs/svelte-hmr#whats-hmr-by-the-way)).
149+
150+
> Do not customize the options unless you know exactly what you are doing.
151+
152+
### ignorePluginPreprocessors
153+
154+
- **Type:** `boolean | string[]`
155+
- **Default:** `false`
156+
157+
Some Vite plugins can contribute additional preprocessors by defining [api.sveltePreprocess](./faq.md#how-do-i-add-a-svelte-preprocessor-from-a-vite-plugin). If you don't want to use them, set this to true to ignore them all or use an array of strings with plugin names to specify which.
158+
159+
## Experimental options
160+
161+
These options are considered experimental and breaking changes to them can occur in any release! Specify them under the `experimental` option.
162+
163+
```js
164+
export default defineConfig({
165+
plugins: [
166+
svelte({
167+
experimental: {
168+
// experimental options
169+
}
170+
})
171+
]
172+
});
173+
```
174+
175+
### useVitePreprocess
176+
177+
- **Type:** `boolean`
178+
- **Default:** `false`
179+
180+
Use extra preprocessors that delegate style and TypeScript preprocessing to native Vite plugins. Do not use together with `svelte-preprocess`!
181+
182+
> Caveat: For TypeScript preprocessing to work, `esbuild.tsconfigRaw.compilerOptions.importsNotUsedAsValues` will be set to `preserve` to safely transpile TypeScript. This requires the entire codebase's Typescript code to only use `import type` when importing types, otherwise the codebase would break.
183+
184+
### generateMissingPreprocessorSourcemaps
185+
186+
- **Type:** `boolean`
187+
- **Default:** `false`
188+
189+
If a preprocessor does not provide a sourcemap, a best-effort fallback sourcemap will be provided. This option requires [diff-match-patch](https://github.com/google/diff-match-patch) to be installed as a peer dependency.
190+
191+
### dynamicCompileOptions
192+
193+
- **Type:**
194+
195+
```ts
196+
type DynamicCompileOptions = (data: {
197+
filename: string; // The file to be compiled
198+
code: string; // The preprocessed Svelte code
199+
compileOptions: Partial<CompileOptions>; // The current compiler options
200+
}) => Promise<Partial<CompileOptions> | void> | Partial<CompileOptions> | void;
201+
```
202+
203+
A function to update the `compilerOptions` before compilation. To change part of the compiler options, return an object with the changes you need.
204+
205+
**Example:**
206+
207+
```js
208+
export default defineConfig({
209+
plugins: [
210+
svelte({
211+
experimental: {
212+
dynamicCompileOptions({ filename, compileOptions }) {
213+
// Dynamically set hydration per Svelte file
214+
if (compileWithHydratable(filename) && !compileOptions.hydratable) {
215+
return { hydratable: true };
216+
}
217+
}
218+
}
219+
})
220+
]
221+
});
222+
```

‎docs/faq.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Frequently Asked Questions
2+
3+
### Why is component state reset on HMR update?
4+
5+
Preservation of local component state after JS updates is disabled to avoid unpredictable and error-prone behavior. You can read more about it [here](https://github.com/rixo/svelte-hmr#preservation-of-local-state).
6+
7+
Please note that if you only edit the `<style>` node, a separate CSS update can be applied where component state is 100% preserved.
8+
9+
### What is the recommended node order for Svelte SFC files?
10+
11+
The `<style>` node should be last to ensure optimal HMR results. This is also the default order with [prettier-plugin-svelte](https://github.com/sveltejs/prettier-plugin-svelte).
12+
13+
Good:
14+
15+
```html
16+
<script></script>
17+
<div></div>
18+
<style></style>
19+
```
20+
21+
Bad:
22+
23+
```html
24+
<script></script>
25+
<style></style>
26+
<!-- this template element is below the style node and may cause extra HMR updates -->
27+
<div></div>
28+
```
29+
30+
### Why isn't Vite detecting my imports correctly in `.svelte` files with TypeScript?
31+
32+
You have to use the `lang="ts"` attribute for Vite to parse it. Never `lang="typescript"` or `type="text/typescript"`.
33+
34+
Good:
35+
36+
```html
37+
<script lang="ts"></script>
38+
```
39+
40+
Bad:
41+
42+
```html
43+
<!-- These are not detected by Vite -->
44+
<script lang="typescript"></script>
45+
<script type="text/typescript"></script>
46+
```
47+
48+
### How do I add a Svelte preprocessor from a Vite plugin?
49+
50+
If you are building a Vite plugin that transforms CSS or JS, you can add a `api.sveltePreprocess: PreprocessorGroup` to your Vite plugin definition and it will be added to the list of Svelte preprocessors used at runtime.
51+
52+
```js
53+
const vitePluginCoolCss = {
54+
name: 'vite-plugin-coolcss',
55+
api: {
56+
sveltePreprocess: {
57+
/* your PreprocessorGroup here */
58+
}
59+
}
60+
/*... your cool css plugin implementation here .. */
61+
};
62+
```
63+
64+
For reference, check out [windicss](https://github.com/windicss/vite-plugin-windicss/blob/517eca0cebc879d931c6578a08accadfb112157c/packages/vite-plugin-windicss/src/index.ts#L167).
65+
66+
### What is `The requested module 'xxx' does not provide an export named 'yyy'`?
67+
68+
This usually happens when a dependency (e.g. `xxx`) only exports CJS code, but is not optimized by Vite. It's also a common issue among many Svelte libraries because they are [excluded from optimization by default](https://github.com/vitejs/vite/issues/3910#issuecomment-897006012) by `vite-plugin-svelte`.
69+
70+
A pending [Vite pull request](https://github.com/vitejs/vite/pull/4634) would help solve this issue soon, but until then, try contacting the `xxx` library authors to also export ESM code.

0 commit comments

Comments
 (0)