IMPORTED COMPONENT ✂

Code splitting which always works^*

SSR-friendly code splitting compatible with any platform.
Deliver a better experience within a single import.

^* It's really will never let you down. All credits to your bundler.

👉 Usage | API | Setup | SSR | CCS Concurrent loading | Webpack/Parcel

Read more about what this table displays

Key features:

• 1️⃣ Single source of truth - your bundler drives everything
• 📖 library level code splitting
• 🧙️ Hybrid and Prerendering compatible
• 💡 TypeScript bindings
• ⚛️ React.Lazy underneath (if hot module updates are disabled)
• 🌟 Async on client, sync on server. Supports Suspense (even on server side)
• 📦 could work with any bundler - webpack, rollup, parcel or puppeteer - it does not matter
• 🤹‍♂️ working as well with any import you may provide

Other features:

• 🔥 Hot-Module-Replacement/React-Hot-Loader friendly
• ⛓️ support forwardRef
• ⚛️ React 16/Async/Hooks ready
• 🛠 HOC, Component, Hooks API
• 🐳 stream rendering support
• 👥 partial hydration out of the box
• 📦 and yes - this is the only parcel-bundler compatible SSR-friendly React code splitting library, as well as a perfect solution for Create React App

👍 Better than React.Lazy:

• It IS Lazy, just with some stuff around^*
• SSR, Prerendering and Preloading support
• With or without Suspense, and easier Error cases support

👍 Better than others:

• Not bound to webpack
• Easy way to use per-browser(modern/legacy) bundles - you down have to mess with actual browser support
• Strong typing
• Working with any imports, even native, external or derived ones.

👌 Client-side module resolution

• Loads chunks only after the main one, as long as loader code is bundled inside the main chunk, so it should be loaded first.
• Not an issue with the progressive hydration, and might provide a better UX via feature detection.
• Provides 👨‍🔬 technological workaround - see here

📦 Optional bundler integration for the best experience

• prefetching backed by webpack stat.json and asset.json
• parcel-manifest.json support

👯‍♀️Works better in pair

• react-prerendered-component for prerendering, partial hydration and react fragment caching
• used-style for CSS and critical CSS extraction
• devolution for shipping legacy/modern bundles
• webpack-imported for deep webpack integration, the only bundler dependent tool in this list.

import importedComponent from 'react-imported-component';
const Component = importedComponent( () => import('./Component'));

const Component = importedComponent( () => import('./Component'), {
  LoadingComponent: Spinner, // what to display during the loading
  ErrorComponent: FatalError // what to display in case of error
});

Component.preload(); // force preload

// render it
<Component... />

import { lazy, LazyBoundary } from 'react-imported-component';
const Component = lazy(() => import('./Component'));

const ClientSideOnly = () => (
  <Suspense>
    <Component />
  </Suspense>
);

// or let's make it SSR friendly
const ServerSideFriendly = () => (
  <LazyBoundary>
    {' '}
    // LazyBoundary is Suspense on the client, and "nothing" on the server
    <Component />
  </LazyBoundary>
);

Example: React.lazy vs Imported-component

Hook

However, you may not load only components - you may load anything

import {useImported} from 'react-imported-component'

const MyCalendarComponent = () => {
  const {
      imported: moment,
      loading
    } = useImported(() => import("moment"));

  return loading ? "..." : <span>today is {moment(Date.now).format()}</span>
}

// or we could make it a bit more interesting...

