• The section in the Meteor Guide
• The official docs
• My presentation from Meteor Impact

1. Meteor re-runs modules when applying updates, either because the module was modified or one of its dependencies was modified. Until the old module gets garbage collected, there are multiple instances of it running within the app.
2. Before re-running each module, Meteor calls any dispose callbacks the module had registered. These dispose callbacks take care of making sure the old instance of the module no longer affects the running app. For example, it can stop Tracker computations, remove event listeners, clear timers, etc.

let errorListeners = [];

function init() {
  // Here the package would hook into Meteor to
  // receive the errors. When there is an error,
  // it will call all of the functions in errorListeners
}

init();

export const onError = (listener) => {
  errorListeners.push(listener);
};

import { onError } from 'meteor/extensive-error-reporting';

onError(err => {
  console.log('There was an error!', err);
});

if (module.hot) {
  module.hot.decline();
}

let errorListeners = [];

function init() {
  // Here the package would hook into Meteor to
  // receive the errors. When there is an error,
  // it will call all of the functions in errorListeners
}

init();

export const onError = (listener) => {
  errorListeners.push(listener);

  return () => {
    const index = errorListeners.indexOf(listener);

    if (index > -1) {
      errorListeners.splice(index, 1);
    }
  };
};

import { onError } from 'meteor/extensive-error-reporting';

const removeListener = onError(err => {
  console.log('There was an error!', err);
});

if (module.hot) {
  module.hot.dispose(() => removeListener());
}

let errorListeners = [];

// This has the id of the current module. For example:
//    /imports/client/app.jsx
let currentModule = null;
let addedBy = new WeakMap();

if (module.hot) {
  module.hot.onRequire({
    before(module, parentModuleId) {
      currentModule = module.id;

      if (module.hot) {
        // When the module is disposed, remove all error listeners
        // it added
        module.hot.dispose(() => {
          for (let i = errorListeners.length - 1; i >= 0; i--) {
            if (addedBy.get(errorListeners[i]) === module.id) {
              errorListeners.splice(i, 1);
            }
          }
        });
      }

      // Return the parent id so after this module
      // finishes running, the after hook can update
      // currentModule
      return { parentModuleId };
    },
    after(module, beforeData) {
      currentModule = beforeData.parentModuleId;
    }
  });
}

function init() {
  // Here the package would hook into Meteor to
  // receive the errors. When there is an error,
  // it will call all of the functions in errorListeners
}

init();

export const onError = (listener) => {
  if (listener) {
    addedBy.set(listener, currentModule);
  }

  errorListeners.push(listener);

  return () => {
    const index = errorListeners.indexOf(listener);

    if (index > -1) {
      errorListeners.splice(index, 1);
    }
  };
};

import { onError } from 'meteor/extensive-error-reporting';

const removeListener = onError(err => {
  console.log('There was an error!', err);
});

1. Will the package be used in files for the view layer, or in other files imported by those files for the view layer? If so, changes to those files will likely be applied with HMR, and for a good experience our package should support it.
2. Will developers want to rapidly iterate on the code that uses our package? If they do and our package is compatible with HMR, they could add module.hot.accept() to files that use our package so they are updated with HMR.

import { registerMessages } from 'meteor/simple-i18n';

registerMessages('en', {
  welcome: 'Welcome',
  goodbye: 'Goodbye'
});

registerMessages('es', {
  welcome: 'Bienvenido',
  goodbye: 'Adiós'
});

registerMessages('fr', {
  welcome: 'Bienvenue',
  goodbye: 'Au revoir'
});

if (module.hot) {
  module.hot.accept();
}

1. The module has no exports. If it does have exports, we want the modules that imported it to be re-run to use the new exports, and accepting updates in this module would prevent that.
2. The module calls registerMessages.

let registerMessagesCalled = false;

if (module.hot) {
  module.hot.onRequire({
    before(module, parentModuleId) {
      let parentCalled = registerMessagesCalled;

      registerMessagesCalled = false;

      // This will be available in the after hook as beforeData.
      return { parentCalled };
    },
    after(module, beforeData) {
      // Make sure HMR is available,
      // the module has no exports,
      // and the module added messages
      if (module.hot && registerMessagesCalled && !module.exports) {
        module.hot.accept();
      }

      registerMessagesCalled = beforeData.parentCalled;
    }
  });
}


export function registerMessages(language, messages) {
  registerMessagesCalled = true;

  // Here it would store the messages
}

• If your package is used in files that are automatically updated with HMR (for example, files with components or templates), or in files that are frequently modified and would benefit from HMR, you should make sure your package provides a way for the old instances of the file to properly disposed itself.
• If your package is normally used when a file is first run, the package can use module.hot.onRequire to add dispose handlers to automatically clean up modules.
• If the files that use your package are frequently modified, have no exports, and don’t do anything that would cause issues with there being multiple instances of the module, you could consider automatically accepting updates to those files. However, you should be careful when doing this since accepting updates for modules that don’t support being re-run can cause a worse experience than reloading the page.