Add mechanism to allow developers to Hot Reload certain Package assets

[cswendrowski]

Summary

Hot reloading is a feature where changes to certain files are captured and inserted into a live page in realtime without reloading. This can help speed up development tasks such as styling, templating, and localization.

Core Behavior

The following core behaviors are available out of the box. Only actively enabled packages will receive hot reload events.

HTML and HBS

Template files update the registered Handlebars partials and _templateCache, and then any open applications are rerendered

Note: Rerendering open apps redraws the entire app, and does not attempt to save any edits in progress

JSON

If the modified file is the current active language for the package (as defined in languages) such as en.json, game.i18n.translations is updated with the new localization entries and then any open applications are rendered

Note: Rerendering open apps redraws the entire app, and does not attempt to save any edits in progress

CSS

Style files reload the stylesheet, usually resulting in a brief flash as the page redraws with the new styles

How to setup Hot Reloading

An active package can opt-in to hot reload by declaring flags.hotReload in their manifest, with the following structure:

{
  "hotReload": { 
    "extensions": [ "Required. An array of file extensions, such as 'css'. ],
    "paths": [ "Optional. An array of paths to directories or files that should be watched. If not set, the entire package directory is watched." ]
  }
}

Example:

  "flags": {
    "hotReload": {
      "extensions": ["css", "html", "hbs", "json"],
      "paths": ["system/templates", "css", "lang/en.json"]
    }
  },

Performance note: There is an overhead to watching too many files for changes - serializing those and sending them to the client is somewhat costly, and if you watch too broadly such that dozens of files change at once (such as some build operations), you will experience lag. It is generally better to define paths narrowly.

As of #9083, you'll also need to enable hot reloading for the server in your options.json, editable in the Setup screen options:

How to extend Core Behavior

Before Core hot reload behavior executes, the hotReload hook is fired with the following data object:

  /**
   * @typedef {Object} HotReloadData
   * @property {string} packageType   The type of package which was modified
   * @property {string} packageId        The id of the package which was modified
   * @property {string} content            The updated stringified file content
   * @property {string} path                 The relative file path which was modified
   * @property {string} extension         The file extension which was modified, e.g. "js", "css", "html"
   */

Registering a hook for this event that returns false will prevent core behavior from occurring.