background-only

Background Only

This is a marker package to indicate that a module can only be used in the Background thread.

Example usages

Say we have a Logger module that has side effects calling into Native Modules or other APIs that are only available in the "Background" environment:

// Logger.js
import "background-only";

export function log(msg) {
  // Notice how we are calling into NativeModules here.
  NativeModules.hybridMonitor.reportJSError(...);
}

By adding import "background-only" to poison this module, we are now declaring that this module is only safe to be bundled in a "Background" environment, protecting this module from being accidentally bundled into a "Main thread" environment by throwing an error at runtime.

For example, if we use log in a desirable position from a React component, such as in useEffect or an event handler, the log will work as expected:

// App.jsx
import { log } from "./Logger";

function App() {
  useEffect() {
    log();
  }
  return <view />
}

However, if we use log in a undesirable position from a React component, such as in the body of the rendering function, it will throw an error at runtime time:

// App.jsx
import { log } from "./Logger";

function App() {
  // throw!
  log();
  return <view />
}

Credits

This is inspired by the server-only package of React.