@nocobase/cli-v1 2.1.0-beta.34 → 2.1.0-beta.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/cli-v1",
-  "version": "2.1.0-beta.34",
+  "version": "2.1.0-beta.36",
   "description": "",
   "license": "Apache-2.0",
   "main": "./src/index.js",
@@ -8,9 +8,9 @@
     "nocobase-v1": "./bin/index.js"
   },
   "dependencies": {
-    "@nocobase/cli": "2.1.0-beta.34",
+    "@nocobase/cli": "2.1.0-beta.36",
     "@nocobase/license-kit": "^0.3.8",
-    "@nocobase/utils": "2.1.0-beta.34",
+    "@nocobase/utils": "2.1.0-beta.36",
     "chalk": "^4.1.1",
     "commander": "^9.2.0",
     "deepmerge": "^4.3.1",
@@ -25,7 +25,7 @@
     "tree-kill": "^1.2.2"
   },
   "devDependencies": {
-    "@nocobase/devtools": "2.1.0-beta.34",
+    "@nocobase/devtools": "2.1.0-beta.36",
     "@types/fs-extra": "^11.0.1"
   },
   "repository": {
@@ -33,5 +33,5 @@
     "url": "git+https://github.com/nocobase/nocobase.git",
     "directory": "packages/core/cli"
   },
-  "gitHead": "ca804833299c547f8d49f8d58f73273a4bfcd03c"
+  "gitHead": "397d45c744f6eb48b3a0cd785c87cbf1257c3513"
 }

package/src/__tests__/app-dev-utils.test.js

@@ -0,0 +1,121 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+/* eslint-env jest */
+
+const fs = require('fs-extra');
+const os = require('os');
+const path = require('path');
+const {
+  buildAppDevServerArgs,
+  createPluginClientExternals,
+  getPluginClientModuleIds,
+  shouldUseAppDevServerSource,
+  toPosixPath,
+} = require('../commands/app-dev-utils');
+
+describe('cli-v1 app-dev utils', () => {
+  test('toPosixPath normalizes Windows paths for generated browser imports', () => {
+    expect(toPosixPath('C:\\Users\\tester\\app\\packages\\plugins\\demo\\src\\client\\index.tsx')).toBe(
+      'C:/Users/tester/app/packages/plugins/demo/src/client/index.tsx',
+    );
+  });
+
+  test('toPosixPath keeps POSIX paths unchanged', () => {
+    expect(toPosixPath('/Users/tester/app/packages/plugins/demo/src/client/index.tsx')).toBe(
+      '/Users/tester/app/packages/plugins/demo/src/client/index.tsx',
+    );
+  });
+
+  test('shouldUseAppDevServerSource requires app-dev and the app source entry', () => {
+    const appRoot = path.resolve('/app');
+    const appSourceEntry = path.resolve(appRoot, 'storage/.app-dev/src/index.ts');
+    const existsSync = (file) => file === appSourceEntry;
+
+    expect(
+      shouldUseAppDevServerSource({
+        cwd: appRoot,
+        env: {
+          APP_ENV: 'development',
+          APP_PACKAGE_ROOT: 'storage/.app-dev',
+          NOCOBASE_APP_DEV: 'true',
+        },
+        existsSync,
+      }),
+    ).toBe(true);
+    expect(
+      shouldUseAppDevServerSource({
+        cwd: appRoot,
+        env: {
+          APP_ENV: 'production',
+          APP_PACKAGE_ROOT: 'storage/.app-dev',
+          NOCOBASE_APP_DEV: 'true',
+        },
+        existsSync,
+      }),
+    ).toBe(false);
+    expect(
+      shouldUseAppDevServerSource({
+        cwd: appRoot,
+        env: {
+          APP_ENV: 'development',
+          APP_PACKAGE_ROOT: 'storage/.app-dev',
+          NOCOBASE_APP_DEV: '',
+        },
+        existsSync,
+      }),
+    ).toBe(false);
+  });
+
+  test('buildAppDevServerArgs runs the app source through tsx watch', () => {
+    expect(
+      buildAppDevServerArgs({
+        appPackageRoot: 'storage/.app-dev',
+        argv: ['node', 'nocobase-v1', 'start', '--launch-mode', 'direct'],
+        serverTsconfigPath: './tsconfig.server.json',
+      }),
+    ).toEqual([
+      'watch',
+      `--ignore=${path.resolve(process.cwd(), 'storage/plugins')}/**`,
+      '--tsconfig',
+      './tsconfig.server.json',
+      '-r',
+      'tsconfig-paths/register',
+      path.join('storage/.app-dev', 'src/index.ts'),
+      'start',
+      '--launch-mode',
+      'direct',
+    ]);
+  });
+
+  test('getPluginClientModuleIds discovers plugin client marker files', () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'nocobase-app-dev-modules-'));
+    const localPluginDir = path.join(cwd, 'packages/plugins/@nocobase/plugin-local');
+    const remotePluginDir = path.join(cwd, 'node_modules/@nocobase/plugin-remote');
+    fs.ensureDirSync(localPluginDir);
+    fs.ensureDirSync(remotePluginDir);
+    fs.writeJsonSync(path.join(localPluginDir, 'package.json'), { name: '@nocobase/plugin-local' });
+    fs.writeFileSync(path.join(localPluginDir, 'client.js'), '');
+    fs.writeJsonSync(path.join(remotePluginDir, 'package.json'), { name: '@nocobase/plugin-remote' });
+    fs.writeFileSync(path.join(remotePluginDir, 'client-v2.js'), '');
+
+    expect(getPluginClientModuleIds({ cwd }).sort()).toEqual([
+      '@nocobase/plugin-local/client',
+      '@nocobase/plugin-remote/client-v2',
+    ]);
+    fs.removeSync(cwd);
+  });
+
+  test('createPluginClientExternals maps plugin client imports to app-dev modules', () => {
+    expect(createPluginClientExternals(['@nocobase/plugin-demo/client'])).toEqual({
+      '@nocobase/plugin-demo/client':
+        'window.__nocobase_app_dev_plugins__ && window.__nocobase_app_dev_plugins__["@nocobase/plugin-demo/client"]',
+    });
+  });
+});

