npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@tobloef/hot-reload

v1.2.5

Published

Hot-reloading utilities

Downloads

479

Readme

Hot Reload 🔥

Utilities for hot reloading (what is hot reloading?) JavaScript modules and other assets on the web.

See this in action in my build tool.

[!WARNING] This project was created primarily for personal use. For this reason, it is not fully documented and I would not recommend using it. That said, I hope it can at least be inspirational for your own projects.

Installation

npm install --save @tobloef/hot-reload

Usage

Hot reloading any asset

HotReload is a simple and agnostic building block for signaling that something should be hot reloaded. The more advanced features of this package build upon this, but it can also be used for the scenarios that those features do not cover.

import { HotReload } from "@tobloef/hot-reload";

const hot = new HotReload(import.meta.url);

// Listen for file changes
hot.onReload("/models/foo.obj", () => {
  // Do what needs to be done when the file changes
  // Likely involves re-fetching the assets and doing something with the new version
});

// Signal that a file changed
// Could for example be hooked up to a WebSocket listening to file events from the server
hot.reload("/models/foo.obj");

When a hot-reload was for some reason not possible (reload(...) returns false, you could for example fallback to a live reload instead.

Manually hot reloading JavaScript modules

Similar to HotReload but built for loading JavaScript modules.

Loads the module automatically, but does not replace any existing usages of the module.

import { HotModuleReload } from "@tobloef/hot-reload";

const hmr = new HotModuleReload(import.meta.url);

// Listen for file changes
hmr.onReload("/scripts/foo.js", (newModule) => {
  newModule.someExportedFunction();
});

// Can also be used with import attributes
// https://github.com/tc39/proposal-import-attributes
hmr.onReload("/configs/foo.json", { type: "json" }, (newModule) => {
  console.log(newModule.someJsonProp);
});

Automatically hot reloading JavaScript modules

This is the reason this package was made: To hot reload JavaScript modules without any manual handling of reload events.

This is accomplished by injecting script files with the ability to hot reload their imports upon receiving a reload event. This package cannot do this alone and will need an HTTP server or Service Worker to intercept and inject scripts. You will also likely need a WebSocket server or similar to notify the page when a file has changed.

To make the script foo.js support hot-reloading for all its imports, you call injectHotImports like this:

const originalScript = "...";
const modulePath = "./foo.js";
const newScript = injectHotImports(originalScript, modulePath);

When injecting, an input script like this:

import { foo } from "./bar.js";

document.querySelector("button").addEventListener("click", () => {
  foo();
});

Turns into an output script like this:

////////// START OF INJECTED HOT-RELOAD CODE //////////

let foo;

await (async () => {
  const { HotModuleReload } = await import("@tobloef/hot-reload");

  const hmr = new HotModuleReload(import.meta.url);

  hmr.onReload("./bar.js", (newModule) => {
    foo = newModule["foo"];
    return true;
  });

  foo = (await hmr.getModule("./bar.js"))["foo"];
})();

/////////// END OF INJECTED HOT-RELOAD CODE ///////////

document.querySelector("button").addEventListener("click", () => {
  foo();
});

Source maps are automatically generated and injected as well, to ensure breakpoints stay correct.

Limitations

  • Only works with ES Modules.
  • Because the injection only makes a module's imports hot reloadable, top-level scripts in your HTML file (imported using the script tag) will not be hot reloadable.

What is hot reloading?

The way I see it, "hot reloading" is taking a part of a running program and swapping it out for a new version without restarting the whole program. For example, being able to update a JavaScript module without refreshing the whole page.

You can also have "live reloading", where you restart the whole program (or refresh the webpage) automatically when a change is detected.

Live reloading is a simpler strategy, easier to implement and with fewer things that can go wrong. Hot reloading has the advantage of minimizing the amount of lost state to the specific part that was changed. For example, when developing a video game, you might update a 3D model or a function to calculate health points, while still keeping the player's position, score, etc.