Skip to content

Commit 27475f3

Browse files
rixorixo
committed
readme
1 parent a161a2d commit 27475f3

File tree

1 file changed

+38
-108
lines changed

1 file changed

+38
-108
lines changed

‎README.md‎

Lines changed: 38 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,54 @@
11
# rollup-plugin-svelte-hot
22

3-
This is a fork of [rollup-plugin-svelte](https://github.com/rollup/rollup-plugin-svelte) that integrates [rollup-plugin-svelte-hmr](https://github.com/rixo/rollup-plugin-svelte-hmr) to compile Svelte components and provide support for HMR over [Nollup](https://github.com/PepsRyuu/nollup).
3+
This is a fork of official [rollup-plugin-svelte](https://github.com/rollup/rollup-plugin-svelte) with added support for HMR.
44

5-
- `rollup-plugin-svelte` only compiles Svelte components
5+
It supports HMR both with [Nollup](https://github.com/PepsRyuu/nollup) or [Rollup](https://github.com/rollup/rollup) with (experimental) [rollup-plugin-hot](https://github.com/rixo/rollup-plugin-hot).
66

7-
- `rollup-plugin-svelte-hmr` only adds HMR support for Svelte components
7+
HMR is not officially supported by Svelte 3 yet. Progress can be tracked in [this issue](https://github.com/sveltejs/svelte/issues/3632).
88

9-
- `rollup-plugin-svelte-hot` (this plugin) combines both functionality
9+
Meanwhile, please report your issues regarding HMR (with Rollup / Nollup) in this project's [issue tracker](https://github.com/rixo/rollup-plugin-svelte-hot/issues). By the way, now is a very good time to share your bright ideas & suggestions about Svelte HMR, since this is all very much a work in progress. Mere feed is welcome, too.
1010

11-
The main reason why this plugin exists is to add support to preserve local component state over HMR updates. Svelte makes it possible (even easy), but the HMR-only plugin can't currently leverage it because it requires a change in Svelte dev API. This plugin is able to workaround this limitation because it has access to Svelte [compiler's output](https://svelte.dev/docs#svelte_compile) (that contains useful metadata about components).
11+
## Templates
1212

13-
This plugin can be used as a drop-in replacement for `rollup-plugin-svelte`. It adds one additional option to enable HMR: `hot`.
13+
To quickly bootstrap a new project, or for example purpose, you can use the following templates. They are copies of official templates, with the bare minimum added to support HMR with this plugin.
1414

15-
## Quick start / Template
15+
- [svelte-template-hot](https://github.com/rixo/svelte-template-hot): hot version of the official Svelte template for Rollup.
1616

17-
Use [svelte-template-hot](https://github.com/rixo/svelte-template-hot) to quickly bootstrap a new project, or as a reference to add this to your project (more detailed instructions to come).
17+
- [sapper-template-hot](https://github.com/rixo/sapper-template-hot/tree/rollup): the `rollup` branch of this template uses this plugin to do Sapper + Rollup + HMR. This one is still very (very) much a work in progress.
1818

1919
## Installation
2020

2121
```bash
22-
npm install --save-dev svelte rollup-plugin-svelte-hot
22+
npm install --save-dev rollup-plugin-svelte-hot
2323
```
2424

25-
Note that we need to install Svelte as well as the plugin, as it's a 'peer dependency'.
26-
27-
You'll also need Nollup, Rollup, etc...
28-
29-
3025
## Usage
3126

27+
This plugin can be used as a drop-in replacement for `rollup-plugin-svelte`. It adds just one additional config option to enable HMR: `hot`. It aims to remain as close to the official plugin as possible. Please refer to official docs for general usage of the plugin. For HMR specific stuff, see bellow.
28+
3229
```js
3330
// rollup.config.js
34-
import * as fs from 'fs';
3531
import svelte from 'rollup-plugin-svelte-hot';
3632

33+
...
34+
35+
const hot = !production && !!watch
36+
3737
export default {
3838
input: 'src/main.js',
3939
output: {
4040
file: 'public/bundle.js',
41+
// format will be overridden to 'system' when using Rollup + HMR
4142
format: 'iife'
4243
},
4344
plugins: [
4445
svelte({
45-
// Use `hot: true` to use default options (as follow)
46-
hot: {
46+
// Use `hot: true` to use default options (as follow).
47+
//
48+
// Set `hot: false` to disable HMR shenanigans (you need this for
49+
// `npm run build`, for example).
50+
//
51+
hot: hot && {
4752
// Prevent preserving local component state
4853
noPreserveState: false,
4954
// Prevent doing a full reload on next HMR update after fatal error
@@ -52,98 +57,23 @@ export default {
5257
optimistic: false
5358
},
5459

55-
// By default, all .svelte and .html files are compiled
56-
extensions: ['.my-custom-extension'],
57-
58-
// You can restrict which files are compiled
59-
// using `include` and `exclude`
60-
include: 'src/components/**/*.svelte',
61-
62-
// By default, the client-side compiler is used. You
63-
// can also use the server-side rendering compiler
64-
generate: 'ssr',
65-
66-
// Optionally, preprocess components with svelte.preprocess:
67-
// https://svelte.dev/docs#svelte_preprocess
68-
preprocess: {
69-
style: ({ content }) => {
70-
return transformStyles(content);
71-
}
72-
},
73-
74-
// Emit CSS as "files" for other plugins to process
75-
emitCss: true,
76-
77-
// Extract CSS into a separate file (recommended).
78-
// See note below
79-
css: function (css) {
80-
console.log(css.code); // the concatenated CSS
81-
console.log(css.map); // a sourcemap
82-
83-
// creates `main.css` and `main.css.map` — pass `false`
84-
// as the second argument if you don't want the sourcemap
85-
css.write('public/main.css');
86-
},
87-
88-
// Warnings are normally passed straight to Rollup. You can
89-
// optionally handle them here, for example to squelch
90-
// warnings with a particular code
91-
onwarn: (warning, handler) => {
92-
// e.g. don't warn on <marquee> elements, cos they're cool
93-
if (warning.code === 'a11y-distracting-elements') return;
94-
95-
// let Rollup handle all other warnings normally
96-
handler(warning);
97-
}
60+
// `dev: true` is required with HMR
61+
dev: hot,
62+
63+
// Separate CSS file is not supported during hMR (neither with Nollup
64+
// nor rollup-plugin-hot), so we just disable it when `hot` is true.
65+
...(!hot && {
66+
css: css => {
67+
css.write('public/bundle.css')
68+
},
69+
}),
70+
71+
// See official rollup-plugin-svelte docs for all available options:
72+
//
73+
// https://github.com/rollup/rollup-plugin-svelte
74+
//
75+
...
9876
})
9977
]
10078
}
10179
```
102-
103-
104-
## Preprocessing and dependencies
105-
106-
If you are using the `preprocess` feature, then your callback responses may — in addition to the `code` and `map` values described in the Svelte compile docs — also optionally include a `dependencies` array. This should be the paths of additional files that the preprocessor result in some way depends upon. In Rollup 0.61+ in watch mode, any changes to these additional files will also trigger re-builds.
107-
108-
109-
## `pkg.svelte`
110-
111-
If you're importing a component from your node_modules folder, and that component's package.json has a `"svelte"` property...
112-
113-
```js
114-
{
115-
"name": "some-component",
116-
117-
// this means 'some-component' resolves to 'some-component/src/SomeComponent.svelte'
118-
"svelte": "src/MyComponent.svelte"
119-
}
120-
```
121-
122-
...then this plugin will ensure that your app imports the *uncompiled* component source code. That will result in a smaller, faster app (because code is deduplicated, and shared functions get optimized quicker), and makes it less likely that you'll run into bugs caused by your app using a different version of Svelte to the component.
123-
124-
Conversely, if you're *publishing* a component to npm, you should ship the uncompiled source (together with the compiled distributable, for people who aren't using Svelte elsewhere in their app) and include the `"svelte"` property in your package.json.
125-
126-
If you are publishing a package containing multiple components, you can create an `index.js` file that re-exports all the components, like this:
127-
128-
```js
129-
export { default as Component1 } from './Component1.svelte';
130-
export { default as Component2 } from './Component2.svelte';
131-
```
132-
133-
and so on. Then, in `package.json`, set the `svelte` property to point to this `index.js` file.
134-
135-
136-
## Extracting CSS
137-
138-
If your Svelte components contain `<style>` tags, by default the compiler will add JavaScript that injects those styles into the page when the component is rendered. That's not ideal, because it adds weight to your JavaScript, prevents styles from being fetched in parallel with your code, and can even cause CSP violations.
139-
140-
A better option is to extract the CSS into a separate file. Using the `css` option as shown above would cause a `public/main.css` file to be generated each time the bundle is built (or rebuilt, if you're using rollup-watch), with the normal scoping rules applied.
141-
142-
If you have other plugins processing your CSS (e.g. rollup-plugin-scss), and want your styles passed through to them to be bundled together, you can use `emitCss: true`.
143-
144-
Alternatively, if you're handling styles in some other way and just want to prevent the CSS being added to your JavaScript bundle, use `css: false`.
145-
146-
147-
## License
148-
149-
MIT

0 commit comments

Comments
 (0)