package/src/__tests__/build-index-html.test.js

@@ -0,0 +1,83 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+/* eslint-env jest */
+
+const fs = require('fs-extra');
+const os = require('os');
+const path = require('path');
+const { buildIndexHtml } = require('../util');
+
+function createAppPackageRoot() {
+  const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'nocobase-app-html-'));
+  const clientDir = path.join(appRoot, 'dist/client');
+  fs.ensureDirSync(clientDir);
+  fs.writeFileSync(path.join(clientDir, 'index.html'), '<html></html>', 'utf-8');
+  fs.writeFileSync(
+    path.join(clientDir, 'index.html.tpl'),
+    [
+      "window['__nocobase_app_dev__'] = {{env.NOCOBASE_APP_DEV}};",
+      "window['__nocobase_public_path__'] = '{{env.APP_PUBLIC_PATH}}';",
+    ].join('\n'),
+    'utf-8',
+  );
+  return appRoot;
+}
+
+describe('cli-v1 buildIndexHtml', () => {
+  const originalArgv = process.argv.slice();
+  const originalEnv = { ...process.env };
+
+  afterEach(() => {
+    process.argv = originalArgv.slice();
+    process.env = { ...originalEnv };
+  });
+
+  test('marks app-dev HTML when running the app-dev command before child env is injected', () => {
+    const appRoot = createAppPackageRoot();
+    process.argv = ['node', 'nocobase-v1', 'app-dev'];
+    process.env.APP_PACKAGE_ROOT = appRoot;
+    process.env.APP_PUBLIC_PATH = '/';
+    process.env.NOCOBASE_APP_DEV = '';
+
+    buildIndexHtml();
+
+    const html = fs.readFileSync(path.join(appRoot, 'dist/client/index.html'), 'utf-8');
+    expect(html).toContain("window['__nocobase_app_dev__'] = true;");
+    fs.removeSync(appRoot);
+  });
+
+  test('marks app-dev HTML when running a child command with app-dev env', () => {
+    const appRoot = createAppPackageRoot();
+    process.argv = ['node', 'nocobase-v1', 'start'];
+    process.env.APP_PACKAGE_ROOT = appRoot;
+    process.env.APP_PUBLIC_PATH = '/';
+    process.env.NOCOBASE_APP_DEV = 'true';
+
+    buildIndexHtml();
+
+    const html = fs.readFileSync(path.join(appRoot, 'dist/client/index.html'), 'utf-8');
+    expect(html).toContain("window['__nocobase_app_dev__'] = true;");
+    fs.removeSync(appRoot);
+  });
+
+  test('does not mark normal start HTML as app-dev', () => {
+    const appRoot = createAppPackageRoot();
+    process.argv = ['node', 'nocobase-v1', 'start'];
+    process.env.APP_PACKAGE_ROOT = appRoot;
+    process.env.APP_PUBLIC_PATH = '/';
+    process.env.NOCOBASE_APP_DEV = '';
+
+    buildIndexHtml();
+
+    const html = fs.readFileSync(path.join(appRoot, 'dist/client/index.html'), 'utf-8');
+    expect(html).toContain("window['__nocobase_app_dev__'] = false;");
+    fs.removeSync(appRoot);
+  });
+});

package/src/__tests__/plugin-generator.test.js

@@ -0,0 +1,43 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+/* eslint-env jest */
+
+const path = require('path');
+const { PluginGenerator } = require('../plugin-generator');
+
+describe('cli-v1 plugin generator', () => {
+  test('uses cwd as baseDir when baseDir is not provided', () => {
+    const cwd = path.resolve('/tmp/nocobase-plugin-generator');
+    const generator = new PluginGenerator({
+      cwd,
+      args: {},
+      context: {
+        name: '@nocobase/plugin-demo',
+      },
+    });
+
+    expect(generator.baseDir).toBe(cwd);
+  });
+
+  test('prefers explicit baseDir over cwd', () => {
+    const baseDir = path.resolve('/tmp/nocobase-plugin-generator-base');
+    const cwd = path.resolve('/tmp/nocobase-plugin-generator-cwd');
+    const generator = new PluginGenerator({
+      baseDir,
+      cwd,
+      args: {},
+      context: {
+        name: '@nocobase/plugin-demo',
+      },
+    });
+
+    expect(generator.baseDir).toBe(baseDir);
+  });
+});

package/src/commands/app-dev-plugin-server.js

