feat: extend inlineScripts type

.changeset/tangy-ends-act.md

@@ -0,0 +1,34 @@
+---
+"@lynx-js/rspeedy": patch
+"@lynx-js/react-rsbuild-plugin": patch
+"@lynx-js/react-webpack-plugin": patch
+"@lynx-js/template-webpack-plugin": patch
+---
+
+Enable fine-grained control for `output.inlineScripts`
+
+```ts
+type InlineChunkTestFunction = (params: {
+  size: number;
+  name: string;
+}) => boolean;
+
+type InlineChunkTest = RegExp | InlineChunkTestFunction;
+
+type InlineChunkConfig =
+  | boolean
+  | InlineChunkTest
+  | { enable?: boolean | 'auto'; test: InlineChunkTest };
+```
+
+```ts
+import { defineConfig } from '@lynx-js/rspeedy';
+
+export default defineConfig({
+  output: {
+    inlineScripts: ({ name, size }) => {
+      return name.includes('foo') && size < 1000;
+    },
+  },
+});
+```

packages/rspeedy/core/etc/rspeedy.api.md

@@ -6,6 +6,7 @@
 
 import type { CreateRsbuildOptions } from '@rsbuild/core';
 import type { DistPathConfig } from '@rsbuild/core';
+import type { InlineChunkConfig } from '@rsbuild/core';
 import { logger } from '@rsbuild/core';
 import type { PerformanceConfig } from '@rsbuild/core';
 import type { RsbuildConfig } from '@rsbuild/core';
