前端业务开发

@modu/web 提供平台页面、运行时、Umi 适配、类型、样式和扩展加载。应用负责自己的页面、品牌配置、services 与业务类型。

安装 Umi 适配

在 config/config.ts 注册 require.resolve('@modu/web/umi')，并保留模板启用的 model、initialState、access、request、locale、layout 和 antd 配置。

核心 model 由插件注册。不要依赖核心源码中的 .umi 生成目录，也不要将应用 alias 指向核心工作树。

适配器通过 modifyConfig 固定 mfsu: false，开发环境统一使用常规 Webpack 编译。核心消费应用生成的 Umi 运行时，React、UI Context 与第三方依赖需共享同一运行时；不要重新启用 MFSU 或仅将核心排除出 MFSU。生产构建和扩展 lazy chunk 不受影响。

在线安装时，GitHub Packages 的实际包名是 @igwen6w/modu-web，安装工具将依赖值设为 npm:@igwen6w/modu-web@0.13.0。应用的依赖键和所有公开 import 继续使用 @modu/web。

组合业务路由

在 config/routes.ts 使用 createRoutes：

import { createRoutes } from '@modu/web/umi';
import type { GeneratedExtensionCatalog } from '@modu/web/extensions';
import catalog from '../src/extensions/catalog.json';

export default createRoutes(
  [{
    path: '/example/currency',
    name: 'example.currency',
    component: './example/currency',
  }],
  catalog as GeneratedExtensionCatalog,
);

它组合核心路由、应用路由与扩展页面，并检查冲突。应用路由注册在核心 catch-all 之前，菜单父子路径保持一致。

组合运行时

src/app.tsx 沿用模板的公开接入方式：

import { createRuntime } from '@modu/web';
import type { GeneratedExtensionCatalog } from '@modu/web/extensions';
import settings from '../config/defaultSettings';
import catalog from './extensions/catalog.json';
import { extensionBindings } from './extensions/bindings';

const runtime = createRuntime({
  settings,
  extensions: {
    catalog: catalog as GeneratedExtensionCatalog,
    bindings: extensionBindings,
  },
});

export const getInitialState = runtime.getInitialState;
export const layout = runtime.layout;
export const request = runtime.request;
export const locale = runtime.locale;
export const rootContainer = runtime.rootContainer;

页面、请求与样式

页面通过应用 src/services 调用接口，HTTP 使用 @umijs/max 的 request。路由、权限和状态分别走 Umi 路由配置、access.ts 与 useModel。

应用 src/global.ts 导入 @modu/web/styles.css。类型从 @modu/web/types 显式导入；业务类型和语言资源留在应用。

稳定子路径出口

业务页面优先使用 @modu/web 的稳定子路径出口组合页面骨架，不进入 lib/src/... 等深路径：

@modu/web/pro-list：ProListPage 与 TablePreset，用于标准列表页。
@modu/web/page-layout：PageLayout 页面骨架。
@modu/web/list-layout：ListLayout 与 ListAside，用于带侧栏的列表布局。
@modu/web/components/files：FileAttachments、FileUploader、ImageUploader、MultiImageUploader、FilePicker、FilePreview 等附件组件。
@modu/web/components/unsaved-guard：useUnsavedGuard、useUnsavedStateGuard、GuardedModalForm，用于未保存离开守卫。
@modu/web/components/action-collapse：ActionCollapse 与 optionColumn，用于表格操作列折叠。
@modu/web/components/data-transfer 与 @modu/web/services/dataTransfer：数据交换组件与请求服务。

根出口 @modu/web 另提供 PageContainer、usePageHeaderPolicy、AuthorizationConsole 与 DelegatedConsole；@modu/web/extensions 的 useExtensionMessages() 供扩展页面读取扩展语言资源。

antd 定制收敛在运行时配置和组件隔离层，使用 v6 Design Token / CSS Variables。页面不直接引用 antd/es/... 内部路径或 deprecated props。

提交前验证

在应用 web 运行 pnpm lint、pnpm typecheck 与 pnpm build。涉及扩展时加上 pnpm extension:check 和构建后的 pnpm extension:verify-build。

扩展页面的惰性加载与语言资源见扩展前端接入。