diff --git a/docs/_guide/devtools-coverage.png b/docs/_guide/devtools-coverage.png new file mode 100644 index 00000000..b37fce5c Binary files /dev/null and b/docs/_guide/devtools-coverage.png differ diff --git a/docs/_guide/lazy-elements.md b/docs/_guide/lazy-elements.md new file mode 100644 index 00000000..1d751122 --- /dev/null +++ b/docs/_guide/lazy-elements.md @@ -0,0 +1,32 @@ +--- +chapter: 17 +subtitle: Dynamically load elements just in time +--- + +A common practice in modern web development is to combine all JavaScript code into JS "bundles". By bundling the code together we avoid the network overhead of fetching each file. However the trade-off of bundling is that we might deliver JS code that will never run in the browser. + +![A screenshot from Chrome Devtools showing the Coverage panel. The panel has multiple request to JS assets and it shows that most of them have large chunks that are unused.](/catalyst/guide/devtools-coverage.png) + +An alternative solution to bundling is to load JavaScript just in time. Downloding the JavaScript for Catalyst controllers when the browser first encounters them can be done with the `lazyDefine` function. + +```typescript +import {lazyDefine} from '@github/catalyst' + +// Dynamically import the Catalyst controller when the `` tag is seen. +lazyDefine('user-avatar', () => import('./components/user-avatar')) +``` + +Serving this file allows us to defer loading of the component code until it's actually needed by the web page. The tradeoff of deferring loading is that the elements will be inert until the dynamic import of the component code resolves. Consider what your UI might look like while these components are resolving. Consider providing a loading indicator and disabling controls as the default state. The smaller the component, the faster it will resolve which means that your users might not notice a inert state. A good rule of thumb is that a component should load within 100ms on a "Fast 3G" connection. + +Generally we think it's a good idea to `lazyDefine` all elements and then prioritize eager loading of ciritical elements as needed. You might consider using code-generation to generate a file lazy defining all your components. + +By default the component will be loaded when the element is present in the document and the document has finished loading. This can happen before sub-resources such as scripts, images, stylesheets and frames have finished loading. It is possible to defer loading even later by adding a `data-load-on` attribute on your element. The value of which must be one of the following prefefined values: + +- `` (default) + - The element is loaded when the document has finished loading. This listens for changes to `document.readyState` and triggers when it's no longer loading. +- `` + - This element is loaded on the first user interaction with the page. This listens for `mousedown`, `touchstart`, `pointerdown` and `keydown` events on `document`. +- `` + - This element is loaded when it's close to being visible. Similar to `` . The functionality is driven by an `IntersectionObserver`. + +This functionality is similar to the ["Lazy Custom Element Definitions" spec proposal](https://github.com/WICG/webcomponents/issues/782) and as this proposal matures we see Catalyst conforming to the spec and leveraging this new API to lazy load elements. diff --git a/package.json b/package.json index 98aaaa57..0cbf67fc 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,7 @@ "prepack": "npm run build", "presize": "npm run build", "size": "size-limit", - "test": "web-test-runner test/* --node-resolve" + "test": "web-test-runner" }, "prettier": "@github/prettier-config", "devDependencies": { diff --git a/src/index.ts b/src/index.ts index 0cb35f27..56865e93 100644 --- a/src/index.ts +++ b/src/index.ts @@ -5,3 +5,4 @@ export {target, targets} from './target.js' export {controller} from './controller.js' export {attr, initializeAttrs, defineObservedAttributes} from './attr.js' export {autoShadowRoot} from './auto-shadow-root.js' +export {lazyDefine} from './lazy-define.js' diff --git a/src/lazy-define.ts b/src/lazy-define.ts new file mode 100644 index 00000000..e9006231 --- /dev/null +++ b/src/lazy-define.ts @@ -0,0 +1,98 @@ +type Strategy = (tagName: string) => Promise + +const dynamicElements = new Map void>>() + +const ready = new Promise(resolve => { + if (document.readyState !== 'loading') { + resolve() + } else { + document.addEventListener('readystatechange', () => resolve(), {once: true}) + } +}) + +const firstInteraction = new Promise(resolve => { + const controller = new AbortController() + controller.signal.addEventListener('abort', () => resolve()) + const listenerOptions = {once: true, passive: true, signal: controller.signal} + const handler = () => controller.abort() + + document.addEventListener('mousedown', handler, listenerOptions) + // eslint-disable-next-line github/require-passive-events + document.addEventListener('touchstart', handler, listenerOptions) + document.addEventListener('keydown', handler, listenerOptions) + document.addEventListener('pointerdown', handler, listenerOptions) +}) + +const visible = (tagName: string): Promise => + new Promise(resolve => { + const observer = new IntersectionObserver( + entries => { + for (const entry of entries) { + if (entry.isIntersecting) { + resolve() + observer.disconnect() + return + } + } + }, + { + // Currently the threshold is set to 256px from the bottom of the viewport + // with a threshold of 0.1. This means the element will not load until about + // 2 keyboard-down-arrow presses away from being visible in the viewport, + // giving us some time to fetch it before the contents are made visible + rootMargin: '0px 0px 256px 0px', + threshold: 0.01 + } + ) + for (const el of document.querySelectorAll(tagName)) { + observer.observe(el) + } + }) + +const strategies: Record = { + ready: () => ready, + firstInteraction: () => firstInteraction, + visible +} + +const timers = new WeakMap() +function scan(node: Element) { + cancelAnimationFrame(timers.get(node) || 0) + timers.set( + node, + requestAnimationFrame(() => { + for (const tagName of dynamicElements.keys()) { + const child: Element | null = node.matches(tagName) ? node : node.querySelector(tagName) + if (customElements.get(tagName) || child) { + const strategyName = (child?.getAttribute('data-load-on') || 'ready') as keyof typeof strategies + const strategy = strategyName in strategies ? strategies[strategyName] : strategies.ready + // eslint-disable-next-line github/no-then + for (const cb of dynamicElements.get(tagName) || []) strategy(tagName).then(cb) + dynamicElements.delete(tagName) + timers.delete(node) + } + } + }) + ) +} + +let elementLoader: MutationObserver + +export function lazyDefine(tagName: string, callback: () => void) { + if (!dynamicElements.has(tagName)) dynamicElements.set(tagName, new Set<() => void>()) + dynamicElements.get(tagName)!.add(callback) + + scan(document.body) + + if (!elementLoader) { + elementLoader = new MutationObserver(mutations => { + if (!dynamicElements.size) return + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + if (node instanceof Element) scan(node) + } + } + }) + elementLoader.observe(document, {subtree: true, childList: true}) + } +} diff --git a/test/lazy-define.ts b/test/lazy-define.ts new file mode 100644 index 00000000..40c53583 --- /dev/null +++ b/test/lazy-define.ts @@ -0,0 +1,80 @@ +import {expect, fixture, html} from '@open-wc/testing' +import {spy} from 'sinon' +import {lazyDefine} from '../src/lazy-define.js' + +describe('lazyDefine', () => { + describe('ready strategy', () => { + it('calls define for a lazy component', async () => { + const onDefine = spy() + lazyDefine('scan-document-test', onDefine) + await fixture(html``) + + await new Promise(resolve => requestAnimationFrame(resolve)) + + expect(onDefine).to.be.callCount(1) + }) + + it('initializes dynamic elements that are defined after the document is ready', async () => { + const onDefine = spy() + await fixture(html``) + lazyDefine('later-defined-element-test', onDefine) + + await new Promise(resolve => requestAnimationFrame(resolve)) + + expect(onDefine).to.be.callCount(1) + }) + + it("doesn't call the same callback twice", async () => { + const onDefine = spy() + lazyDefine('twice-defined-element', onDefine) + lazyDefine('once-defined-element', onDefine) + lazyDefine('twice-defined-element', onDefine) + await fixture(html` + + + + + + + + `) + + await new Promise(resolve => requestAnimationFrame(resolve)) + + expect(onDefine).to.be.callCount(2) + }) + }) + + describe('firstInteraction strategy', () => { + it('calls define for a lazy component', async () => { + const onDefine = spy() + lazyDefine('scan-document-test', onDefine) + await fixture(html``) + + await new Promise(resolve => requestAnimationFrame(resolve)) + expect(onDefine).to.be.callCount(0) + + document.dispatchEvent(new Event('mousedown')) + + await new Promise(resolve => requestAnimationFrame(resolve)) + expect(onDefine).to.be.callCount(1) + }) + }) + describe('visible strategy', () => { + it('calls define for a lazy component', async () => { + const onDefine = spy() + lazyDefine('scan-document-test', onDefine) + await fixture( + html`
+ ` + ) + await new Promise(resolve => requestAnimationFrame(resolve)) + expect(onDefine).to.be.callCount(0) + + document.documentElement.scrollTo({top: 10}) + + await new Promise(resolve => requestAnimationFrame(resolve)) + expect(onDefine).to.be.callCount(1) + }) + }) +}) diff --git a/web-test-runner.config.js b/web-test-runner.config.js index b1deeaf6..9f86690f 100644 --- a/web-test-runner.config.js +++ b/web-test-runner.config.js @@ -2,5 +2,6 @@ import {esbuildPlugin} from '@web/dev-server-esbuild' export default { files: ['test/*'], + nodeResolve: true, plugins: [esbuildPlugin({ts: true, target: 'es2020'})] }