@@ -232,7 +233,7 @@ export interface Output {
     distPath?: DistPath | undefined;
     filename?: string | Filename | undefined;
     filenameHash?: boolean | string | undefined;
-    inlineScripts?: boolean | undefined;
+    inlineScripts?: InlineChunkConfig | undefined;
     legalComments?: 'none' | 'inline' | 'linked' | undefined;
     minify?: Minify | boolean | undefined;
     sourceMap?: boolean | SourceMap | undefined;

packages/rspeedy/core/src/config/output/index.ts

@@ -1,7 +1,7 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
-import type { Rspack } from '@rsbuild/core'
+import type { InlineChunkConfig, Rspack } from '@rsbuild/core'
 
 import type { CssModules } from './css-modules.js'
 import type { DistPath } from './dist-path.js'
@@ -304,11 +304,15 @@ export interface Output {
    *
    * @remarks
    *
-   * If no value is provided, the default value would be `true`.
+   * If no value is provided, the default value would be `true`, which means all background thread scripts will be inlined.
    *
    * This is different with {@link https://rsbuild.dev/config/output/inline-scripts | output.inlineScripts } since we normally want to inline scripts in Lynx bundle (`.lynx.bundle`).
    *
-   * Only background thread scripts can remain non-inlined, whereas the main thread script is always inlined.
+   * There are two points that need to be especially noted:
+   *
+   * 1. Only background thread scripts can remain non-inlined, whereas the main thread script is always inlined.
+   *
+   * 2. Currently, when `experimental_isLazyBundle` is enabled, `inlineScripts` will always be `true`.
    *
    * @example
    *
@@ -323,7 +327,7 @@ export interface Output {
    * })
    * ```
    */
-  inlineScripts?: boolean | undefined
+  inlineScripts?: InlineChunkConfig | undefined
 
   /**
    * The {@link Output.legalComments} controls how to handle the legal comment.

packages/rspeedy/core/test/config/output.test-d.ts

@@ -182,6 +182,26 @@ describe('Config - Output', () => {
     assertType<Output>({
       inlineScripts: false,
     })
+    assertType<Output>({
+      inlineScripts: /[\\/]background\.\w+\.js$/,
+    })
+    assertType<Output>({
+      inlineScripts: ({ size }) => {
+        return size < 10 * 1000
+      },
+    })
+    assertType<Output>({
+      inlineScripts: {
+        enable: 'auto',
+        test: /[\\/]background\.\w+\.js$/,
+      },
+    })
+    assertType<Output>({
+      inlineScripts: {
+        enable: true,
+        test: /[\\/]background\.\w+\.js$/,
+      },
+    })
   })
 
   test('output.legalComments', () => {

packages/rspeedy/core/test/config/validate.test.ts

@@ -835,6 +835,24 @@ describe('Config Validation', () => {
         { distPath: { svg: 'svg' } },
         { inlineScripts: true },
         { inlineScripts: false },
+        { inlineScripts: /[\\/]background\.\w+\.js$/ },
+        {
+          inlineScripts: ({ size }) => {
+            return size < 10 * 1000
+          },
+        },
+        {
+          inlineScripts: {
+            enable: 'auto',
+            test: /[\\/]background\.\w+\.js$/,
+          },
+        },
+        {
+          inlineScripts: {
+            enable: true,
+            test: /[\\/]background\.\w+\.js$/,
+          },
+        },
         { legalComments: 'inline' },
         { legalComments: 'none' },
         { legalComments: 'linked' },
@@ -1099,15 +1117,67 @@ describe('Config Validation', () => {
           ]
         `)
 
-      expect(() => validate({ output: { inlineScripts: null } }))
-        .toThrowErrorMatchingInlineSnapshot(`
-          [Error: Invalid configuration.
+      expect(() =>
+        validate({
+          output: {
+            inlineScripts: {
+              enable: 123,
+            },
+          },
+        })
+      ).toThrowErrorMatchingInlineSnapshot(`
+        [Error: Invalid configuration.
 
-          Invalid config on \`$input.output.inlineScripts\`.
-            - Expect to be (boolean | undefined)
-            - Got: null
-          ]
-        `)
+        Invalid config on \`$input.output.inlineScripts.enable\`.
+          - Expect to be ("auto" | boolean | undefined)
+          - Got: number
+
+        Invalid config on \`$input.output.inlineScripts.test\`.
+          - Expect to be RegExp
+          - Got: undefined
+        ]
+      `)
+
+      expect(() =>
+        validate({
+          output: {
+            inlineScripts: {
+              enable: true,
+            },
+          },
+        })
+      ).toThrowErrorMatchingInlineSnapshot(`
+        [Error: Invalid configuration.
+
+        Invalid config on \`$input.output.inlineScripts.test\`.
+          - Expect to be RegExp
+          - Got: undefined
+        ]
+      `)
+
+      expect(() =>
+        validate({
+          output: {
+            inlineScripts: {
+              enable: true,
+              test: 123,
+            },
+          },
+        })
+      ).toThrowErrorMatchingInlineSnapshot(`
+        [Error: Invalid configuration.
+
+        Invalid config on \`$input.output.inlineScripts.test\`.
+          - Expect to be RegExp
+          - Got: number
+        ]
+      `)
+
+      //  FIXME:
+      //  ubuntu will matchingInlineSnapshot _type.o111
+      //  macos will matchingInlineSnapshot _type.o110
+      expect(() => validate({ output: { inlineScripts: null } }))
+        .toThrowError()
 
       expect(() => validate({ output: { legalComments: [null] } }))
         .toThrowErrorMatchingInlineSnapshot(`

packages/rspeedy/plugin-react/src/entry.ts

@@ -197,11 +197,20 @@ export function applyEntry(
         .end()
     })
 
+    let finalFirstScreenSyncTiming = firstScreenSyncTiming
+
     if (isLynx) {
-      const inlineScripts =
-        typeof environment.config.output?.inlineScripts === 'boolean'
-          ? environment.config.output.inlineScripts
-          : true
+      let inlineScripts
+      if (experimental_isLazyBundle) {
+        // TODO: support inlineScripts in lazyBundle
+        inlineScripts = true
+      } else {
+        inlineScripts = environment.config.output?.inlineScripts ?? true
+      }
+
+      if (inlineScripts !== true) {
+        finalFirstScreenSyncTiming = 'jsReady'
+      }
 
       chain
         .plugin(PLUGIN_NAME_RUNTIME_WRAPPER)
@@ -246,7 +255,7 @@ export function applyEntry(
       .use(ReactWebpackPlugin, [{
         disableCreateSelectorQueryIncompatibleWarning: compat
           ?.disableCreateSelectorQueryIncompatibleWarning ?? false,
-        firstScreenSyncTiming,
+        firstScreenSyncTiming: finalFirstScreenSyncTiming,
         enableSSR,
         mainThreadChunks,
         extractStr,

packages/webpack/template-webpack-plugin/etc/template-webpack-plugin.api.md

@@ -87,8 +87,10 @@ export class LynxEncodePlugin {
 
 // @public
 export interface LynxEncodePluginOptions {
+    // Warning: (ae-forgotten-export) The symbol "InlineChunkConfig" needs to be exported by the entry point index.d.ts
+    //
     // (undocumented)
-    inlineScripts?: boolean | undefined;
+    inlineScripts?: InlineChunkConfig | undefined;
 }
 
 // @public
@@ -184,6 +186,6 @@ export class WebEncodePlugin {
 
 // Warnings were encountered during analysis:
 //
-// lib/LynxTemplatePlugin.d.ts:63:9 - (ae-forgotten-export) The symbol "EncodeRawData" needs to be exported by the entry point index.d.ts
+// lib/LynxTemplatePlugin.d.ts:67:9 - (ae-forgotten-export) The symbol "EncodeRawData" needs to be exported by the entry point index.d.ts
 
 ```