@@ -0,0 +1,181 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+const path = require('path');
+const { createRsbuild } = require('@rsbuild/core');
+const { pluginLess } = require('@rsbuild/plugin-less');
+const { pluginReact } = require('@rsbuild/plugin-react');
+const { pluginSvgr } = require('@rsbuild/plugin-svgr');
+const {
+  createPluginClientExternals,
+  discoverLocalPluginEntries,
+  getPluginClientModuleIds,
+  writePluginDevEntryFiles,
+} = require('./app-dev-utils');
+const { storagePathJoin } = require('../util');
+
+const appDevExternalDeps = [
+  'react',
+  'react-dom',
+  'react/jsx-runtime',
+  'react-router',
+  'react-router-dom',
+  'antd',
+  'antd-style',
+  '@ant-design/icons',
+  '@ant-design/cssinjs',
+  'i18next',
+  'react-i18next',
+  '@formily/antd-v5',
+  '@formily/core',
+  '@formily/json-schema',
+  '@formily/path',
+  '@formily/react',
+  '@formily/reactive',
+  '@formily/reactive-react',
+  '@formily/shared',
+  '@formily/validator',
+  '@dnd-kit/core',
+  '@dnd-kit/sortable',
+  '@nocobase/client',
+  '@nocobase/client/client',
+  '@nocobase/client-v2',
+  '@nocobase/client-v2/client-v2',
+  '@nocobase/evaluators',
+  '@nocobase/evaluators/client',
+  '@nocobase/flow-engine',
+  '@nocobase/sdk',
+  '@nocobase/utils',
+  '@nocobase/utils/client',
+  '@emotion/css',
+  'ahooks',
+  'axios',
+  'dayjs',
+  'file-saver',
+  'lodash',
+];
+
+function createExternals() {
+  return appDevExternalDeps.reduce((memo, dep) => {
+    memo[dep] = `window.__nocobase_app_dev_deps__ && window.__nocobase_app_dev_deps__[${JSON.stringify(dep)}]`;
+    return memo;
+  }, {});
+}
+
+async function main() {
+  const cwd = process.cwd();
+  const port = Number(process.env.NOCOBASE_APP_DEV_PLUGIN_PORT || 14100);
+  const entryDir = storagePathJoin('.app-dev', 'plugin-dev', 'entries');
+  const outDir = storagePathJoin('.app-dev', 'plugin-dev', 'dist');
+  const entries = discoverLocalPluginEntries({ cwd, port });
+  const externals = {
+    ...createExternals(),
+    ...createPluginClientExternals(getPluginClientModuleIds({ cwd })),
+  };
+
+  if (!entries.length) {
+    console.log('[app-dev] no local plugin client entries found');
+    await new Promise(() => {});
+    return;
+  }
+
+  const rsbuildEntries = await writePluginDevEntryFiles(entries, entryDir);
+  const rsbuild = await createRsbuild({
+    cwd,
+    rsbuildConfig: {
+      plugins: [pluginReact(), pluginLess(), pluginSvgr()],
+      source: {
+        entry: Object.fromEntries(
+          Object.entries(rsbuildEntries).map(([name, entryFile]) => [
+            name,
+            {
+              import: entryFile,
+              html: false,
+            },
+          ]),
+        ),
+        tsconfigPath: path.resolve(cwd, 'tsconfig.json'),
+        decorators: {
+          version: 'legacy',
+        },
+      },
+      output: {
+        target: 'web',
+        distPath: {
+          root: outDir,
+          js: '.',
+          jsAsync: '.',
+          css: '.',
+          cssAsync: '.',
+          svg: '.',
+          font: '.',
+          image: '.',
+          media: '.',
+          assets: '.',
+        },
+        filename: {
+          js: '[name].js',
+          css: '[name].css',
+          svg: '[name][ext][query]',
+          font: '[name][ext][query]',
+          image: '[name][ext][query]',
+          media: '[name][ext][query]',
+          assets: '[name][ext][query]',
+        },
+        assetPrefix: `http://localhost:${port}/`,
+        cleanDistPath: true,
+        sourceMap: {
+          js: 'eval-cheap-module-source-map',
+          css: false,
+        },
+      },
+      server: {
+        host: '0.0.0.0',
+        port,
+        cors: true,
+      },
+      dev: {
+        hmr: false,
+        liveReload: true,
+        assetPrefix: `http://localhost:${port}/`,
+        lazyCompilation: false,
+        client: {
+          port,
+          protocol: 'ws',
+        },
+      },
+      tools: {
+        rspack(config) {
+          config.output = config.output || {};
+          config.output.library = { type: 'module' };
+          config.output.module = true;
+          config.output.chunkFormat = 'module';
+          config.output.chunkLoading = 'import';
+          config.output.workerChunkLoading = 'import';
+          config.experiments = {
+            ...config.experiments,
+            outputModule: true,
+          };
+          config.externalsType = 'var';
+          config.externals = {
+            ...(config.externals || {}),
+            ...externals,
+          };
+        },
+      },
+    },
+  });
+
+  await rsbuild.startDevServer();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/commands/app-dev-utils.js

@@ -0,0 +1,191 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+const fs = require('fs-extra');
+const fg = require('fast-glob');
+const path = require('path');
+const { resolvePluginStoragePath } = require('../util');
+
+const pluginClientLanes = {
+  client: {
+    rootEntryFile: 'client.js',
+    sourceDir: 'client',
+  },
+  'client-v2': {
+    rootEntryFile: 'client-v2.js',
+    sourceDir: 'client-v2',
+  },
+};
+
+function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, '/');
+}
+
+function getEntryName(packageName, lane) {
+  return `${packageName.replace(/[^a-zA-Z0-9_]/g, '_')}__${lane.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+}
+
+function readPackageName(packageJsonPath) {
+  try {
+    return fs.readJsonSync(packageJsonPath).name;
+  } catch (error) {
+    return '';
+  }
+}
+
+function findLocalPluginPackageJsons(cwd = process.cwd()) {
+  return fg.sync(['packages/plugins/*/package.json', 'packages/plugins/@*/*/package.json'], {
+    cwd,
+    absolute: true,
+    onlyFiles: true,
+  });
+}
+
+function findPluginClientPackageJsons(cwd = process.cwd()) {
+  return fg.sync(
+    [
+      'packages/plugins/*/package.json',
+      'packages/plugins/@*/*/package.json',
+      'node_modules/@nocobase/plugin-*/package.json',
+      'node_modules/@nocobase/preset-*/package.json',
+    ],
+    {
+      cwd,
+      absolute: true,
+      onlyFiles: true,
+    },
+  );
+}
+
+function getPluginClientModuleIds({ cwd = process.cwd(), packageJsonPaths = findPluginClientPackageJsons(cwd) } = {}) {
+  const moduleIds = new Set();
+
+  for (const packageJsonPath of packageJsonPaths) {
+    const pluginDir = path.dirname(packageJsonPath);
+    const packageName = readPackageName(packageJsonPath);
+    if (!packageName) {
+      continue;
+    }
+
+    for (const [lane, config] of Object.entries(pluginClientLanes)) {
+      if (fs.existsSync(path.join(pluginDir, config.rootEntryFile))) {
+        moduleIds.add(`${packageName}/${lane}`);
+      }
+    }
+  }
+
+  return [...moduleIds];
+}
+
+function createPluginClientExternals(moduleIds) {
+  return moduleIds.reduce((memo, moduleId) => {
+    memo[moduleId] = `window.__nocobase_app_dev_plugins__ && window.__nocobase_app_dev_plugins__[${JSON.stringify(
+      moduleId,
+    )}]`;
+    return memo;
+  }, {});
+}
+
+function discoverLocalPluginEntries({ cwd = process.cwd(), port } = {}) {
+  const entries = [];
+
+  for (const packageJsonPath of findLocalPluginPackageJsons(cwd)) {
+    const pluginDir = path.dirname(packageJsonPath);
+    const packageJson = fs.readJsonSync(packageJsonPath);
+    const packageName = packageJson.name;
+    if (!packageName) {
+      continue;
+    }
+
+    for (const [lane, config] of Object.entries(pluginClientLanes)) {
+      const rootEntry = path.join(pluginDir, config.rootEntryFile);
+      const sourceEntry = fg.sync('index.{ts,tsx,js,jsx}', {
+        cwd: path.join(pluginDir, 'src', config.sourceDir),
+        absolute: true,
+        onlyFiles: true,
+      })[0];
+
+      if (!fs.existsSync(rootEntry) || !sourceEntry) {
+        continue;
+      }
+
+      const entryName = getEntryName(packageName, lane);
+      entries.push({
+        packageName,
+        lane,
+        entryName,
+        sourceEntry,
+        url: port ? `http://localhost:${port}/${entryName}.js` : '',
+      });
+    }
+  }
+
+  return entries;
+}
+
+function buildPluginDevUrlMap(entries) {
+  return entries.reduce((memo, item) => {
+    memo[item.packageName] = memo[item.packageName] || {};
+    memo[item.packageName][item.lane] = item.url;
+    return memo;
+  }, {});
+}
+
+function shouldUseAppDevServerSource({ env = process.env, cwd = process.cwd(), existsSync = fs.existsSync } = {}) {
+  if (env.NOCOBASE_APP_DEV !== 'true' || env.APP_ENV === 'production' || !env.APP_PACKAGE_ROOT) {
+    return false;
+  }
+
+  return existsSync(path.resolve(cwd, env.APP_PACKAGE_ROOT, 'src/index.ts'));
+}
+
+function buildAppDevServerArgs({
+  appPackageRoot = process.env.APP_PACKAGE_ROOT,
+  argv = process.argv,
+  serverTsconfigPath = process.env.SERVER_TSCONFIG_PATH,
+} = {}) {
+  const args = ['watch', `--ignore=${resolvePluginStoragePath()}/**`];
+
+  if (serverTsconfigPath) {
+    args.push('--tsconfig', serverTsconfigPath);
+  }
+
+  args.push('-r', 'tsconfig-paths/register', path.join(appPackageRoot, 'src/index.ts'), ...argv.slice(2));
+  return args;
+}
+
+async function writePluginDevEntryFiles(entries, entryDir) {
+  await fs.ensureDir(entryDir);
+  await fs.emptyDir(entryDir);
+
+  const rsbuildEntries = {};
+  for (const entry of entries) {
+    const entryFile = path.join(entryDir, `${entry.entryName}.tsx`);
+    const sourceEntry = toPosixPath(entry.sourceEntry);
+    await fs.writeFile(
+      entryFile,
+      [`export { default } from '${sourceEntry}';`, `export * from '${sourceEntry}';`, ''].join('\n'),
+      'utf-8',
+    );
+    rsbuildEntries[entry.entryName] = entryFile;
+  }
+
+  return rsbuildEntries;
+}
+
+module.exports = {
+  buildAppDevServerArgs,
+  buildPluginDevUrlMap,
+  createPluginClientExternals,
+  discoverLocalPluginEntries,
+  getPluginClientModuleIds,
+  shouldUseAppDevServerSource,
+  toPosixPath,
+  writePluginDevEntryFiles,
+};

