#Interface: Source

The Source option changes the behavior of source files.

#Properties

#alias?

optional alias?: Record<string, string | false | string[]>

Create aliases to import or require certain modules more easily.

#Deprecated

Use Resolve.alias instead.

#Default Value

undefined

#assetsInclude?

optional assetsInclude?: RuleSetCondition

Include additional files that should be treated as static assets.

#Default Value

undefined

#Remarks

By default, Rsbuild treats common image, font, audio, and video files as static assets. Through the source.assetsInclude config, you can specify additional file types that should be treated as static assets. These added static assets are processed using the same rules as the built-in supported static assets。

The usage of source.assetsInclude is consistent with Condition in Rspack, which supports passing in strings, regular expressions, arrays of conditions, or logical conditions to match the module path or assets.

#Example

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    assetsInclude: /\.json5$/,
  },
})

#decorators?

optional decorators?: Decorators

Used to configure the decorators syntax.

#Default Value

undefined

#Remarks

See Decorators.version for more information.

#define?

optional define?: DefinePluginOptions

The define options is used to define some values or expressions at compile time.

#Default Value

undefined

#Examples

Using define for environment variables.

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      BUILD_VERSION: JSON.stringify(process.env.BUILD_VERSION ?? 'unknown_version'),
      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
    },
  },
})

Expressions will be replaced with the corresponding code fragments:

const version = BUILD_VERSION;
if (process.env.NODE_ENV === 'development') {}

// ⬇️ Turn into being...
const version = "unknown_version";
if ("development" === 'development') {}

Using define for typeof.

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      'typeof window': JSON.stringify("undefined"),
    },
  },
})

The typeof expressions will be replaced with the corresponding code fragments:

if (typeof window !== 'undefined') {}

// ⬇️ Turn into being...
if ("undefined" !== 'undefined') {}

Using define with objects.

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    define: {
      'import.meta': {
        foo: JSON.stringify('foo'),
        bar: { baz: 0 },
      },
    },
  },
})

Expressions will be replaced with the corresponding code fragments:

console.log(import.meta)

// ⬇️ Turn into being...
console.log({ foo: "foo", bar: { baz: 0 } })

#Remarks

• If the value provided is a string, it will be utilized as a code fragment.

• If the value provided is an object, all its keys will be defined in the same manner.

• If the value isn't a string, it will be stringified, with functions included.

• Notably, if a typeof prefix is attached to the key, it will be exclusively defined for typeof calls."

#entry?

optional entry?: Entry

The Entry option is used to set the entry module.

#Default Value

'./src/index.js'

#Examples

• Use a single entry:

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: './src/pages/main/index.js',
  },
})

• Use a single entry with multiple entry modules:

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: ['./src/prefetch.js', './src/pages/main/index.js'],
  },
})

• Use multiple entries(with multiple entry modules):

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: ['./src/pages/bar/index.js', './src/post.js'], // multiple entry modules is allowed
    },
  },
})

• Use multiple entries with EntryDescription:

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    entry: {
      foo: './src/pages/foo/index.js',
      bar: {
        import: ['./src/prefetch.js', './src/pages/bar'],
      },
    },
  },
})

#exclude?

optional exclude?: RuleSetCondition[]

The source.exclude is used to specify JavaScript files that should be excluded from compilation.

#Default Value

undefined

#Remarks

By default, Rsbuild compiles JavaScript files in the current directory and TypeScript/JSX files in all directories. Through the source.exclude config, you can specify files or directories that should be excluded from compilation. The usage of source.exclude is consistent with Rule.exclude in Rspack, which supports passing in strings or regular expressions to match module paths.

#Examples

• Exclude specific files or directories

You can exclude specific files or directories from compilation to improve build performance or avoid processing certain files:

import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    exclude: [
      // Exclude all files in the test directory
      /[\\/]test[\\/]/,
      // Exclude specific file
      './src/legacy-file.js',
      // Exclude files matching a pattern
      /\.stories\.(js|ts)x?$/,
    ],
  },
})

