Declarative dynamic imports for everyone!

npm i -S async-usage

What is it?

This is a simple tool for creating environment specific dynamic import factories with pluginable functionality. It allows you to create dynamic import factories to help your project be KISS and DRY. 😉

You can use it to reduce code repetition in your project's imports.

Mostly designed to work with webpack, but can be easily tuned to work with other bundlers or even native browser dynamic imports.

TLDR

General usage

It's simple - just create your specific async chunk use-case:

// Import the `createAsyncUsage` function
import { createAsyncUsage } from 'async-usage';

// Define the factory function to generate your imports
const importFactory = (path) => import(
  // Baked in webpack's "magic comments"
  /* webpackChunkName: "[request]" */
  /* webpackMode: "lazy" */

  // If using webpack, always start your factory path with a constant string,
  // so that webpack knows where to look to avoid complete module bundling.
  '@/' + path
);

// Create your final usage function
const useComponents = createAsyncUsage(
  importFactory, // Pass the import factory as the 1-st argument
  'components'   // Pass the base path as the second argument
);

And then use it 😉:

const components = useComponents(
  // Object options:
  // key - final imported module name alias
  // value - path to the module, relative to the base path passed into `createAsyncUsage`
  {
    'cool-component-base': 'path/to/cool/component-base',
    'some-component-top': 'path/to/some/component-top',
    'other-component': 'other/component',
  }

// You can then chain the call to avoid unnecessary object spreads
// Aliases for chaining: 'and', 'with'
).and(
  // Array options:
  // value - both path to the module AND its imported alias
  // `/` in the path will be replaced with `-` for the module alias
  [
    'home/page-slider'
  ],
  // Optional absolute path to the module from your importFactory root.
  'pages/home/components'
).clean();


// Result:
components === {
  'cool-component-base': () => import(
    /* webpackChunkName: "[request]" */
    /* webpackMode: "lazy" */
    '@/components/path/to/cool/component-base'
  ),
  'some-component-top': () => import(
    /* webpackChunkName: "[request]" */
    /* webpackMode: "lazy" */
    '@/components/path/to/some-component-top'
  ),
  'other-component': () => import(
    /* webpackChunkName: "[request]" */
    /* webpackMode: "lazy" */
    '@/components/other/component'
  ),
  'home-page-slider': () => import(
    /* webpackChunkName: "[request]" */
    /* webpackMode: "lazy" */
    '@/pages/home/components/home/page-slider'
  )
}

Plugins

It's possible to create custom plugins for createAsyncUsage.

createAsyncUsage already comes with two default plugins you can use: cachePlugin and ProfilePlugin

Shortly, the general format for plugins is the following:

type Plugin = {
  // Called when the usage was just initiated, returning a factory function
  invoked: (path: string, name: string, previousChunk: Promise<Chunk> | undefined) => Promise<Chunk> | undefined;
  
  // Called right before the `import` function is called
  beforeStart: (path: string, name: string, previousChunk: Promise<Chunk> | undefined) => Promise<Chunk> | undefined;

  // Called right after the `import` function is called
  started: (path: string, name: string, newChunk: Promise<Chunk>) => Promise<Chunk> | undefined;

  // Triggered upon successful chunk loading
  resolved: (path: string, name: string, result: Chunk) => Promise<Chunk> | Chunk | undefined;

  // Triggered if there was an error loading a chunk
  rejected: (path: string, name: string, reason) => Promise<Chunk> | Chunk | undefined;
}

Any value returned from those functions that is different from undefined will be treated as a loading result and returned instead of the the original result. If you want to simply let async-usage do its thing - simply return undefined from plugin's function.

Cache Plugin

This plugin simply caches your chunks in-memory, bypassing the browser request cache.

Useful in case of having a 'no-cache' flag for some assets, while also having a need to conditionally cache some modules.

Usage:

import { cachePlugin } from 'async-usage';

const use = createAsyncUsage(/* import factory here */, {
  basePath: 'assets',
  plugins: [
    cachePlugin
  ]
});

Profile Plugin

Logs chunk-loading statistics into the console in a following format:

 ┌─ Loading time from chunk being requested to a fully loaded chunk
 │             ┌─ Status of loading the chunk - Loaded | Error | Cached (loaded from cache by cachePlugin)
 │       ┌─────┴─────┐
250 ms ┬ Chunk loaded: footer-sama  ────── Name of the chunk (ususally, the key in a chunk-path map)
       └─ components/footer-sama
          └─────────┬──────────┘
                    └─ Path to the chunk
                       (relative to the base path set in your custom import factory)

Usage:

import { ProfilePlugin } from 'async-usage';

const use = createAsyncUsage(/* import factory here */, {
  basePath: 'assets',
  plugins: [
    new ProfilePlugin('src/assets', 'color: red')
  ]
});