package/src/commands/app-dev.js

@@ -0,0 +1,93 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+const path = require('path');
+const { getPortPromise } = require('portfinder');
+const { buildPluginDevUrlMap, discoverLocalPluginEntries } = require('./app-dev-utils');
+const { run, runWithPrefix } = require('../util');
+
+function hasArg(args, name) {
+  return args.some((item) => item === name || item.startsWith(`${name}=`));
+}
+
+function omitOptionWithValue(args, name) {
+  const nextArgs = [];
+  for (let index = 0; index < args.length; index++) {
+    const item = args[index];
+    if (item === name) {
+      index += 1;
+      continue;
+    }
+    if (item.startsWith(`${name}=`)) {
+      continue;
+    }
+    nextArgs.push(item);
+  }
+  return nextArgs;
+}
+
+/**
+ *
+ * @param {import('commander').Command} cli
+ */
+module.exports = (cli) => {
+  cli
+    .command('app-dev')
+    .description('Run the published app shell with local plugin development support')
+    .option('--plugin-port [port]', 'local plugin dev server port')
+    .allowUnknownOption()
+    .action(async (opts) => {
+      const passthroughArgs = omitOptionWithValue(process.argv.slice(3), '--plugin-port');
+      const pluginPort = opts.pluginPort
+        ? Number(opts.pluginPort)
+        : await getPortPromise({ port: Number(process.env.NOCOBASE_APP_DEV_PLUGIN_PORT || 14100) });
+      const entries = discoverLocalPluginEntries({ cwd: process.cwd(), port: pluginPort });
+      const pluginDevUrlMap = buildPluginDevUrlMap(entries);
+      let pluginDevServer;
+
+      const sharedEnv = {
+        NOCOBASE_APP_DEV: 'true',
+        NOCOBASE_APP_DEV_PLUGIN_PORT: `${pluginPort}`,
+        NOCOBASE_APP_DEV_PLUGIN_URLS: JSON.stringify(pluginDevUrlMap),
+      };
+
+      if (entries.length) {
+        pluginDevServer = runWithPrefix('node', [path.resolve(__dirname, './app-dev-plugin-server.js')], {
+          prefix: 'plugin-dev',
+          color: 'green',
+          env: sharedEnv,
+        });
+      }
+
+      const cleanup = () => {
+        pluginDevServer?.kill('SIGTERM');
+      };
+      process.once('exit', cleanup);
+      process.once('SIGINT', () => {
+        cleanup();
+        process.exit(130);
+      });
+      process.once('SIGTERM', () => {
+        cleanup();
+        process.exit(143);
+      });
+
+      const startArgs = ['start'];
+      if (!hasArg(passthroughArgs, '--launch-mode')) {
+        startArgs.push('--launch-mode', 'direct');
+      }
+      startArgs.push(...passthroughArgs);
+
+      await run('nocobase-v1', startArgs, {
+        env: {
+          ...sharedEnv,
+        },
+      });
+    });
+};

