feat(react): fetchBundle-based lazy bundle loader

.changeset/lazy-bundle-fetch-bundle.md

@@ -0,0 +1,14 @@
+---
+"@lynx-js/react": minor
+"@lynx-js/react-rsbuild-plugin": minor
+"@lynx-js/react-webpack-plugin": minor
+"@lynx-js/template-webpack-plugin": minor
+---
+
+feat(lazy-bundle): add `lynx.fetchBundle`-based loader
+
+Opt in by setting `engineVersion: '3.8'` (or higher) in `pluginReactLynx`.
+Use `import('./X', { with: { mode: 'sync' | 'async' } })` to control whether
+the first screen blocks on a sync fetch. The lazy bundle's main-thread
+section is bytecoded by default (skipped in dev or when `DEBUG` includes
+`rspeedy`).

benchmark/react/package.json

@@ -40,7 +40,7 @@
     "@lynx-js/rspeedy": "workspace:*",
     "@lynx-js/trace-processor": "^0.0.1",
     "@lynx-js/type-element-api": "0.0.3",
-    "@lynx-js/types": "3.7.0",
+    "@lynx-js/types": "3.10.2-alpha.0",
     "@types/react": "^18.3.28"
   }
 }

codecov.yml

@@ -27,9 +27,12 @@ coverage:
 ignore:
   - ".github/**"
   - "codecov.yml"
+  - "examples/**"
   - "packages/genui/**"
   - "pnpm-lock.yaml"
   - "rstest.config.ts"
+  - "**/__swc_snapshots__/**"
+  - "**/__snapshots__/**"
 
 fixes:
   - "/home/runner/_work/lynx-stack::"

examples/gesture/package.json

@@ -17,7 +17,7 @@
     "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
     "@lynx-js/react-rsbuild-plugin": "workspace:*",
     "@lynx-js/rspeedy": "workspace:*",
-    "@lynx-js/types": "3.7.0",
+    "@lynx-js/types": "3.10.2-alpha.0",
     "@types/react": "^18.3.28"
   }
 }

examples/motion/package.json

@@ -16,7 +16,7 @@
     "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
     "@lynx-js/react-rsbuild-plugin": "workspace:*",
     "@lynx-js/rspeedy": "workspace:*",
-    "@lynx-js/types": "3.7.0",
+    "@lynx-js/types": "3.10.2-alpha.0",
     "@types/react": "^18.3.28"
   }
 }

examples/react-compiler/package.json

@@ -15,7 +15,7 @@
     "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
     "@lynx-js/react-rsbuild-plugin": "workspace:*",
     "@lynx-js/rspeedy": "workspace:*",
-    "@lynx-js/types": "3.7.0",
+    "@lynx-js/types": "3.10.2-alpha.0",
     "@rsbuild/plugin-babel": "1.1.0",
     "@types/react": "^18.3.28",
     "babel-plugin-react-compiler": "0.0.0-experimental-fe727a3-20250909"

examples/react-element-template/package.json

@@ -15,7 +15,7 @@
     "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
     "@lynx-js/react-rsbuild-plugin": "workspace:*",
     "@lynx-js/rspeedy": "workspace:*",
-    "@lynx-js/types": "3.7.0",
+    "@lynx-js/types": "3.10.2-alpha.0",
     "@types/react": "^18.3.28"
   }
 }

examples/react-element/package.json

@@ -15,7 +15,7 @@
     "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
     "@lynx-js/react-rsbuild-plugin": "workspace:*",
     "@lynx-js/rspeedy": "workspace:*",
-    "@lynx-js/types": "3.7.0",
+    "@lynx-js/types": "3.10.2-alpha.0",
     "@types/react": "^18.3.28"
   }
 }

examples/react-externals/package.json

@@ -20,7 +20,7 @@
     "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
     "@lynx-js/react-rsbuild-plugin": "workspace:*",
     "@lynx-js/rspeedy": "workspace:*",
-    "@lynx-js/types": "3.7.0",
+    "@lynx-js/types": "3.10.2-alpha.0",
     "@types/react": "^18.3.28",
     "cross-env": "^7.0.3"
   }

examples/react-lazy-bundle-standalone/lynx.config.consumer.js