const MyCalendarComponent = () => {
  const {
      imported: format  = x => "---", // default value is used while importing library
    } = useImported(
      () => import("moment"),
      moment => x => moment(x).format // masking everything behind
    );

  return <span>today is {format(Date.now())</span>
}

What you could load using useImported? Everything - imported itself is using it to import components.

useImported is an excellent example for loading translations, which are usually a simple json, in a trackable way.

💡 did you know that there is another hook based solution to load "something might might need"? The use-sidecar pattern.

🤔 Keep in mind - everything here is using useImported, and you can build whatever you need using just it.

Module

A slim helper to help handle modules, you might require using useImported in a component way

import { importedModule, ImportedModule } from 'react-imported-component';

const Moment = importedModule(() => import('moment'));

<Moment fallback="long time ago">
  {(momentjs /* default imports are auto-imported*/) => momentjs(date).fromNow()}
</Moment>;

Yes, this example was taken from loadable.lib

Can I also use a ref, populated when the library is loaded? No, you cant. Use useImported for any special case like this.

Plus, there is a Component helper:

<ImportedModule
 // import is just a _trackable_ promise - do what ever you want
 import={() => import('moment').then(({momentDefault})=> momentDefault(date).fromNow()}
 fallback="long time ago"
>
 {(fromNow) => fromNow()}
</ImportedModule>

ImportedModule will throw a promise to the nearest Suspense boundary if no fallback provided.

Babel macro

If you could not use babel plugin, but do have babel-plugin-macro (like CRA) - consider using macro API:

import { imported, lazy, useImported } from 'react-imported-component/macro';
// notice - there is no default import here

Indirect usage

Just importing react-imported-component/macro would enable babel transformation for the current file. If you have imported definition in one file, and use it from another - just import "react-imported-component/macro" in that another file. See #142

1. Add babel plugin
2. Run yarn imported-components src src/imported.js to extract all your imports into a run time chunk (aka async-requires).
3. Replace React.lazy with our lazy, and React.Suspense with our LazyBoundary. Literraly monkey-patch React to do so
4. Add printDrainHydrateMarks to the server code.
5. Add rehydrateMarks to the client code
6. Done. Just read the rest of readme for details.

There are examples for webpack, parcel, and react-snap. Just follow them.

1. Configure babel plugin

On the server:

{
  "plugins": ["react-imported-component/babel", "babel-plugin-dynamic-import-node" /* might be optional for babel 7*/]
}

On the client:

{
  "plugins": ["react-imported-component/babel"]
}

Imported-Component will hook into dynamic imports, providing extra information about files you want to load.

2. Add one more command into package.json

CLI command imported-components [sources ROOT] [targetFile.js] (use .ts for TypeScript)

 "generate-imported-component": "imported-components src src/imported.js"

When you will execute this command - all imports among your codebase would be found and extracted to a file provided. This will gave ability to orchestrate code-splitting later.

If you need to search inside more that one top-level directory - just define more command, saving information into more than one target file.

The current implementation will discover and use all imports, even // commented ones

💡 Feel free to .gitignore these autogenerated files

3. Start using imported, lazy or useImported

Without you using API provided nothing would work.

4. Add server side tracking

There are two ways to do it - in a single threaded way, and async

Single threaded

import { printDrainHydrateMarks, drainHydrateMarks } from 'react-imported-component';
// this action will "drain" all currently used(by any reason) marks
// AND print a script tag
const html = renderToString(<YourApp />) + printDrainHydrateMarks();

// OR return list of usedmarks, and yet again CLEAR the marks list.
const html = renderToString(<YourApp />) + '<script>const marks=' + JSON.stringify(drainHydrateMarks()) + '</script>';

renderToStream or async render

import {createLoadableStream} 'react-imported-component';

let importedStream = createLoadableStream();
// ImportedStream is a async rendering "provider"
const stream = renderToStream(
  <ImportedStream stream={importedStream}>
    <YourApp />
  </ImportedStream>
);

// you'd then pipe the stream into the response object until it's done
stream.pipe(res, { end: false });

// and finalize the response with closing HTML
stream.on('end', () =>
    // print marks used in the file
    res.end(`${printDrainHydrateMarks(importedStream)}</body></html>`),
)

However, the idea is just to use streams to separate renders

const html =
  renderToString(
    <ImportedStream stream={importedStream}>
      <YourApp />
    </ImportedStream>
  ) + printDrainHydrateMarks(importedStream);

5. Add rehydrateMarks to the client code

Before rendering your application you have to ensure - all parts are loaded. rehydrateMarks will load everything you need, and provide a promise to await.

import { rehydrateMarks } from 'react-imported-component';

// this will trigger all marked imports, and await for competition.
rehydrateMarks().then(() => {
  // better
  ReactDOM.hydrate(<App />, document.getElementById('main'));
  // or
  ReactDOM.render(<App />, document.getElementById('main'));
});

rehydrateMarks accepts a list of marks from a server side(drainHydrateMarks), loads all necessary chunks and then resolves.

// index.js (boot)
import './src/imported'; // the file generated by "generate-imported-component" (.2)
import { rehydrateMarks } from 'react-imported-component/boot';

rehydrateMarks(); // just start loading what's needed

// load/execute the rest after letting the browser kick off chunk loading
// for example wrapping it in two Promises (1ms timeout or setImmediate)
Promise.resolve().then(() =>
  Promise.resolve().then(() => {
    // load the rest
    require('./main'); // <--- your main scripts
    // ! and don't forget to `await rehydrateMarks()` before render
  })
);

// main.js
rehydrateMarks().then(() => {
  ReactDOM.hydrate(<App />, document.getElementById('root'));
});

// index.js (boot)
import './src/imported'; // the file generated by "generate-imported-component" (.2)
import { rehydrateMarks } from 'react-imported-component/boot';

rehydrateMarks(); // just start loading what's needed

const startApp = () => require('./main'); // <--- your main scripts

// it's "not safe" to start you application before DOM is "ready"
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', startApp);
} else {
  startApp();
}

import {createLoadableTransformer, getLoadableTrackerCallback} from 'react-imported-component/server';
const importedTracker = createLoadableTransformer(
  loadableStream, // stream to observe
  getLoadableTrackerCallback() // helper factory to create global tracker.
);

// pipe result of `renderToStream` throught it
const reactRenderStream = ReactDOM.renderToNodeStream(...).pipe(importedTracker);

// index.js
import './src/imported'; // the file generated by "generate-imported-component" (.2)
import { injectLoadableTracker } from 'react-imported-component/boot';

injectLoadableTracker();

// load the rest after letting the browser kick off chunk loading
// for example wrapping it in two Promises (1ms timeout or setImmediate)
Promise.resolve().then(() =>
  Promise.resolve().then(() => {
    require('./main');
  })
);

import React from 'react';
import { lazy, LazyBoundary } from 'react-imported-component';
React.lazy = lazy;
React.Suspense = LazyBoundary;

• pre-render supports state hydration, like getState in react-snap. See our example.
• for rendertron or https://prerender.io follow react-snap example, just dump state using setTimeout.
• You may use react-prerendered-component to maintain a component state until async chunk is not loaded. See example below.

Works better in pair (boiled-place-less code splitting)

You might not need to wait for all the chunks to be loaded before you can render you app - just use react-prerendered-component.

import imported from 'react-imported-component';
import { PrerenderedComponent } from 'react-prerendered-component';

const AsyncComponent = imported(() => import('./myComponent.js'));

<PrerenderedComponent
  // component will "go live" when chunk loading would be done
  live={AsyncComponent.preload()}
>
  // until component is not "live" prerendered HTML code would be used // that's why you need to `preload`
  <AsyncComponent />
</PrerenderedComponent>;

React-prerendered-component is another way to work with code splitting, which makes everything far better.

Timeout to display "spinners"

There is no build in timeouts to display Error or Loading states. You could control everything by yourself

• use react-delay, p-delay, p-timeout, or Suspense :P.

Component loader

You may use component api if you need it by any reason.

import { ComponentLoader } from 'react-imported-component';

const MyPage = () => (
  <ComponentLoader
    loadable={() => import('./Page.js')}
    // all fields are optional, and matches the same field of importedComponent.
    LoadingComponent={Loading}
    ErrorComponent={Error}
    onError
    exportPicker
    render
    async
  />
);

This library does not support CSS as CSS, as long it's bundler independent and such deep integration is not possible. Even if deep bundler integration is next following this section - the recomended solution is to skip css part of it, and use a more bundler independent way to support CSS:

1. Configure you bundler, and server side rendering to emit the right classNames (just remove style-loader from webpack configuration)
2. Use used-styles to inject used css files to the resulting HTML.

In short (streamed example is NOT short)

const lookup = discoverProjectStyles('./dist');
// ....
const markup = ReactDOM.renderToString(<App />);
const usedStylesAsCSSFiles = getUsedStyles(markup, lookup);
// generate `link` (better rel='preload') to load CSS files

const usedStylesAsStyles = getCriticalStyles(markup, lookup);
// extract critical CSS and inline in to the server response

If you need stream render example with reduced TTFB - please refer to used-styles documentation, or our parcel-bundler stream server example.

Critical style extraction and Preloader

With the critical style extracting you might not need the "real" and "full" styles on the page load - only js is really required for hydration. Thus - you might skip loading styles for the initial render, however still need them for the next render. However - your bundler might think that you have loaded them, this is not true. To handle this case you need addPreloader method

// load initial bundle
// await dom ready
// -> HYDRATE APP <-
// add preloader

import { addPreloader } from 'react-imported-component/boot';

addPreloader(() => {
  // check that styles are loaded
  // or return Promise if they are not
});

// any not yet loaded ImportedComponent
// will await for it's own `import` as well as for
// promise returned from preloaders

See critical css example for details

Create React App

Use react-imported-component/macro for CRA compatible SSR code splitting without ejecting.

It is safe to always use react-imported-component/macro without babel-plugin-macros, BUT with react-hot-loader/babel enabled, as long as it will remove all macros.

// get mark somehow (drainHydrateMarks(importedStream))
import { getMarkedChunks } from 'react-imported-component/server';

const chunkNames = getMarkedChunks(marks);

webpack-imported - provides webpack plugin to get data from the build, as well as to use it. Supports prefetching and critical style guidance.

import { WebpackImport } from 'webpack-imported/react';
import importedStat from 'build/imported.json';

<WebpackImport stats={importedStat} chunks={getMarkedChunks(drainHydrateMarks())} />;

Via stat.json

If you do have only stat.json - it could be converted into "importedStat" by webpack-imported without adding plugin.

Alternatively - you can discover all resources you have to preload using flush-webpack-chunks

const { js, styles } = flushChunks(webpackStats, {
  chunkNames,
});

const prefetch = (targets, as) => targets.map(url => `<link as="${as}" rel="preload" href="${url}" />`).join('');

res.send(prefetch(scripts, 'script'));
res.send(prefetch(stylesheets, 'style'));

DO NOT actually load reported resources - only preload them, and let webpack do rest.

Via assets.json

You you are using assets-webpack-plugin then you have only list of assets, without dependencies between. That's enought.

const prefetchChunks = (chunks, assets) =>
  chunks
    .map(chunk =>
      [
        assets[chunk].js && `<link rel="preload" as="script" href="${assets[chunk].js}" />`,
        assets[chunk].css && `<link rel="preload" as="style" href="${assets[chunk].css}" />`,
      ].join('')
    )
    .join('');

res.send(prefetchChunks(chunkNames, assets));

Parcel integration

Use parcel-manifest and getMarkedFileNames(instead of getMarkedChunks) to find which files were required and has to be imported. Keep in mind - the base path would be different and you have to resolve the right files in to the right files (/app/index to index.js).

CRA integration

Consider using concurrent-loading technique only.

React-snap

react-imported-component is compatible with react-snap out of the box. Works even better with react-prerendered-component.

Webpack-external-import (or native import)

react-imported-component is compatible with webpack-external-import, as long as it executes imports, thus executes custom logic

useImported and Suspense

useImported is not supposed to be used with Suspense (by design), while it could

const MyComponent = () => {
  const { loading, error, loadable, imported } = useImported(() => import('...'));

  if (loading) throw loadable.resolution; // throw to the nearest Suspense boundary
  if (error) throw error; // throw to the nearest Error boundary

  // do something with `imported` value
};

SSR (Server side rendering)

It was usually a headache - async components and SSR, which is currently sync. React-imported-component break this cycle, making ServerSide rendering sync, and providing comprehensive ways to rehydrate rendered tree on client. It will detect server-side environment and precache all used components.

Server Side Auto Import

On the server side imported would auto-import any found import. As long as not all imports could be executed at Server Side you might pop out this feature using a "magic comment".

import(/* client-side */ './file');

Or file filtering

import { setConfiguration } from 'react-imported-component';

setConfiguration({
  fileFilter: fileName => file.indexOf('/client') !== 0,
});

.imported.js

There is possibility to finely control both with files are scanned, which imports are added and which chunks would be generated(webpackonly) via .imported.js at the root directory

💩 .js, not .ts

// 👉 use provided helper for documentation and type safety
const { configure } = require('react-imported-component');

modules.export = configure({
  configuration: {
    // the same options you can use in setConfiguration
    // for example
    checkSignatures: false,
  },
  testFile: fileName => true | false,
  testImport: (targetFile, sourceFile) => true | false,
  clientSideOnly: (targetFile, sourceFile, sourceComments) => true | false,
  shouldPrefetch: (targetFile, sourceFile, sourceComments) => true | false,
  shouldPreload: (targetFile, sourceFile, sourceComments) => true | false,
  chunkName: (targetFile, sourceFile, sourceComments) => string | null | undefined,
});

None of those methods are required.

.imported could be used to:

• remove some files or imports
• autogenerate chunk names or prefetch/preload

Bundler independent SSR

It does not matter how do you bundle your application - it could be even browser. The secrect sause is a cli command, to extract all your imports into imports map, and use it later to load chunks by request.

• You might even dont have any separated chunk on the server side - it would still works.
• You might even ship module/nomodule scripts, using, for example, devolution - no additional configuration would be required.

Why you need SSR

In case of imported component SSR is a "dry run" of your application - an easy way to discover required pieces powered by zero latency(you are already on the server) and super fast speed connection (all scripts are in memory).

However - you dont need SSR to get the same benefits on pure ClientSideRendered solutions - prediction would be enought. The common approach is to

• load first part of components, including Providers, which would load something they need. Like translations.
• then hit, and load the current route
• then do the same with the sub route

This causes effect known as loading waves, the effect SSR could mitigate almost in full.

However, nothing stops you from loading translation data in the parallel to the routes, and loading route and sub route in the same time, not sequentially. You can have backend-for-frontend, why not to have frontend-for-frontend? Just handle route, cookies, and whatever you could handle, outside of React. Redux-first-router and principles behind it are the great example of this idealogy.

Not using React.Lazy with React-Hot-Loader

There is design limitation with React.lazy support from RHL size, so they could not be reloaded without state loss if lazy is created not in the user space. At it would be created inside imported.

If React-Hot-Loader is detected lazy switches to imported async mode, this behaves absolutely the same.

• https://medium.com/hackernoon/react-and-code-splitting-made-easy-f118befb5168
• https://dev.to/thekashey/react-imported-component-v6-4304

Other loaders

Another loaders exist, and the only difference is in API, and how they manage (or not manage) SSR.

• (no SSR) React.Lazy

• (webpack only) With react-loadable

• (not compatible with hooks) react-async-component

• (webpack only) loadable-components

• (webpack only) react-universal-component

• (not a component loader) use-sidecar

Licence

MIT

Current Tags

• 6.3.12                                ...           beta (4 years ago)
• 6.5.4                                ...           latest (9 months ago)
• 6.2.4                                ...           next (5 years ago)

80 Versions

• 6.5.4                                ...           9 months ago
• 6.5.3                                ...           3 years ago
• 6.5.2                                ...           3 years ago
• 6.5.0                                ...           3 years ago
• 6.4.1                                ...           4 years ago
• 6.4.0                                ...           4 years ago
• 6.3.13                                ...           4 years ago
• 6.3.12                                ...           4 years ago
• 6.3.11                                ...           4 years ago
• 6.3.10                                ...           4 years ago
• 6.3.9                                ...           4 years ago
• 6.3.7                                ...           4 years ago
• 6.3.6                                ...           4 years ago
• 6.3.5                                ...           4 years ago
• 6.3.4                                ...           5 years ago
• 6.3.3                                ...           5 years ago
• 6.3.2                                ...           5 years ago
• 6.3.1                                ...           5 years ago
• 6.3.0                                ...           5 years ago
• 6.2.4                                ...           5 years ago
• 6.2.3                                ...           5 years ago
• 6.2.2                                ...           5 years ago
• 6.2.1                                ...           5 years ago
• 6.2.0                                ...           5 years ago
• 6.1.1                                ...           5 years ago
• 6.1.0                                ...           5 years ago
• 6.0.5                                ...           5 years ago
• 6.0.4                                ...           5 years ago
• 6.0.3                                ...           5 years ago
• 6.0.2                                ...           5 years ago
• 6.0.1                                ...           5 years ago
• 6.0.0                                ...           5 years ago
• 6.0.0-beta.6                                ...           5 years ago
• 6.0.0-beta.5                                ...           5 years ago
• 6.0.0-beta.4                                ...           5 years ago
• 6.0.0-beta.3                                ...           5 years ago
• 6.0.0-beta.2                                ...           5 years ago
• 6.0.0-beta.1                                ...           5 years ago
• 5.5.3                                ...           6 years ago
• 5.5.1                                ...           6 years ago
• 5.5.0                                ...           6 years ago
• 5.4.1                                ...           6 years ago
• 5.4.0                                ...           6 years ago
• 5.3.0                                ...           6 years ago
• 5.2.5                                ...           6 years ago
• 5.2.4                                ...           6 years ago
• 5.2.3                                ...           6 years ago
• 5.2.2                                ...           6 years ago
• 5.2.1                                ...           6 years ago
• 5.2.0                                ...           6 years ago
• 5.1.3                                ...           6 years ago
• 5.1.2                                ...           6 years ago
• 5.1.1                                ...           6 years ago
• 5.1.0                                ...           6 years ago
• 5.0.1                                ...           6 years ago
• 5.0.0                                ...           6 years ago
• 4.6.2                                ...           6 years ago
• 4.6.1                                ...           7 years ago
• 4.6.0                                ...           7 years ago
• 4.5.0                                ...           7 years ago
• 4.4.2                                ...           7 years ago
• 4.4.1                                ...           7 years ago
• 4.4.0                                ...           7 years ago
• 4.3.3                                ...           7 years ago
• 4.3.2                                ...           7 years ago
• 4.3.1                                ...           7 years ago
• 4.3.0                                ...           7 years ago
• 4.2.1                                ...           7 years ago
• 4.2.0                                ...           7 years ago
• 4.1.1                                ...           7 years ago
• 4.1.0                                ...           7 years ago
• 4.0.1                                ...           7 years ago
• 4.0.0                                ...           7 years ago
• 2.0.1                                ...           7 years ago
• 2.0.0                                ...           7 years ago
• 1.0.4                                ...           7 years ago
• 1.0.3                                ...           7 years ago
• 1.0.2                                ...           7 years ago
• 1.0.1                                ...           7 years ago
• 1.0.0                                ...           7 years ago