async-usage
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.0 • Public • Published

    Build Status Coverage status npm npm bundle size (minified) dependencies (minified)

    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')
      ]
    });

    Install

    npm i async-usage

    DownloadsWeekly Downloads

    49

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    104 kB

    Total Files

    84

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar