Development
The following method is to improve the Gem development experience.
Language Support
Install extension:
Formatting
Prettier
prettier defaults to support the inline html/css template, but does not supportcss({}), use the following command to install prettier
To support the formatting of this style:
pnpm add -D prettier@npm:@mantou/prettierBiome
biome v2 defaults to support the inline html/css template, but does not supportcss({}).
HMR
HMR is available through
unplugin-gem (recommended)
Turn on hot in the bundler when it has a JS HMR host, then enable hmr. The plugin injects @mantou/gem/helper/hmr automatically:
unpluginGem({
hmr: true,
});Complete JavaScript HMR still needs a host that implements import.meta.webpackHot (webpack/Rspack) or import.meta.hot (Vite / experimental Rolldown). Rollup and esbuild only get the runtime so class updates stay compatible.
SWC plugin
When using
- Turn on
hotin the build tool, such as Webpack - Add
@mantou/gem/helper/hmrto the bundler entry (it must run before any element class is defined) - Enable
hmrin the SWC plugin config (true/"webpack-hot","import-meta-hot", or"module-hot")
What HMR covers
Hot updated correctly:
- Bodies of methods, getters/setters and arrow function fields (including private and static members), such as templates,
@effectand@memocontents and their dependencies, and the constructor body (applies to elements created afterwards) - Adding or removing undecorated methods, getters/setters and arrow function fields (including private and static members)
- Adding or removing
@attribute,@property,@emitter,@state,@partand@slotfields - Styles (
@adoptedStyle,css), including Light DOM - Top-level constants and functions of the module
- State is kept: element instance fields and
createState, and stores created by top-levelcreateStore - Creating elements with
new MyElement()in updated code
Reloads the page:
- Adding or removing decorated methods or function fields (such as
@effectand@template), or the constructor - Adding or removing plain instance fields without decorators
- Changing
@shadow,@light({ penetrable })or@async - Adding or removing stores in
@connectStore, or connecting a local store that is not created by top-levelcreateStore - A constructor with
super(args),new.target, TS parameter properties, orreturnwith a value
Hot updated, but not guaranteed to be reliable:
- Apart from
@effectand@memodependencies, changed decorator arguments are not applied, such as@templateconditions and@aria - Changed field initial values and store initial values are not applied, because they are kept as state
- Other mutable top-level variables of the module (such as
letvariables or cacheMaps) are reset when the module updates - Changed static field values only apply when read through the class name inside the module; reading through
this.constructororcustomElements.get()still returns the old value - Members with computed names are not hot updated
- Top-level side effects of the module run again, such as event listeners, timers and
renderin the entry - DOM rendered by a changed template literal (
html) is recreated, so input focus, child element state and similar state inside it are lost; unchanged templates reuse the existing DOM - When a base class updates, new fields are only added to instances of the tag being updated
- Modules without element definitions (utilities, store modules) hand the update to the modules that import them; other modules outside that update chain keep the old version
