lazy API

How to use the lazy function to dynamically import a component only when it is rendered.

Dynamic import

lazy loads a component only when Wompo needs to render it.

import { lazy } from 'wompo';

const UserChart = lazy(() => import('./UserChart.js'));

The imported file must export the component as default.

// UserChart.js
import { defineWompo, html } from 'wompo';

function UserChart() {
  return html`<section>Chart content</section>`;
}

defineWompo(UserChart);
export default UserChart;

Render the lazy component like any other dynamic Wompo component.

function Dashboard() {
  return html`
    <section>
      <${UserChart} />
    </section>
  `;
}

Suspense fallback

Pair lazy with Suspense when you want a loading UI while the chunk is being imported.

import { Suspense, html, lazy } from 'wompo';

const UserChart = lazy(() => import('./UserChart.js'));

function Dashboard() {
  return html`
    <${Suspense} fallback=${html`<p>Loading chart...</p>`}>
      <${UserChart} />
    </${Suspense}>
  `;
}

Simulating a slow component

Local development often loads chunks too quickly to see the fallback. You can wrap the import in a small delay while testing.

function delayImport(promise) {
  return new Promise((resolve) => setTimeout(resolve, 800))
    .then(() => promise);
}

const LazySettings = lazy(() => delayImport(import('./SettingsPanel.js')));

Common mistakes

Do not return a named export unless you convert it to a default export shape.

// Wrong if the file does not export default.
const Chart = lazy(() => import('./Chart.js'));
// Correct when the component is exported by name.
const Chart = lazy(() =>
  import('./Chart.js').then((module) => ({
    default: module.Chart,
  })),
);