Skip to content

core.mdx

Latest commit

 

History

History
371 lines (281 loc) · 8.5 KB

core.mdx

File metadata and controls

371 lines (281 loc) · 8.5 KB
description Use Rslib core APIs such as createRslib, loadConfig, defineConfig, and environment loading in JavaScript workflows.

Rslib core

This chapter introduces some of the core methods provided by Rslib.

createRslib

Create an Rslib instance.

  • Type:
function createRslib(options?: CreateRslibOptions): Promise<RslibInstance>;
  • Example:
import { createRslib } from '@rslib/core';

const rslib = await createRslib({
  config: {
    // Rslib configuration
  },
});

Options

The first parameter of createRslib is an options object with the following properties:

type CreateRslibOptions = {
  cwd?: string;
  config?: RslibConfig | (() => Promise<RslibConfig>);
  loadEnv?: boolean | LoadEnvOptions;
};
  • cwd: The root path of the current build, defaults to process.cwd().
  • config: Rslib configuration object. Refer to Configuration overview for all available configuration options.
  • loadEnv: Whether to call the loadEnv method to load environment variables and define them as global variables via source.define.

Load configuration async

config can also be an async function for dynamically loading Rslib configuration and performing custom operations.

import { createRslib, loadConfig } from '@rslib/core';

const rslib = await createRslib({
  config: async () => {
    const { content } = await loadConfig();
    someFunctionToUpdateConfig(content);
    return content;
  },
});

Load environment variables

The loadEnv option in createRslib calls the loadEnv method to load environment variables:

const rslib = await createRslib({
  loadEnv: true,
});

Setting loadEnv: true automatically completes these steps:

  1. Call the loadEnv method to load environment variables.
  2. Add source.define configuration, defining the publicVars returned by loadEnv as global variables.
  3. Watch the .env file for changes, restart build or restart the dev server when the file changes, and invalidate the build cache.
  4. Automatically call the cleanup method returned by loadEnv when closing the build or dev server.

You can also pass in the options of the loadEnv method, for example:

const rslib = await createRslib({
  loadEnv: {
    prefixes: ['PUBLIC_', 'REACT_COMPS_'],
  },
});

loadConfig

Load Rslib configuration file.

  • Type:
function loadConfig(params?: {
  // Default is process.cwd()
  cwd?: string;
  // Specify the configuration file (relative or absolute path)
  path?: string;
  meta?: Record<string, unknown>;
  envMode?: string;
  loader?: 'auto' | 'jiti' | 'native';
}): Promise<{
  content: RslibConfig;
  filePath: string | null;
}>;
  • Example:
import { loadConfig } from '@rslib/core';

// load `rslib.config.*` file by default
const { content } = await loadConfig();

console.log(content); // -> Rslib config object

const rslib = await createRslib({
  config: content,
});

If the Rslib config file does not exist in the cwd directory, the return value of the loadConfig method is { content: {}, filePath: null }.

Specify the configuration file

Use the path option to load the my-config.ts configuration file:

import { join } from 'node:path';
import { loadConfig } from '@rslib/core';

const { content } = await loadConfig({
  path: join(__dirname, 'my-config.ts'),
});

Passing meta object

Load the configuration file and pass in a custom meta object:

import { join } from 'node:path';
import { loadConfig } from '@rslib/core';

const { content } = await loadConfig({
  meta: {
    foo: 'bar',
  },
});

In the defineConfig configuration function, you can access the foo variable through the meta object:

export default defineConfig(({ meta }) => {
  console.log(meta.foo); // bar
  return config;
});

loadEnv

Load the .env file and return all environment variables starting with the specified prefixes.

The usage is the same as Rsbuild, see loadEnv -- Rsbuild for details.

:::tip

  • Rslib CLI will automatically call the loadEnv() method. If you are using the Rslib CLI, you can set the mode parameter through the --env-mode option.
  • The loadEnv option in createRslib will help you call the loadEnv() method and handle related operations.

:::

mergeRslibConfig

Used to merge multiple Rslib configuration objects.

The mergeRslibConfig function takes multiple configuration objects as parameters. It deep merges each configuration object, automatically combining multiple function values into an array of sequentially executed functions, and returns a merged configuration object.

  • Type:
function mergeRslibConfig(
  ...configs: (RslibConfigWithOptionalLib | undefined)[]
): RslibConfigWithOptionalLib;

Basic example

import { mergeRslibConfig } from '@rslib/core';

const config1 = {
  lib: [
    {
      format: 'esm',
    },
  ],
  output: {
    target: 'node',
  },
};
const config2 = {
  output: {
    target: 'web',
  },
};

const mergedConfig = mergeRslibConfig(config1, config2);

console.log(mergedConfig);
// {
//   lib: [
//     {
//       format: 'esm',
//     },
//   ],
//   output: {
//     target: 'web',
//   },
// }

Merge rules

For each item in the lib object array, the merge is processed based on the id field:

  • Objects with the same id are deeply merged
  • Objects without id will be appended to the end of the result array
  • Objects with id are sorted in order of first occurrence

Other configuration fields follow the same merge rules as mergeRsbuildConfig.

import { mergeRslibConfig } from '@rslib/core';

const config1: RslibConfig = {
  lib: [
    {
      format: 'iife',
    },
    {
      id: 'esm',
      format: 'esm',
      syntax: 'es2020',
      resolve: {
        alias: {
          A: 'a',
        },
      },
      output: {
        externals: ['pkg1'],
      },
    },
    {
      id: 'cjs',
      format: 'cjs',
    },
  ],
};

const config2: RslibConfig = {
  lib: [
    {
      id: 'esm',
      syntax: 'es2021',
      output: {
        externals: ['pkg2'],
      },
      resolve: {
        alias: {
          B: 'b',
        },
      },
    },
    {
      format: 'umd',
    },
  ],
};

const mergedConfig = mergeRslibConfig(config1, config2);

console.log(mergedConfig);
// {
//   lib: [
//     {
//       format: 'esm',
//       id: 'esm',
//       output: {
//         externals: ['pkg1', 'pkg2'],
//       },
//       resolve: {
//         alias: {
//           A: 'a',
//           B: 'b',
//         },
//       },
//       syntax: 'es2021',
//     },
//     {
//       format: 'cjs',
//       id: 'cjs',
//     },
//     {
//       format: 'iife',
//     },
//     {
//       format: 'umd',
//     },
//   ],
// }

rspack

If you need to access the API or plugins exported by @rspack/core, you can directly import the rspack object from @rslib/core without installing the @rspack/core package separately.

  • Type: Rspack
  • Example:
// the same as `import { rspack } from '@rspack/core'`
import { rspack } from '@rslib/core';

console.log(rspack.rspackVersion); // a.b.c
console.log(rspack.util.createHash);
console.log(rspack.BannerPlugin);

:::tip

  • Refer to Rspack plugins and Rspack JavaScript API to learn more about the available Rspack APIs.
  • It's not recommended to manually install the @rspack/core package, as it may conflict with the version that Rslib depends on.

:::

rsbuild

If you need to access the API exported by @rsbuild/core, you can directly import the rsbuild object from @rslib/core without installing the @rsbuild/core package separately.

  • Example:
import { rsbuild } from '@rslib/core';

console.log(rsbuild.version);

:::tip

Refer to Rsbuild core for available Rsbuild APIs.

:::

version

The version of @rslib/core currently in use.

  • Type: string
  • Example:
import { version } from '@rslib/core';

console.log(version); // 0.19.0