feat: support loading config from explicit path

packages/rstack/src/config.ts

@@ -1,3 +1,4 @@
+import { resolve } from 'node:path';
 import { loadConfig } from '@rstackjs/load-config';
 import type { RsbuildConfigDefinition } from '@rsbuild/core';
 import type { RslibConfigDefinition } from '@rslib/core';
@@ -24,6 +25,15 @@ type LoadedRstackConfig = {
   dependencies: string[];
 };
 
+type LoadRstackConfigOptions = {
+  /**
+   * The path to the Rstack config file, can be a relative or absolute path.
+   * If `configFilePath` is not provided, the config path set by the CLI is used.
+   * If neither path is provided, the function will search for the config file in the current working directory.
+   */
+  configFilePath?: string;
+};
+
 type ConfigState = {
   configs: Configs;
   configPath?: string;
@@ -108,17 +118,20 @@ export const define: Define = {
   staged: (config) => setConfig('staged', config),
 };
 
-export const loadRstackConfig = async (): Promise<LoadedRstackConfig> => {
+export const loadRstackConfig = async ({
+  configFilePath,
+}: LoadRstackConfigOptions = {}): Promise<LoadedRstackConfig> => {
   const state = getConfigState();
+  const configPath = configFilePath ?? state.configPath;
   state.configs = {};
 
   try {
     const { filePath, dependencies } = await loadConfig({
       loader: 'native',
       exportName: false,
       fresh: true,
-      ...(state.configPath !== undefined
-        ? { path: state.configPath }
+      ...(configPath !== undefined
+        ? { path: resolve(configPath) }
         : {
             configFileNames: [
               'rstack.config.ts',

packages/rstack/tests/config/load-config/explicit-dependency.ts

@@ -0,0 +1 @@
+export const title = 'explicit config works';

packages/rstack/tests/config/load-config/explicit.config.ts

@@ -0,0 +1,8 @@
+import { define } from 'rstack';
+import { title } from './explicit-dependency.ts';
+
+define.app({
+  html: {
+    title,
+  },
+});

packages/rstack/tests/config/load-config/index.test.ts

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { afterEach, expect, test } from 'rstack/test';
+import { getConfigState, loadRstackConfig } from '../../../src/config.ts';
+
+const state = getConfigState();
+
+afterEach(() => {
+  state.configs = {};
+  delete state.configPath;
+});
+
+test('should reset config state before and after loading', async () => {
+  state.configs = { app: {} };
+  state.configPath = path.join(import.meta.dirname, 'rstack.config.ts');
+
+  await expect(loadRstackConfig()).rejects.toThrow('test config error');
+  expect(state.configs).toEqual({});
+});
+
+test('should load an explicit config path before the legacy state path', async () => {
+  const configFilePath = path.join(import.meta.dirname, 'explicit.config.ts');
+  const dependencyPath = path.join(import.meta.dirname, 'explicit-dependency.ts');
+  const relativeConfigPath = path.relative(process.cwd(), configFilePath);
+  state.configPath = path.join(import.meta.dirname, 'rstack.config.ts');
+
+  const loaded = await loadRstackConfig({
+    configFilePath: relativeConfigPath,
+  });
+
+  expect(loaded.configs.app).toEqual({
+    html: {
+      title: 'explicit config works',
+    },
+  });
+  expect(loaded.filePath).toBe(configFilePath);
+  expect(loaded.dependencies).toEqual([dependencyPath]);
+  expect(state.configs).toEqual({});
+});
+
+test('should report the resolved path when an explicit config is missing', async () => {
+  const configFilePath = path.join(import.meta.dirname, 'missing.config.ts');
+  state.configs = { app: {} };
+
+  await expect(loadRstackConfig({ configFilePath })).rejects.toThrow(
+    `Cannot find config file: ${configFilePath}`,
+  );
+  expect(state.configs).toEqual({});
+});