{"id":16913,"library":"svelte-hmr","title":"Svelte HMR Core Utilities","description":"svelte-hmr provides the core logic and utilities for implementing Hot Module Replacement (HMR) in Svelte 3 and 4 applications. It is not an end-user bundler plugin itself, but rather a foundational package leveraged by bundler-specific plugins (e.g., for Rollup, Webpack, Vite) to enable seamless development experiences. The package is currently stable at version `0.16.0` and receives updates as Svelte itself evolves or HMR patterns improve, typically releasing patch and minor versions on an as-needed basis rather than a strict schedule. Key differentiators include its bundler-agnostic design, robust state preservation mechanisms (both component and local variable state), and intelligent CSS injection capabilities, offering a consistent HMR experience across different build tools without needing full page reloads.","status":"active","version":"0.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/sveltejs/svelte-hmr","tags":["javascript"],"install":[{"cmd":"npm install svelte-hmr","lang":"bash","label":"npm"},{"cmd":"yarn add svelte-hmr","lang":"bash","label":"yarn"},{"cmd":"pnpm add svelte-hmr","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required at runtime for Svelte component compilation and hydration.","package":"svelte","optional":false}],"imports":[{"note":"Primarily used by bundler plugin authors to initialize the HMR runtime. Not for direct use in application code.","symbol":"init","correct":"import { init } from 'svelte-hmr';"},{"note":"A utility function for bundler plugins to normalize and resolve HMR configuration options passed by the user.","symbol":"resolveOptions","correct":"import { resolveOptions } from 'svelte-hmr/options';"},{"note":"Used by bundler plugins to apply HMR updates to Svelte modules, handling component re-rendering and state preservation.","symbol":"hotUpdate","correct":"import { hotUpdate } from 'svelte-hmr/loader';"}],"quickstart":{"code":"<!-- src/App.svelte -->\n<script lang=\"ts\">\n  // @hmr:keep-all\n  // This comment directly influences svelte-hmr's state preservation logic.\n  let count: number = 0;\n  let textInput: string = 'Edit me!';\n  let showDetails: boolean = false;\n\n  function increment() {\n    count += 1;\n  }\n\n  function toggleDetails() {\n    showDetails = !showDetails;\n  }\n</script>\n\n<style>\n  div { padding: 1rem; border: 1px solid #eee; margin-bottom: 1rem; background-color: #f9f9f9; }\n  h1 { color: #333; }\n  button {\n    background-color: #4CAF50;\n    color: white;\n    padding: 10px 15px;\n    border: none;\n    border-radius: 5px;\n    cursor: pointer;\n    margin-right: 10px;\n  }\n  input { padding: 8px; border: 1px solid #ccc; border-radius: 4px; }\n</style>\n\n<div>\n  <h1>HMR Demo Count: {count}</h1>\n  <p>Input text: <input type=\"text\" bind:value={textInput} /></p>\n  <button on:click={increment}>Increment Count</button>\n  <button on:click={toggleDetails}>Toggle Details</button>\n\n  {#if showDetails}\n    <p>Details are visible!</p>\n    <p>Current input value will persist: \"{textInput}\"</p>\n  {:else}\n    <p>Details are hidden.</p>\n  {/if}\n\n  <p>\n    Modify this Svelte component (e.g., change text, add a new element) and save.\n    With a compatible HMR bundler setup (e.g., Vite with <code>@sveltejs/vite-plugin-svelte</code>),\n    <code>svelte-hmr</code> will update the component in place, preserving <code>count</code>,\n    <code>textInput</code>, and <code>showDetails</code> due to the <code>@hmr:keep-all</code> directive.\n  </p>\n</div>\n","lang":"typescript","description":"This Svelte component demonstrates state preservation using `@hmr:keep-all` comments, a feature provided by `svelte-hmr` and enabled via a bundler plugin for a seamless HMR development experience."},"warnings":[{"fix":"Migrate from `noPreserveState` to `preserveLocalState` in your bundler plugin's HMR options, or use `@hmr:reset` in your Svelte components if you explicitly want to disable state preservation.","message":"The `noPreserveState` option was removed in version 0.12. Users should now use the `preserveLocalState` option or `preserveAllLocalStateKey` / `preserveLocalStateKey` directives for state preservation.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"If you relied on the previous behavior of attempting to render the next component version after a crash, explicitly set `optimistic: true` in your bundler plugin's HMR options (e.g., `hmrOptions: { optimistic: true }`). Otherwise, ensure your code handles runtime errors gracefully.","message":"The default value for the `optimistic` option changed from `true` to `false` in version 0.14.12. This means that runtime errors during component initialization are now considered fatal to HMR by default, potentially triggering a full browser reload.","severity":"breaking","affected_versions":">=0.14.12"},{"fix":"Instead of direct imports, configure HMR through your chosen bundler's Svelte plugin. Refer to your bundler plugin's documentation for enabling and configuring Svelte HMR.","message":"`svelte-hmr` is an internal utility for bundler plugins, not an end-user package. It should not be directly imported or used in application code. Its functionalities are exposed through bundler-specific HMR plugins (e.g., `@sveltejs/vite-plugin-svelte`, `rollup-plugin-hot`).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure HMR directives are placed at the beginning of the `<script>` tag (e.g., `// @hmr:keep-all`) or as the first line in your component's markup (e.g., `<!-- @hmr:keep-all -->`). Check the `svelte-hmr` documentation or your bundler plugin's guide for exact placement rules.","message":"HMR comments like `@hmr:keep-all` must be correctly placed to be effective. They typically need to be at the top level of a `<script>` block or as the very first line of a component's markup.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade `svelte-hmr` to `0.15.2` or higher to ensure compatibility and correct functioning with Svelte 4 applications.","message":"Svelte 4 support was officially added in `svelte-hmr@0.15.2`. Older versions may have incompatible peer dependencies or exhibit incorrect behavior when used with Svelte 4 projects.","severity":"breaking","affected_versions":"<0.15.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"`svelte-hmr` is an underlying dependency for bundler plugins that enable HMR for Svelte. Its features are controlled via your bundler plugin's configuration (e.g., `svelte({ hot: true })` in Vite) or specific HMR comments within Svelte components. Direct imports are generally not required for application developers.","cause":"Attempting to import `svelte-hmr` directly into application source code.","error":"Cannot find module 'svelte-hmr' or its corresponding type declarations."},{"fix":"Ensure your bundler's Svelte plugin has HMR explicitly enabled (e.g., `hot: true` or similar option). Check the browser console for JavaScript runtime errors that might cause `svelte-hmr` to trigger a full reload. Consider setting `hmrOptions: { optimistic: true }` in your bundler plugin config to allow `svelte-hmr` to attempt recovery from some errors, though this might mask underlying issues.","cause":"HMR is not correctly enabled in the bundler plugin, or a fatal runtime error is preventing `svelte-hmr` from applying updates.","error":"HMR is not working: Full page reloads instead of hot updates on component changes."},{"fix":"Enable `preserveLocalState: true` in your bundler plugin's HMR options (e.g., `hmrOptions: { preserveLocalState: true }`). Alternatively, use HMR directives within your Svelte components like `<!-- @hmr:keep-all -->` at the top of the component file, or `let myVar = 0; // @hmr:keep` for specific variables.","cause":"State preservation is not enabled either globally via bundler options or specifically for the component/variable.","error":"Local state (e.g., component `let` variables) is not preserved across HMR updates in my Svelte components."}],"ecosystem":"npm","meta_description":null}