package/src/commands/build.js

@@ -7,34 +7,10 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-const { existsSync } = require('fs');
 const { resolve } = require('path');
 const { Command } = require('commander');
 const { run, nodeCheck, isPackageValid, buildIndexHtml } = require('../util');
 
-async function buildClientV2() {
-  const configPath = resolve(process.env.APP_PACKAGE_ROOT, 'client-v2/rsbuild.config.ts');
-  if (!existsSync(configPath)) {
-    console.log(`client-v2 config not found: ${configPath}`);
-    return;
-  }
-  await run('rsbuild', ['build', '--config', configPath], {
-    env: {
-      ...process.env,
-      APP_ENV: 'production',
-      NODE_ENV: 'production',
-      API_BASE_URL: process.env.API_BASE_URL || process.env.API_BASE_PATH,
-      API_CLIENT_STORAGE_PREFIX: process.env.API_CLIENT_STORAGE_PREFIX,
-      API_CLIENT_STORAGE_TYPE: process.env.API_CLIENT_STORAGE_TYPE,
-      API_CLIENT_SHARE_TOKEN: process.env.API_CLIENT_SHARE_TOKEN || 'false',
-      WEBSOCKET_URL: process.env.WEBSOCKET_URL || '',
-      WS_PATH: process.env.WS_PATH,
-      ESM_CDN_BASE_URL: process.env.ESM_CDN_BASE_URL || 'https://esm.sh',
-      ESM_CDN_SUFFIX: process.env.ESM_CDN_SUFFIX || '',
-    },
-  });
-}
-
 /**
  *
  * @param {Command} cli
@@ -50,17 +26,11 @@ module.exports = (cli) => {
     .option('-w, --watch', 'watch compile the @nocobase/build package')
     .option('-s, --sourcemap', 'generate sourcemap')
     .option('--no-dts', 'not generate dts')
-    .option('--client-v2-only', 'build client-v2 shell only')
     .action(async (pkgs, options) => {
       nodeCheck();
       process.env['VITE_CJS_IGNORE_WARNING'] = 'true';
       process.env.APP_ENV = 'production';
 
-      if (options.clientV2Only) {
-        await buildClientV2();
-        return;
-      }
-
       if (pkgs.length === 0) {
         await run('nocobase-v1', ['clean', '--dist']);
       }
@@ -80,8 +50,5 @@ module.exports = (cli) => {
         options.retry ? '--retry' : '',
       ]);
       buildIndexHtml(true);
-      if (!pkgs.includes('@nocobase/app')) {
-        await buildClientV2();
-      }
     });
 };

package/src/commands/clean.js

@@ -9,7 +9,7 @@
 
 const chalk = require('chalk');
 const { Command } = require('commander');
-const { run, isDev } = require('../util');
+const { run, isDev, storagePathJoin } = require('../util');
 
 /**
  *
@@ -34,7 +34,7 @@ module.exports = (cli) => {
           run('rimraf', ['-rf', ...distDirs]);
         }
       } else {
-        run('rimraf', ['-rf', './storage/app-dev']);
+        run('rimraf', ['-rf', storagePathJoin('.app-dev')]);
         run('rimraf', ['-rf', 'packages/*/*/{lib,esm,es,dist,node_modules}']);
         run('rimraf', ['-rf', 'packages/*/@*/*/{lib,esm,es,dist,node_modules}']);
       }

package/src/commands/client.js

@@ -11,6 +11,7 @@ const chalk = require('chalk');
 const { Command } = require('commander');
 const fs = require('fs-extra');
 const { resolve } = require('path');