• Exclude third-party dependencies

You can exclude specific third-party dependencies that don't need compilation:

import { defineConfig } from '@lynx-js/rspeedy'
import path from 'node:path'
import { createRequire } from 'node:module'

const require = createRequire(import.meta.url)

export default defineConfig({
  source: {
    exclude: [
      // Exclude specific package
      path.dirname(require.resolve('lodash')),
      // Exclude using regex pattern
      /node_modules[\\/]lodash-es[\\/]/,
    ],
  },
})

#include?

optional include?: RuleSetCondition[]

The source.include is used to specify additional JavaScript files that need to be compiled.

#Default Value

When unset, Rsbuild compiles JavaScript files in the current directory and TypeScript or JSX files in all directories, while excluding JavaScript files under node_modules.

#Remarks

To avoid redundant compilation, by default, Rsbuild only compiles JavaScript files in the current directory and TypeScript and JSX files in all directories. It does not compile JavaScript files under node_modules.

Through the source.include config, you can specify directories or modules that need to be compiled by Rsbuild. The usage of source.include is consistent with Rule.include in Rspack, which supports passing in strings or regular expressions to match the module path.

#Examples

• Compile Npm Packages

A typical usage scenario is to compile npm packages under node_modules, because some third-party dependencies have ESNext syntax, which may not be supported in Lynx. You can solve the problem by using this config to specify the dependencies that need to be compiled.

import { createRequire } from 'node:module'
import path from 'node:path'

import { defineConfig } from '@lynx-js/rspeedy'

const require = createRequire(import.meta.url)

export default defineConfig({
  source: {
    include: [
      // Method 1:
      // First get the path of the module by `require.resolve`
      // Then pass path.dirname to point to the corresponding directory
      path.dirname(require.resolve('query-string')),
      // Method 2:
      // Match by regular expression
      // All paths containing `node_modules/query-string/` will be matched
      /node_modules[\\/]query-string[\\/]/,
    ],
  },
})

• Compile Libraries in Monorepo

import path from 'node:path'
import { fileURLToPath } from 'node:url'

import { defineConfig } from '@lynx-js/rspeedy'

const __dirname = path.dirname(fileURLToPath(import.meta.url))

const packagesDir = path.resolve(__dirname, '../../packages')

export default defineConfig({
  source: {
    include: [
      // Compile all files in Monorepo's package directory
      // It is recommended to exclude the node_modules
      {
        and: [packagesDir, { not: /[\\/]node_modules[\\/]/ }],
      },
    ],
  },
})

#preEntry?

optional preEntry?: string | string[]

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.

#Default Value

undefined

#Remarks

See source.preEntry for more details.

#Example

Relative path will be resolved relative to the project root directory.

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    preEntry: './src/polyfill.ts',
  },
})

#transformImport?

optional transformImport?: TransformImport[]

The TransformImport option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by babel-plugin-import.

#Default Value

undefined

#Example

When using the TUX component library, you can import components on demand with the following config:

import { defineConfig } from '@lynx-js/rspeedy'

export default defineConfig({
  source: {
    transformImport: [
      {
        libraryName: 'foo',
        customName: 'foo/src/components/{{ member }}/{{ member }}',
      },
    ],
  },
})

This will transform the following source code:

import { Button } from 'foo'

to:

import { Button } from 'foo/src/components/Button/Button'

#tsconfigPath?

optional tsconfigPath?: string

Configure a custom tsconfig.json file path to use, can be a relative or absolute path.

#Default Value

'./tsconfig.json'

#Remarks

The tsconfigPath configuration affects the following behaviors:

• The paths field is used to configure Path Aliases.

• Sets the scope and rules for the Type Check Plugin.

#Example

Relative path will be resolved relative to the project root directory.

import { defineConfig } from '@lynx-js/rspeedy'
export default defineConfig({
  source: {
    tsconfigPath: './tsconfig.build.json',
  },
})