feat: experimental lazy-compilation support (#457)

* feat(repack): lazy-compilation

* chore: add changeset

* docs(repack): add guide for lazy compilation

* fix(TesterApp): fix tests

* docs: add devServer condition to lazy compilation docs

* docs: add example of code-splitting to lazy compilation

.changeset/stale-panthers-taste.md

@@ -0,0 +1,5 @@
+---
+"@callstack/repack": minor
+---
+
+Support lazy-compilation for dynamic imports

packages/TesterApp/__tests__/start.test.ts

@@ -29,6 +29,7 @@ beforeAll(async () => {
     port,
     silent: true,
     logFile: path.join(TMP_DIR, 'server.log'),
+    webpackConfig: path.join(__dirname, './webpack.config.mjs'),
   };
 
   const { stop } = await start.func([], config as Config, args as Args);

packages/TesterApp/__tests__/webpack.config.mjs

@@ -6,5 +6,9 @@ export default async (env) => {
       ...config.output,
       path: process.env.TEST_WEBPACK_OUTPUT_DIR,
     },
+    experiments: {
+      ...config.output.experiments,
+      lazyCompilation: false,
+    },
   };
 };

packages/TesterApp/package.json

@@ -40,6 +40,7 @@
     "http-server": "^14.1.1",
     "metro-react-native-babel-preset": "^0.73.9",
     "node-fetch": "^3.2.6",
+    "react-native-event-source": "^1.1.0",
     "terser-webpack-plugin": "^5.3.3",
     "typescript": "^4.8.4",
     "vitest": "^0.15.1",

packages/TesterApp/webpack.config.mjs

@@ -55,6 +55,12 @@ export default (env) => {
      */
     devtool: false,
     context,
+    experiments: {
+      lazyCompilation: devServer && {
+        imports: true,
+        entries: false,
+      },
+    },
     /**
      * `getInitializationEntries` will return necessary entries with setup and initialization code.
      * If you don't want to use Hot Module Replacement, set `hmr` option to `false`. By default,
@@ -84,6 +90,17 @@ export default (env) => {
         'react-native': reactNativePath,
         '@babel/runtime': path.join(dirname, 'node_modules/@babel/runtime'),
       },
+      /**
+       * Because Re.Pack is symlinked from it's workspace, we need to provide a fallback for
+       * `react-native-event-source` package used for lazyCompilation. This is not needed in
+       * normal projects.
+       */
+      fallback: {
+        'react-native-event-source': path.join(
+          dirname,
+          'node_modules/react-native-event-source'
+        ),
+      },
     },
     /**
      * Configures output.

packages/repack/package.json

@@ -107,6 +107,7 @@
     "headers-polyfill": "^3.0.7",
     "jest": "^28.1.1",
     "react-native": "^0.64.1",
+    "react-native-event-source": "^1.1.0",
     "terser-webpack-plugin": "^5.1.3",
     "typedoc": "^0.22.17",
     "typedoc-plugin-markdown": "^3.12.1",

packages/repack/src/webpack/plugins/DevelopmentPlugin.ts

@@ -40,6 +40,8 @@ export class DevelopmentPlugin implements WebpackPlugin {
    * @param compiler Webpack compiler instance.
    */
   apply(compiler: webpack.Compiler) {
+    const logger = compiler.getInfrastructureLogger('DevelopmentPlugin');
+
     if (!this.config?.devServer) {
       return;
     }
@@ -115,5 +117,32 @@ export class DevelopmentPlugin implements WebpackPlugin {
         }
       );
     }
+
+    if (compiler.options.experiments?.lazyCompilation) {
+      if (compiler.options.experiments.lazyCompilation.entries !== false) {
+        compiler.hooks.initialize.tap('DevelopmentPlugin', () => {
+          logger.error(
+            'You have enabled lazyCompilation for entrypoints which is not supported. ' +
+              'Lazy compilation is supported only for dynamic imports. ' +
+              'You can fix this by adding { entries: false } to experiments.lazyCompilation configuration object inside webpack.config.'
+          );
+        });
+      }
+
+      try {
+        require.resolve('react-native-event-source');
+      } catch (error) {
+        compiler.hooks.initialize.tap('DevelopmentPlugin', () => {
+          logger.error(
+            "You have enabled lazyCompilation but 'react-native-event-source' was not found in your devDependencies. " +
+              'Please install it via your package manager and try again.'
+          );
+        });
+      }
+
+      new webpack.ProvidePlugin({
+        EventSource: ['react-native-event-source', 'default'],
+      }).apply(compiler);
+    }
   }
 }