+const { storagePathJoin } = require('../util');
 
 /**
  * 复制主应用客户端文件
@@ -110,7 +111,7 @@ module.exports = (cli) => {
     .allowUnknownOption()
     .action(async () => {
       const version = require('../../package.json').version;
-      const target = resolve(process.cwd(), 'storage/dist-client', version);
+      const target = storagePathJoin('dist-client', version);
       const mainClientSource = resolve(process.cwd(), 'node_modules/@nocobase/app/dist/client');
       await copyMainClient(mainClientSource, target);
       await copyPluginClients('packages/plugins', '@nocobase', target);
@@ -123,7 +124,7 @@ module.exports = (cli) => {
     .allowUnknownOption()
     .action(async () => {
       const version = require('../../package.json').version;
-      const target = resolve(process.cwd(), 'storage/dist-client', version);
+      const target = storagePathJoin('dist-client', version);
 
       // 检查必要的环境变量
       if (

package/src/commands/dev.js

@@ -24,6 +24,7 @@ const chokidar = require('chokidar');
 const { uid } = require('@formily/shared');
 const path = require('path');
 const fs = require('fs');
+const { resolvePluginStoragePath } = require('@nocobase/utils/plugin-symlink');
 
 function sleep(ms = 1000) {
   return new Promise((resolve) => {
@@ -198,7 +199,7 @@ module.exports = (cli) => {
       };
 
       if (shouldRunClient) {
-        const storagePluginPath = path.resolve(process.cwd(), 'storage/plugins');
+        const storagePluginPath = resolvePluginStoragePath();
         const watcher = chokidar.watch(`${storagePluginPath}/**/*`, {
           cwd: process.cwd(),
           ignored: /(^|[\/\\])\../, // 忽略隐藏文件
@@ -246,7 +247,7 @@ module.exports = (cli) => {
         const argv = [
           'watch',
           ...(inspect ? [`--inspect=${inspect === true ? 9229 : inspect}`] : []),
-          '--ignore=./storage/plugins/**',
+          `--ignore=${resolvePluginStoragePath()}/**`,
           '--tsconfig',
           SERVER_TSCONFIG_PATH,
           '-r',

package/src/commands/e2e.js

@@ -8,7 +8,7 @@
  */
 
 const { Command } = require('commander');
-const { run, isPortReachable, checkDBDialect } = require('../util');
+const { run, isPortReachable, checkDBDialect, storagePathJoin } = require('../util');
 const { execSync } = require('node:child_process');
 const axios = require('axios');
 const { pTest } = require('./p-test');
