Have ideas to improve npm?Join in the discussion! »

    @shopify/async
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.6 • Public • Published

    @shopify/async

    Build Status Build Status License: MIT npm version

    Primitives for loading parts of an application asynchronously.

    Installation

    $ yarn add @shopify/async

    Usage

    This package provides a wrapper for asynchronous import statements that allows for synchronous resolution and cacheing. This wrapper can be created using the createResolver function. The resulting Resolver object exposes a number of methods for interacting with the loaded module.

    const resolver = createResolver({
      load: () => import('./expensive'),
    });
    
    // Access the resolved module, if available. If an `id` option is provided
    // to `createResolver`, the resolver will attempt to synchronously
    // resolve the module based on the environment and the passed identifier.
    resolver.resolved;
    
    // If you provide an `id` option to `createResolver`, it will be
    // reflected here
    resolver.id;
    
    // Force the module to resolve. Returns a promise for the resolved value.
    resolver.resolve();

    This package also contains a few types that are useful for creating async components:

    • Import represents a value that could be default or non-default export
    • DeferTiming is an enum of defer timing values; has values for component Mount, browser Idle, or element InViewport

    As well as the following types related to window.requestIdleCallback:

    • RequestIdleCallbackHandle
    • RequestIdleCallbackOptions
    • RequestIdleCallbackDeadline
    • RequestIdleCallback
    • WindowWithRequestIdleCallback

    Finally, this package includes a plugin for Babel that allows the module IDs that are asynchronously imported to be exposed to the application.

    Babel

    The Babel plugin is exported from the @shopify/async/babel entrypoint. This plugin will look for any functions imported from the specified packages. It will then iterate over each reference to that function and, if the reference is a call expression where the first argument is an object, and that object has a load function, will mark it for processing. The adjustment is simple: it simply adds an id method that returns a Webpack-specific identifier based on the first dynamic import in the load method, allowing the function to use this identifier to mark the module as used.

    import {createAsyncComponent} from 'my-package';
    
    createAsyncComponent({
      load: () => import('../SomeComponent'),
    });
    
    // Becomes:
    
    createAsyncComponent({
      load: () => import('../SomeComponent'),
      id: () => require.resolveWeak('../SomeComponent'),
    });

    Options

    packages

    packages should be an object where the keys are the names of packages, and the values are an array of functions that should be processed. This option defaults to an object containing a few Shopify-specific async packages (createAsyncComponent and createAsyncContext from @shopify/react-async, and createAsyncQueryComponent from @shopify/react-graphql).

    // babel.config.js
    {
      plugins: [
        ['@shopify/async/babel', {
          packages: {
            'my-package': ['createAsyncComponent'],
          },
        }],
      ],
    }
    webpack

    If you are using your components in a non-Webpack environment (for example, in Jest), you can pass the webpack: false option to this plugin. This disables the Webpack-specific require.resolveWeak addition, and instead uses require.resolve. The resulting id can then be used to synchronously require the module in Node.js.

    Webpack

    In order to make use of the id property added by the Babel plugin, you will need to create a manifest of assets keyed by this ID. An example of doing so can be found in sewing kit’s webpack-asset-metadata-plugin package.

    Keywords

    none

    Install

    npm i @shopify/async

    DownloadsWeekly Downloads

    90,835

    Version

    2.2.6

    License

    MIT

    Unpacked Size

    58.9 kB

    Total Files

    40

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar