feat(rspeedy): support source.preEntry (#750)

<!--
  Thank you for submitting a pull request!

We appreciate the time and effort you have invested in making these
changes. Please ensure that you provide enough information to allow
others to review your pull request.

Upon submission, your pull request will be automatically assigned with
reviewers.

If you want to learn more about contributing to this project, please
visit:
https://github.com/lynx-family/lynx-stack/blob/main/CONTRIBUTING.md.
-->

## Summary

<!-- Can you explain the reasoning behind implementing this change? What
problem or issue does this pull request resolve? -->

<!-- It would be helpful if you could provide any relevant context, such
as GitHub issues or related discussions. -->

close #299

When we set `preEntry` in the `lynx.config.js`:

```js
  source: {
    entry: {
      main: './src/index.tsx',
      main2: './src/index.tsx',
    },
    preEntry: './src/normalize.css',
  },
```

The `rspack.config.lynx.mjs` will automatically generate entries with
the following structure:
```js
    main__main-thread: {
      layer: 'react:main-thread',
      'import': [
        '/hotModuleReplacement.lepus.cjs',
        './src/normalize.css',
        './src/index.tsx'
      ],
      filename: '.rspeedy/main/main-thread.js'
    },
    main: {
      layer: 'react:background',
      'import': [
        '@lynx-js/react/refresh',
        '@lynx-js/webpack-dev-transport/client',
        '@rspack/core/hot/dev-server',
        './src/normalize.css',
        './src/index.tsx'
      ],
      filename: '.rspeedy/main/background.js'
    },
    main2__main-thread: {
      layer: 'react:main-thread',
      'import': [
        '/hotModuleReplacement.lepus.cjs',
        './src/normalize.css',
        './src/index.tsx'
      ],
      filename: '.rspeedy/main/main-thread.js'
    },
    main2: {
      layer: 'react:background',
      'import': [
        '@lynx-js/react/refresh',
        '@lynx-js/webpack-dev-transport/client',
        '@rspack/core/hot/dev-server',
        './src/normalize.css',
        './src/index.tsx'
      ],
      filename: '.rspeedy/main/background.js'
    },
```

The CSS files (`main.css` and `main2.css`) will contain:
```css
/* from preEntry normalize.css */
.test {
  background-color: red;
}

/* The others */
:root {
  background-color: #000;
  --color-text: #fff;
}
```


## Checklist

<!--- Check and mark with an "x" -->

- [x] Tests updated (or not required).
- [x] Documentation updated (or not required).

---------

Signed-off-by: BitterGourd <[email protected]>

Author: gaoachao

.changeset/cold-terms-battle.md

@@ -0,0 +1,19 @@
+---
+"@lynx-js/rspeedy": patch
+---
+
+Support `source.preEntry`.
+
+Add a script before the entry file of each page. This script will be executed before the page code.
+It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.
+
+example：
+
+```js
+import { defineConfig } from '@lynx-js/rspeedy';
+export default defineConfig({
+  source: {
+    preEntry: './src/polyfill.ts',
+  },
+});
+```

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

@@ -280,6 +280,7 @@ export interface Source {
     entry?: Entry | undefined;
     exclude?: Rspack.RuleSetCondition[] | undefined;
     include?: Rspack.RuleSetCondition[] | undefined;
+    preEntry?: string | string[] | undefined;
     transformImport?: TransformImport[] | undefined;
     tsconfigPath?: string | undefined;
 }

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

@@ -68,6 +68,8 @@ export function toRsbuildConfig(
 
       include: config.source?.include,
 
+      preEntry: config.source?.preEntry,
+
       transformImport: config.source?.transformImport,
 
       tsconfigPath: config.source?.tsconfigPath,

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

@@ -429,6 +429,29 @@ export interface Source {
    */
   include?: Rspack.RuleSetCondition[] | undefined
 
+  /**
+   * Add a script before the entry file of each page. This script will be executed before the page code.
+   * It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.
+   *
+   * @remarks
+   *
+   * See {@link https://rsbuild.dev/config/source/pre-entry | source.preEntry} for more details.
+   *
+   * @example
+   *
+   * Relative path will be resolved relative to the project root directory.
+   *
+   * ```js
+   * import { defineConfig } from '@lynx-js/rspeedy'
+   * export default defineConfig({
+   *   source: {
+   *     preEntry: './src/polyfill.ts',
+   *   },
+   * })
+   * ```
+   */
+  preEntry?: string | string[] | undefined
+
   /**
    * The {@link TransformImport} option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by {@link https://npmjs.com/package/babel-plugin-import | babel-plugin-import}.
    *

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

@@ -803,5 +803,34 @@ describe('Config - toRsBuildConfig', () => {
         }
       `)
     })
+
+    test('source.preEntry string', () => {
+      const rsbuildConfig = toRsbuildConfig({
+        source: {
+          preEntry: './src/polyfill.ts',
+        },
+      })
+
+      expect(rsbuildConfig.source?.preEntry).toMatchInlineSnapshot(
+        `"./src/polyfill.ts"`,
+      )
+    })
+
+    test('source.preEntry string[]', () => {
+      const rsbuildConfig = toRsbuildConfig({
+        source: {
+          preEntry: ['./src/polyfill-a.ts', './src/polyfill-b.ts'],
+        },
+      })
+
+      expect(rsbuildConfig.source?.preEntry).toMatchInlineSnapshot(
+        `
+        [
+          "./src/polyfill-a.ts",
+          "./src/polyfill-b.ts",
+        ]
+      `,
+      )
+    })
   })
 })

packages/rspeedy/core/test/config/source/preEntry.test-d.ts

@@ -0,0 +1,22 @@
+// 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 { assertType, describe, test } from 'vitest'
+
+import type { Source } from '../../../src/index.js'
+
+describe('Config - source.preEntry', () => {
+  test('preEntry', () => {
+    assertType<Source>({
+      preEntry: undefined,
+    })
+
+    assertType<Source>({
+      preEntry: './src/polyfill.ts',
+    })
+
+    assertType<Source>({
+      preEntry: ['./src/polyfill-a.ts', './src/polyfill-b.ts'],
+    })
+  })
+})

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

@@ -1822,6 +1822,23 @@ describe('Config Validation', () => {
     test('valid type', () => {
       const cases: Source[] = [
         {},
+        {
+          assetsInclude: 'json5',
+        },
+        {
+          assetsInclude: /\.json5$/,
+        },
+        {
+          assetsInclude: [/\.json5$/, /\.pdf$/],
+        },
+        {
+          assetsInclude: (value: string) => value.endsWith('.json5'),
+        },
+        {
+          assetsInclude: {
+            not: /\.json5$/,
+          },
+        },
         { decorators: {} },
         { decorators: { version: '2022-03' } },
         { decorators: { version: 'legacy' } },
@@ -1879,6 +1896,12 @@ describe('Config Validation', () => {
             { not: /core-js/ },
           ],
         },
+        {
+          preEntry: './src/polyfill.ts',
+        },
+        {
+          preEntry: ['./src/polyfill-a.ts', './src/polyfill-b.ts'],
+        },
         { transformImport: [] },
         {
           transformImport: [
@@ -1903,23 +1926,6 @@ describe('Config Validation', () => {
             },
           ],
         },
-        {
-          assetsInclude: 'json5',
-        },
-        {
-          assetsInclude: /\.json5$/,
-        },
-        {
-          assetsInclude: [/\.json5$/, /\.pdf$/],
-        },
-        {
-          assetsInclude: (value: string) => value.endsWith('.json5'),
-        },
-        {
-          assetsInclude: {
-            not: /\.json5$/,
-          },
-        },
       ]
 
       cases.forEach(source => {
@@ -2132,6 +2138,16 @@ describe('Config Validation', () => {
           ]
         `)
 
+      expect(() => validate({ source: { preEntry: true } }))
+        .toThrowErrorMatchingInlineSnapshot(`
+          [Error: Invalid configuration.
+
+          Invalid config on \`$input.source.preEntry\`.
+            - Expect to be (Array<string> | string | undefined)
+            - Got: boolean
+          ]
+        `)
+
       expect(() => validate({ source: { transformImport: true } }))
         .toThrowErrorMatchingInlineSnapshot(`
           [Error: Invalid configuration.