@@ -119,17 +119,15 @@ const commonConfig = {
 };
 
 const runCodegenSync = () => {
+  const authFile = storagePathJoin('playwright', '.auth', 'codegen.auth.json');
   try {
     execSync(
-      `npx playwright codegen --load-storage=storage/playwright/.auth/codegen.auth.json ${process.env.APP_BASE_URL} --save-storage=storage/playwright/.auth/codegen.auth.json`,
+      `npx playwright codegen --load-storage=${authFile} ${process.env.APP_BASE_URL} --save-storage=${authFile}`,
       commonConfig,
     );
   } catch (err) {
     if (err.message.includes('auth.json')) {
-      execSync(
-        `npx playwright codegen ${process.env.APP_BASE_URL} --save-storage=storage/playwright/.auth/codegen.auth.json`,
-        commonConfig,
-      );
+      execSync(`npx playwright codegen ${process.env.APP_BASE_URL} --save-storage=${authFile}`, commonConfig);
     } else {
       console.error(err);
     }

package/src/commands/index.js

@@ -21,6 +21,7 @@ module.exports = (cli) => {
   require('./locale')(cli);
   require('./build')(cli);
   require('./tar')(cli);
+  require('./app-dev')(cli);
   require('./dev')(cli);
   require('./start')(cli);
   require('./e2e')(cli);

package/src/commands/instance-id.js

@@ -9,9 +9,8 @@
 
 const chalk = require('chalk');
 const { Command } = require('commander');
-const { run, isDev } = require('../util');
+const { run, isDev, storagePathJoin } = require('../util');
 const { getInstanceIdAsync } = require('@nocobase/license-kit');
-const path = require('path');
 const fs = require('fs');
 const { logger } = require('../logger');
 
@@ -26,8 +25,8 @@ module.exports = (cli) => {
     .option('--force', 'Force generate InstanceID')
     .action(async (options) => {
       logger.info('Generating InstanceID...');
-      const dir = path.resolve(process.cwd(), 'storage/.license');
-      const filePath = path.resolve(dir, 'instance-id');
+      const dir = storagePathJoin('.license');
+      const filePath = storagePathJoin('.license', 'instance-id');
       if (fs.existsSync(filePath) && !options.force) {
         logger.info('InstanceID already exists at ' + filePath);
         return;

package/src/commands/locale.js

@@ -15,6 +15,7 @@ const _ = require('lodash');
 const deepmerge = require('deepmerge');
 const { getCronstrueLocale } = require('./locale/cronstrue');
 const { getReactJsCron } = require('./locale/react-js-cron');
+const { storagePathJoin } = require('../util');
 
 function sortJSON(json) {
   if (Array.isArray(json)) {
@@ -41,8 +42,9 @@ module.exports = (cli) => {
     const files = await fg('./*/src/locale/*.json', {
       cwd,
     });
+    const localeDir = storagePathJoin('locales');
     let locales = {};
-    await fs.mkdirp(path.resolve(process.cwd(), 'storage/locales'));
+    await fs.mkdirp(localeDir);
     for (const file of files) {
       const locale = path.basename(file, '.json');
       const pkg = path.basename(path.dirname(path.dirname(path.dirname(file))));
@@ -70,10 +72,7 @@ module.exports = (cli) => {
     }
     locales = sortJSON(locales);
     for (const locale of Object.keys(locales)) {
-      await fs.writeFile(
-        path.resolve(process.cwd(), 'storage/locales', `${locale}.json`),
-        JSON.stringify(sortJSON(locales[locale]), null, 2),
-      );
+      await fs.writeFile(path.resolve(localeDir, `${locale}.json`), JSON.stringify(sortJSON(locales[locale]), null, 2));
     }
   });
 

package/src/commands/p-test.js

@@ -14,6 +14,7 @@ const dotenv = require('dotenv');
 const fs = require('fs');
 const glob = require('glob');
 const _ = require('lodash');
+const { storagePathJoin } = require('../util');
 
 let ENV_FILE = resolve(process.cwd(), '.env.e2e');
 
@@ -55,16 +56,16 @@ async function runApp(dir, index = 0) {
       APP_ENV: 'production',
       APP_PORT: 20000 + index,
       DB_DATABASE: `nocobase${index}`,
-      SOCKET_PATH: `storage/e2e/gateway-e2e-${index}.sock`,
-      PM2_HOME: resolve(process.cwd(), `storage/e2e/.pm2-${index}`),
-      PLAYWRIGHT_AUTH_FILE: resolve(process.cwd(), `storage/playwright/.auth/admin-${index}.json`),
+      SOCKET_PATH: storagePathJoin('e2e', `gateway-e2e-${index}.sock`),
+      PM2_HOME: storagePathJoin('e2e', `.pm2-${index}`),
+      PLAYWRIGHT_AUTH_FILE: storagePathJoin('playwright', '.auth', `admin-${index}.json`),
       E2E_JOB_ID: index,
     },
   });
 }
 
 exports.pTest = async (options) => {
-  const dir = resolve(process.cwd(), 'storage/e2e');
+  const dir = storagePathJoin('e2e');
 
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });

package/src/commands/pkg.js

@@ -22,7 +22,7 @@ class Package {
   constructor(packageName, packageManager) {
     this.packageName = packageName;
     this.packageManager = packageManager;
-    this.outputDir = path.resolve(process.cwd(), `storage/plugins/${this.packageName}`);
+    this.outputDir = path.resolve(resolvePluginStoragePath(), this.packageName);
   }
 
   get token() {

package/src/commands/start.js

@@ -13,6 +13,8 @@ const { existsSync, rmSync } = require('fs');
 const { resolve, isAbsolute } = require('path');
 const chalk = require('chalk');
 const chokidar = require('chokidar');
+const { buildAppDevServerArgs, shouldUseAppDevServerSource } = require('./app-dev-utils');
+const { resolvePluginStoragePath } = require('@nocobase/utils/plugin-symlink');
 
 function getSocketPath() {
   const { SOCKET_PATH } = process.env;
@@ -52,6 +54,7 @@ module.exports = (cli) => {
     .allowUnknownOption()
     .action(async (opts) => {
       checkDBDialect();
+      const useAppDevServerSource = shouldUseAppDevServerSource();
       if (opts.quickstart) {
         await downloadPro();
       }
@@ -62,7 +65,7 @@ module.exports = (cli) => {
           await run('yarn', ['nocobase', 'pm2-restart']);
         }, 500);
 
-        const watcher = chokidar.watch('./storage/plugins/**/*', {
+        const watcher = chokidar.watch(`${resolvePluginStoragePath()}/**/*`, {
           cwd: process.cwd(),
           ignoreInitial: true,
           ignored: /(^|[\/\\])\../, // 忽略隐藏文件
@@ -99,7 +102,7 @@ module.exports = (cli) => {
         ]);
         return;
       }
-      if (!existsSync(resolve(process.cwd(), `${APP_PACKAGE_ROOT}/lib/index.js`))) {
+      if (!useAppDevServerSource && !existsSync(resolve(process.cwd(), `${APP_PACKAGE_ROOT}/lib/index.js`))) {
         console.log('The code is not compiled, please execute it first');
         console.log(chalk.yellow('$ yarn build'));
         console.log('If you want to run in development mode, please execute');
@@ -136,12 +139,21 @@ module.exports = (cli) => {
             ].filter(Boolean),
           );
         } else {
-          run(
-            'node',
-            [`${APP_PACKAGE_ROOT}/lib/index.js`, ...(NODE_ARGS || '').split(' '), ...process.argv.slice(2)].filter(
-              Boolean,
-            ),
-          );
+          if (useAppDevServerSource) {
+            promptForTs();
+            run('tsx', buildAppDevServerArgs(), {
+              env: {
+                IS_DEV_CMD: 'true',
+              },
+            });
+          } else {
+            run(
+              'node',
+              [`${APP_PACKAGE_ROOT}/lib/index.js`, ...(NODE_ARGS || '').split(' '), ...process.argv.slice(2)].filter(
+                Boolean,
+              ),
+            );
+          }
         }
       }
     });

package/src/commands/update-deps.js

@@ -10,14 +10,23 @@
 const chalk = require('chalk');
 const { Command } = require('commander');
 const { resolve } = require('path');
-const { run, promptForTs, runAppCommand, hasCorePackages, downloadPro, hasTsNode, checkDBDialect } = require('../util');
+const {
+  run,
+  promptForTs,
+  runAppCommand,
+  hasCorePackages,
+  downloadPro,
+  hasTsNode,
+  checkDBDialect,
+  storagePathJoin,
+} = require('../util');
 const { existsSync, rmSync } = require('fs');
 const { readJSON, writeJSON } = require('fs-extra');
 const deepmerge = require('deepmerge');
 
 const rmAppDir = () => {
   // If ts-node is not installed, do not do the following
-  const appDevDir = resolve(process.cwd(), './storage/.app-dev');
+  const appDevDir = storagePathJoin('.app-dev');
   if (existsSync(appDevDir)) {
     rmSync(appDevDir, { recursive: true, force: true });
   }

package/src/commands/view-license-key.js

@@ -10,8 +10,8 @@
 const chalk = require('chalk');
 const { Command } = require('commander');
 const { keyDecrypt } = require('@nocobase/license-kit');
-const path = require('path');
 const fs = require('fs');
+const { storagePathJoin } = require('../util');
 
 /**
  *
@@ -22,8 +22,7 @@ module.exports = (cli) => {
     .command('view-license-key')
     .description('View License Key')
     .action(async (options) => {
-      const dir = path.resolve(process.cwd(), 'storage/.license');
-      const filePath = path.resolve(dir, 'license-key');
+      const filePath = storagePathJoin('.license', 'license-key');
       if (!fs.existsSync(filePath)) {
         console.log('License key not found at ' + filePath);
         return;

package/src/license.js

@@ -8,15 +8,15 @@
  */
 
 const chalk = require('chalk');
-const { resolve } = require('path');
 const fs = require('fs-extra');
 const { keyDecrypt, getEnvAsync } = require('@nocobase/license-kit');
 const { isEnvMatch } = require('@nocobase/plugin-license/utils/env');
 const { logger } = require('./logger');
+const { storagePathJoin } = require('./util');
 const { pick } = require('lodash');
 
 exports.getAccessKeyPair = async function () {
-  const keyFile = resolve(process.cwd(), 'storage/.license/license-key');
+  const keyFile = storagePathJoin('.license', 'license-key');
   if (!fs.existsSync(keyFile)) {
     logger.info('License key not found');
     return {};

package/src/plugin-generator.js

@@ -38,8 +38,11 @@ async function getProjectVersion() {
 
 class PluginGenerator extends Generator {
   constructor(options) {
-    const { log, context = {}, ...opts } = options;
-    super(opts);
+    const { log, context = {}, cwd, baseDir, ...opts } = options;
+    super({
+      ...opts,
+      baseDir: baseDir || cwd || process.cwd(),
+    });
     this.context = context;
     this.log = log || console.log;
   }

package/src/util.js

@@ -261,7 +261,7 @@ function normalizeAppDevFiles(appDevDir) {
 
 exports.generateAppDir = function generateAppDir() {
   const appPkgPath = dirname(dirname(require.resolve('@nocobase/app/src/index.ts')));
-  const appDevDir = resolve(process.cwd(), './storage/.app-dev');
+  const appDevDir = storagePathJoin('.app-dev');
   if (exports.isDev() && !exports.hasCorePackages() && appPkgPath.includes('node_modules')) {
     if (!existsSync(appDevDir)) {
       mkdirSync(appDevDir, { force: true, recursive: true });
@@ -374,6 +374,10 @@ function resolveV2PublicPath(appPublicPath = '/') {
 
 exports.resolveV2PublicPath = resolveV2PublicPath;
 
+function isAppDevHtml() {
+  return process.argv[2] === 'app-dev' || process.env.NOCOBASE_APP_DEV === 'true';
+}
+
 function buildIndexHtml(force = false) {
   const file = `${process.env.APP_PACKAGE_ROOT}/dist/client/index.html`;
   if (!fs.existsSync(file)) {
@@ -396,6 +400,7 @@ function buildIndexHtml(force = false) {
     .replace(/\{\{env.API_BASE_URL\}\}/g, process.env.API_BASE_URL || process.env.API_BASE_PATH)
     .replace(/\{\{env.WS_URL\}\}/g, process.env.WEBSOCKET_URL || '')
     .replace(/\{\{env.WS_PATH\}\}/g, process.env.WS_PATH)
+    .replace(/\{\{env.NOCOBASE_APP_DEV\}\}/g, isAppDevHtml() ? 'true' : 'false')
     .replace(/\{\{env.ESM_CDN_BASE_URL\}\}/g, process.env.ESM_CDN_BASE_URL || '')
     .replace(/\{\{env.ESM_CDN_SUFFIX\}\}/g, process.env.ESM_CDN_SUFFIX || '')
     .replace(/((?:src|href)=")(?:\.\/)?assets\//g, `$1${process.env.APP_PUBLIC_PATH}assets/`)
@@ -455,6 +460,7 @@ function storagePathJoin(...segments) {
 
 exports.resolveStorageRoot = resolveStorageRoot;
 exports.storagePathJoin = storagePathJoin;
+exports.resolvePluginStoragePath = resolvePluginStoragePath;
 /** @deprecated Use resolveStorageRoot — kept for backward compatibility */
 exports.generateStoragePath = resolveStorageRoot;
 
@@ -485,6 +491,17 @@ function generatePm2Home() {
 }
 
 exports.initEnv = function initEnv() {
+  const preserveSymlinksFlag = '--preserve-symlinks';
+  const currentNodeOptions = String(process.env.NODE_OPTIONS || '').trim();
+  const hasPreserveSymlinksFlag = currentNodeOptions
+    ? currentNodeOptions.split(/\s+/).includes(preserveSymlinksFlag)
+    : false;
+  if (!hasPreserveSymlinksFlag) {
+    process.env.NODE_OPTIONS = currentNodeOptions
+      ? `${currentNodeOptions} ${preserveSymlinksFlag}`
+      : preserveSymlinksFlag;
+  }
+
   const env = {
     APP_ENV: 'development',
     APP_KEY: 'test-jwt-secret',
@@ -504,11 +521,13 @@ exports.initEnv = function initEnv() {
     // PM2_HOME: generatePm2Home(),
     // SOCKET_PATH: generateGatewayPath(),
     NODE_MODULES_PATH: resolve(process.cwd(), 'node_modules'),
+    NODE_PATH: resolve(process.cwd(), 'node_modules'),
     PLUGIN_PACKAGE_PREFIX: '@nocobase/plugin-,@nocobase/plugin-sample-,@nocobase/preset-',
     SERVER_TSCONFIG_PATH: './tsconfig.server.json',
     CACHE_DEFAULT_STORE: 'memory',
     CACHE_MEMORY_MAX: 2000,
     BROWSERSLIST_IGNORE_OLD_DATA: true,
+    NOCOBASE_DEV_LOCAL_PLUGINS_ONLY: 'true',
     PLUGIN_STATICS_PATH: '/static/plugins/',
     APP_SERVER_BASE_URL: '',
     APP_BASE_URL: '',