@@ -9,6 +9,7 @@ import { detectLanHost, producerDevPort } from './demo-ports.js';
 
 const projectRoot = path.dirname(fileURLToPath(import.meta.url));
 const enableBundleAnalysis = !!process.env['RSPEEDY_BUNDLE_ANALYSIS'];
+const enableFetchBundle = !!process.env['LAZY_BUNDLE_FETCHBUNDLE'];
 const producerHost = detectLanHost();
 
 export default defineConfig({
@@ -35,7 +36,9 @@ export default defineConfig({
     },
   },
   plugins: [
-    pluginReactLynx(),
+    pluginReactLynx({
+      ...(enableFetchBundle ? { engineVersion: '3.8' } : {}),
+    }),
     pluginQRCode({
       schema(url) {
         return `${url}?fullscreen=true`;

examples/react-lazy-bundle-standalone/lynx.config.producer.js

@@ -8,12 +8,15 @@ import { detectLanHost, producerDevPort } from './demo-ports.js';
 
 const projectRoot = path.dirname(fileURLToPath(import.meta.url));
 const enableBundleAnalysis = !!process.env['RSPEEDY_BUNDLE_ANALYSIS'];
+const enableFetchBundle = !!process.env['LAZY_BUNDLE_FETCHBUNDLE'];
 const producerPublicPath = `http://${detectLanHost()}:${producerDevPort}/`;
 
 export default defineConfig({
   source: {
     entry: {
       LazyComponent: './src/LazyComponent.tsx',
+      LazyComponentSync: './src/LazyComponentSync.tsx',
+      LazyComponentAsync: './src/LazyComponentAsync.tsx',
       add: './src/utils/add.ts',
       minus: './src/utils/minus.ts',
       dynamic: './src/utils/dynamic.ts',
@@ -35,6 +38,7 @@ export default defineConfig({
   plugins: [
     pluginReactLynx({
       experimental_isLazyBundle: true,
+      ...(enableFetchBundle ? { engineVersion: '3.8' } : {}),
     }),
   ],
   environments: {

examples/react-lazy-bundle-standalone/package.json

@@ -6,12 +6,15 @@
   "scripts": {
     "build": "pnpm run --parallel \"/^build:(producer|consumer)$/\"",
     "build:consumer": "rspeedy build --config lynx.config.consumer.js",
+    "build:fetchbundle": "cross-env LAZY_BUNDLE_FETCHBUNDLE=1 pnpm run build",
     "build:producer": "rspeedy build --config lynx.config.producer.js",
     "dev": "node scripts/serve.mjs dev",
     "dev:consumer": "rspeedy dev --config lynx.config.consumer.js",
+    "dev:fetchbundle": "cross-env LAZY_BUNDLE_FETCHBUNDLE=1 node scripts/serve.mjs dev",
     "dev:producer": "rspeedy dev --config lynx.config.producer.js",
     "preview": "node scripts/serve.mjs preview",
     "preview:consumer": "rspeedy preview --config lynx.config.consumer.js",
+    "preview:fetchbundle": "cross-env LAZY_BUNDLE_FETCHBUNDLE=1 node scripts/serve.mjs preview",
     "preview:producer": "rspeedy preview --config lynx.config.producer.js"
   },
   "dependencies": {
@@ -22,7 +25,8 @@
     "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
     "@lynx-js/react-rsbuild-plugin": "workspace:*",
     "@lynx-js/rspeedy": "workspace:*",
-    "@lynx-js/types": "3.7.0",
-    "@types/react": "^18.3.28"
+    "@lynx-js/types": "3.10.2-alpha.0",
+    "@types/react": "^18.3.28",
+    "cross-env": "^7.0.3"
   }
 }

examples/react-lazy-bundle-standalone/src/App.tsx

@@ -4,13 +4,40 @@ import { createProducerBundleUrl } from './entry-url.js';
 
 import './App.css';
 
-const LazyComponent = lazy(() =>
-  import(createProducerBundleUrl('LazyComponent.lynx.bundle'), {
-    with: {
-      type: 'component',
-    },
-  })
-);
+let LazyComponentDemo: () => JSX.Element;
+if (__LAZY_BUNDLE_FETCHER__ === 'FetchBundle') {
+  const LazyComponentSync = lazy(() =>
+    import(createProducerBundleUrl('LazyComponentSync.lynx.bundle'), {
+      with: { type: 'component', mode: 'sync' },
+    })
+  );
+  const LazyComponentAsync = lazy(() =>
+    import(createProducerBundleUrl('LazyComponentAsync.lynx.bundle'), {
+      with: { type: 'component', mode: 'async' },
+    })
+  );
+  LazyComponentDemo = () => (
+    <>
+      <Suspense fallback={<text>Loading sync...</text>}>
+        <LazyComponentSync />
+      </Suspense>
+      <Suspense fallback={<text>Loading async...</text>}>
+        <LazyComponentAsync />
+      </Suspense>
+    </>
+  );
+} else {
+  const LazyComponent = lazy(() =>
+    import(createProducerBundleUrl('LazyComponent.lynx.bundle'), {
+      with: { type: 'component' },
+    })
+  );
+  LazyComponentDemo = () => (
+    <Suspense fallback={<text>Loading...</text>}>
+      <LazyComponent />
+    </Suspense>
+  );
+}
 
 export function App() {
   useEffect(() => {
@@ -43,9 +70,7 @@ export function App() {
           <text className='Subtitle'>on Lynx</text>
         </view>
         <view className='Suspense'>
-          <Suspense fallback={<text>Loading...</text>}>
-            <LazyComponent />
-          </Suspense>
+          <LazyComponentDemo />
         </view>
       </view>
     </view>

examples/react-lazy-bundle-standalone/src/LazyComponentAsync.css

@@ -0,0 +1,4 @@
+.LazyComponentAsync {
+  font-weight: 700;
+  color: cyan;
+}

examples/react-lazy-bundle-standalone/src/LazyComponentAsync.tsx

@@ -0,0 +1,9 @@
+import './LazyComponentAsync.css';
+
+export default function LazyComponentAsync() {
+  return (
+    <view>
+      <text className='LazyComponentAsync'>LazyComponentAsync</text>
+    </view>
+  );
+}

examples/react-lazy-bundle-standalone/src/LazyComponentSync.css

@@ -0,0 +1,4 @@
+.LazyComponentSync {
+  font-weight: 700;
+  color: yellow;
+}

examples/react-lazy-bundle-standalone/src/LazyComponentSync.tsx

@@ -0,0 +1,9 @@
+import './LazyComponentSync.css';
+
+export default function LazyComponentSync() {
+  return (
+    <view>
+      <text className='LazyComponentSync'>LazyComponentSync</text>
+    </view>
+  );
+}

examples/react-lazy-bundle-standalone/src/entry-url.ts

@@ -1,6 +1,8 @@
 export function createProducerBundleUrl(bundleFileName: string): string {
-  if (process.env.NODE_ENV === 'production') {
-    return `http://${process.env.LYNX_STANDALONE_PRODUCER_HOST}:${process.env.LYNX_STANDALONE_PRODUCER_PORT}/${bundleFileName}`;
+  if (process.env['NODE_ENV'] === 'production') {
+    return `http://${process.env['LYNX_STANDALONE_PRODUCER_HOST']}:${
+      process.env['LYNX_STANDALONE_PRODUCER_PORT']
+    }/${bundleFileName}`;
   }
   return `${__webpack_public_path__}producer/${bundleFileName}`;
 }

examples/react-lazy-bundle/lynx.config.js

@@ -1,12 +1,38 @@
+import os from 'node:os';
+
 import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin';
 import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';
 import { defineConfig } from '@lynx-js/rspeedy';
 
 const enableBundleAnalysis = !!process.env['RSPEEDY_BUNDLE_ANALYSIS'];
+const enableFetchBundle = !!process.env['LAZY_BUNDLE_FETCHBUNDLE'];
+
+function detectLanHost() {
+  for (const ifaces of Object.values(os.networkInterfaces())) {
+    for (const iface of ifaces ?? []) {
+      if (iface.family === 'IPv4' && !iface.internal) {
+        return iface.address;
+      }
+    }
+  }
+  throw new Error('No external IPv4 interface found for lazy bundle host.');
+}
+
+const port = Number(process.env['LYNX_LAZY_BUNDLE_PORT'] ?? '54173');
+const assetPrefix = `http://${detectLanHost()}:${port}/`;
 
 export default defineConfig({
+  output: {
+    assetPrefix,
+  },
+  server: {
+    port,
+    strictPort: true,
+  },
   plugins: [
-    pluginReactLynx(),
+    pluginReactLynx({
+      ...(enableFetchBundle ? { engineVersion: '3.8' } : {}),
+    }),
     pluginQRCode({
       schema(url) {
         // We use `?fullscreen=true` to open the page in LynxExplorer in full screen mode

examples/react-lazy-bundle/package.json

@@ -5,7 +5,11 @@
   "type": "module",
   "scripts": {
     "build": "rspeedy build",
-    "dev": "rspeedy dev"
+    "build:fetchbundle": "cross-env LAZY_BUNDLE_FETCHBUNDLE=1 rspeedy build",
+    "dev": "rspeedy dev",
+    "dev:fetchbundle": "cross-env LAZY_BUNDLE_FETCHBUNDLE=1 rspeedy dev",
+    "preview": "rspeedy preview",
+    "preview:fetchbundle": "cross-env LAZY_BUNDLE_FETCHBUNDLE=1 rspeedy preview"
   },
   "dependencies": {
     "@lynx-js/react": "workspace:*"
@@ -15,7 +19,8 @@
     "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
     "@lynx-js/react-rsbuild-plugin": "workspace:*",
     "@lynx-js/rspeedy": "workspace:*",
-    "@lynx-js/types": "3.7.0",
-    "@types/react": "^18.3.28"
+    "@lynx-js/types": "3.10.2-alpha.0",
+    "@types/react": "^18.3.28",
+    "cross-env": "^7.0.3"
   }
 }

examples/react-lazy-bundle/src/App.tsx

@@ -2,7 +2,32 @@ import { Suspense, lazy, useEffect } from '@lynx-js/react';
 
 import './App.css';
 
-const LazyComponent = lazy(() => import('./LazyComponent.js'));
+let LazyComponentDemo: () => JSX.Element;
+if (__LAZY_BUNDLE_FETCHER__ === 'FetchBundle') {
+  const LazyComponentSync = lazy(() =>
+    import('./LazyComponentSync.js', { with: { mode: 'sync' } })
+  );
+  const LazyComponentAsync = lazy(() =>
+    import('./LazyComponentAsync.js', { with: { mode: 'async' } })
+  );
+  LazyComponentDemo = () => (
+    <>
+      <Suspense fallback={<text>Loading sync...</text>}>
+        <LazyComponentSync />
+      </Suspense>
+      <Suspense fallback={<text>Loading async...</text>}>
+        <LazyComponentAsync />
+      </Suspense>
+    </>
+  );
+} else {
+  const LazyComponent = lazy(() => import('./LazyComponent.js'));
+  LazyComponentDemo = () => (
+    <Suspense fallback={<text>Loading...</text>}>
+      <LazyComponent />
+    </Suspense>
+  );
+}
 
 export function App() {
   useEffect(() => {
@@ -27,9 +52,7 @@ export function App() {
           <text className='Subtitle'>on Lynx</text>
         </view>
         <view className='Suspense'>
-          <Suspense fallback={<text>Loading...</text>}>
-            <LazyComponent />
-          </Suspense>
+          <LazyComponentDemo />
         </view>
       </view>
     </view>

examples/react-lazy-bundle/src/LazyComponentAsync.css

@@ -0,0 +1,4 @@
+.LazyComponentAsync {
+  font-weight: 700;
+  color: cyan;
+}

examples/react-lazy-bundle/src/LazyComponentAsync.tsx

@@ -0,0 +1,9 @@
+import './LazyComponentAsync.css';
+
+export default function LazyComponentAsync() {
+  return (
+    <view>
+      <text className='LazyComponentAsync'>LazyComponentAsync</text>
+    </view>
+  );
+}

examples/react-lazy-bundle/src/LazyComponentSync.css

@@ -0,0 +1,4 @@
+.LazyComponentSync {
+  font-weight: 700;
+  color: yellow;
+}