@vlian/framework

Secra Framework - 一个现代化的低代码前端应用框架

简介

Secra Framework 是一个低门槛、高可扩展、面向团队的前端应用启动框架，让开发者一行配置即可快速启动完整基础设施，同时保持长期可演进与插件生态自由。

特性

• 🚀 开箱即用：一行配置即可启动完整基础设施
• 🔌 插件化架构：支持中间件和插件系统，灵活扩展
• 🌍 国际化支持：基于 i18next 的多语言支持
• 🎨 主题系统：支持浅色/深色/自动主题切换
• 🔄 状态管理：统一的状态管理抽象，支持多种适配器
• 🛣️ 路由系统：配置驱动的路由系统，支持权限控制
• 📡 请求库：企业级请求库，支持多种 HTTP 适配器
• 🔒 安全防护：XSS 防护、配置验证、输入清理等安全功能
• 📊 性能监控：Web Vitals 收集和性能指标监控
• 🐛 错误处理：完整的错误类型体系和错误边界

安装

# 使用 pnpm
pnpm add @vlian/framework

# 使用 npm
npm install @vlian/framework

# 使用 yarn
yarn add @vlian/framework

快速开始

基本使用

import { startApp } from '@vlian/framework';
import App from './App';

// 启动应用
await startApp({
  app: <App />,
});

完整配置示例

import { startApp, LogLevel } from '@vlian/framework';
import App from './App';

await startApp({
  app: <App />,
  loggerLevel: LogLevel.DEBUG,
  theme: {
    mode: 'dark',
    primaryColor: '#1890ff',
  },
  locale: {
    'zh-CN': {
      common: {
        confirm: '确认',
        cancel: '取消',
      },
    },
    'en-US': {
      common: {
        confirm: 'Confirm',
        cancel: 'Cancel',
      },
    },
  },
  router: {
    enabled: true,
    mode: 'browser',
    routes: [
      {
        path: '/',
        component: './pages/Home',
        meta: { title: '首页' },
      },
    ],
  },
});

按需导入

框架支持按需导入（Tree Shaking），可以显著减少打包体积。主入口 @vlian/framework 主要用于兼容和快速接入，生产环境优先使用子路径导入来减少最终应用体积：

// 只导入核心启动功能
import { startApp } from '@vlian/framework/core';

// 只导入工具函数
import { logger, LogLevel } from '@vlian/framework/utils';

// 只导入状态管理
import { StateManager } from '@vlian/framework/state';

// 只导入请求库
import { createRequestClient } from '@vlian/framework/request';

// 只导入国际化
import { setupI18n, $t } from '@vlian/framework/library';

可用的子路径

• @vlian/framework/core - 核心模块（启动、上下文、路由等）
• @vlian/framework/utils - 工具模块（日志、验证、安全等）
• @vlian/framework/state - 状态管理模块
• @vlian/framework/library - 基础库模块（国际化、存储等）
• @vlian/framework/request - 请求库模块
• @vlian/framework/components - 组件模块（当前为空）

打包体积优化

使用按需导入可以减少 30-50% 的打包体积，具体取决于你使用的功能。详细说明请查看 按需导入使用指南。

外部依赖说明

为了减小包体积，框架会将宿主应用应自行提供的核心依赖保持为外部依赖。安装本包时，请同时根据使用场景安装对应依赖：

• react
• react-dom
• react-router-dom
• i18next
• react-i18next
• react-error-boundary
• zod

核心模块

Core 模块

框架的核心模块，提供启动、上下文管理、初始化、错误边界等功能。

Utils 模块

工具模块，提供日志、错误处理、验证、安全、监控等功能。

Library 模块

基础库模块，提供国际化、存储等功能。

State 模块

状态管理模块，提供统一的状态管理抽象，支持多种适配器。

Request 模块

请求库模块，提供企业级请求能力，支持多种 HTTP 适配器和插件系统。

文档

详细文档请查看 docs/README.md

依赖要求

• React: ^18.0.0 || ^19.0.0
• React DOM: ^18.0.0 || ^19.0.0
• React Router DOM: ^7.0.0
• react-error-boundary: ^6.0.0

许可证

Apache-2.0

相关链接

• 文档
• 变更日志