website/docs/configuration/guides/lazy-compilation.mdx

@@ -0,0 +1,107 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Lazy Compilation
+
+:::caution
+
+Lazy compilation is an experimental feature of webpack, therefore it is considered experimental in Re.Pack as well.
+
+If you encounter an issue while using lazy compilation, it's advisable to disable it temporarily before reporting the problem to ensure it's not the underlying cause.
+
+:::
+
+If you are using [Code splitting](/docs/code-splitting/usage)
+and have async chunks in your app, imported like this:
+
+```js
+const myChunk = await import('./myChunk.js');
+```
+
+You might benefit from using lazy compilation in development.
+It will cause all dynamic imports in your app to be compiled only when necessary, reducing the time of your initial app startup.
+
+:::danger
+
+Lazy compilation is supported only for dynamic imports. While webpack has an option to also compile entrypoints on demand, this will not work in React Native environment, and will result in your app's bundle compiling with errors.
+
+:::
+
+:::caution
+
+Prefetching chunks with `ScriptManager` with lazy compilation might result in confusing behaviour. When fetched via `ScriptManager.shared.prefetchScript`, the chunk will be downloaded, but it will not have the desired contents inside. Only upon evaluation of that chunk, the compilation will be triggered and the result will be sent to your client.
+
+:::
+
+## Usage
+
+First, install the `react-native-event-source` package to your `devDependencies`:
+
+<Tabs>
+<TabItem value="npm" label="npm" default>
+
+```bash
+npm install -D react-native-event-source
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash
+yarn add -D react-native-event-source
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm add -D react-native-event-source
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash
+bun add -D react-native-event-source
+```
+
+</TabItem>
+</Tabs>
+
+:::info
+
+`react-native-event-source` is a polyfill for `EventSource`
+which is used by webpack to communicate with the development server.
+It is required for lazy compilation to work.
+:::
+
+Then, add the following to your `webpack.config` file:
+
+```js
+/* ... */
+
+export default (env) => {
+  /* ... */
+
+  return {
+    /* ... */
+
+    module: {
+      experiments: [
+        lazyCompilation: devServer && {
+            imports: true,
+            entries: false,
+        }
+      ],
+    },
+
+    /* ... */
+  };
+};
+```
+
+:::tip
+
+You can read more about Webpack's lazy compilation feature here: https://webpack.js.org/configuration/experiments/#experimentslazycompilation
+
+:::

website/sidebars.js

@@ -77,6 +77,7 @@ module.exports = {
         'configuration/guides/svg',
         'configuration/guides/inline-assets',
         'configuration/guides/remote-assets',
+        'configuration/guides/lazy-compilation',
       ],
     },
   ],

yarn.lock

@@ -4945,6 +4945,7 @@ __metadata:
     mime-types: ^2.1.35
     pretty-format: ^26.6.2
     react-native: ^0.64.1
+    react-native-event-source: ^1.1.0
     react-refresh: ^0.14.0
     schema-utils: ^3.0.0
     shallowequal: ^1.1.0
@@ -27521,6 +27522,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"react-native-event-source@npm:^1.1.0":
+  version: 1.1.0
+  resolution: "react-native-event-source@npm:1.1.0"
+  checksum: 303f369bcaf10961b51212e7d39b266bdf37af2022e0def6ec8f12e416d1dd4d62bbadb7490671eaba1f29ea8b4f91864bf5b4299aca36545a89c9e813e15a27
+  languageName: node
+  linkType: hard
+
 "react-native-gradle-plugin@npm:^0.71.18":
   version: 0.71.18
   resolution: "react-native-gradle-plugin@npm:0.71.18"
@@ -31063,6 +31071,7 @@ __metadata:
     node-fetch: ^3.2.6
     react: 18.2.0
     react-native: ^0.71.8
+    react-native-event-source: ^1.1.0
     react-native-svg: ^13.7.0
     terser-webpack-plugin: ^5.3.3
     typescript: ^4.8.4