create-react-scaffold

创建 React 应用程序脚手架，专为 Vite 构建工具优化的路由解决方案

特性

• 🚀 专为 Vite + React 优化
• 📁 基于文件系统的路由
• 🔄 支持数据预加载
• 🎯 TypeScript 原生支持
• ⚡ 高性能并行加载
• 🛡️ 完善的错误处理
• 📦 轻量级，零额外依赖

安装

npm install create-react-scaffold

基础使用

import { createReactScaffold } from "create-react-scaffold";

// 创建应用
await createReactScaffold({
  root: "#root",           // 可选，默认 "#root"
  mode: "browser",         // 可选，支持 "browser" | "hash" | "memory"
  entry: "home",          // 可选，默认入口页面
});

高级配置

await createReactScaffold({
  root: "#root",
  mode: "browser",
  entry: "home",
  
  // 生命周期钩子
  async onStart() {
    console.log("应用启动");
  },
  
  async onBeforePage(pathInfo) {
    // 页面加载前显示loading
    return <Loading />;
  },
  
  async onPage(pageContent, pathInfo) {
    // 包装页面组件
    return <Layout>{pageContent}</Layout>;
  },
  
  async onAfterPage(pathInfo) {
    // 页面渲染完成
    console.log("页面加载完成", pathInfo);
  },
  
  async onNotFound(pathInfo) {
    // 处理404页面
    return <NotFound path={pathInfo.real} />;
  }
});

路由系统

URL 查找规则

假设 URL 为 https://example.com/path/to/app，查找规则为：

1. 查找 @/pages/path/to/app/index.jsx 或 @/pages/path/to/app/index.tsx
2. 该文件的默认导出必须为 React 组件

数据加载

支持页面级数据预加载：

// @/pages/user/profile/data.ts
export async function getPageData() {
  // 在页面组件加载前执行
  const userData = await fetchUserData();
  // 可以将数据存储到全局状态管理中
}

// 或者使用默认导出
export default async function() {
  await loadUserProfile();
}

项目约定

1. 页面目录: @/pages 为页面组件目录
2. 路由映射: URL路径 /path/to/app → 文件 @/pages/path/to/app/index.[jsx|tsx]
3. 数据文件: @/pages/path/to/app/data.[js|jsx|ts|tsx]
4. 路径别名: @ 指向 src 目录
5. BASE_URL: 自动使用 Vite 的 import.meta.env.BASE_URL

导航

import { goto } from "create-react-scaffold";

// 基础导航
goto("/user/profile");

// 带查询参数
goto("/search", { q: "react", page: 1 });

// 替换当前历史记录
goto("/login", undefined, "replace");

TypeScript 支持

完整的 TypeScript 类型定义：

import type { 
  CreateReactScaffoldOption,
  PathInfo,
  HistoryMode,
  NavigationType 
} from "create-react-scaffold";

支持的组件类型

• ✅ 函数组件
• ✅ 类组件
• ✅ React.memo 包装的组件
• ✅ React.forwardRef 包装的组件
• ✅ MobX observer 包装的组件
• ✅ 其他高阶组件（HOC）包装的组件

版本要求

• React 19.2.0+
• TypeScript 5.9.0+
• Vite 构建工具

更新日志

v1.1.0

• ✨ 使用 Vite 的 BASE_URL 环境变量
• 🔧 改进 TypeScript 类型安全
• ⚡ 优化页面加载性能
• 🛡️ 增强错误处理
• 📦 升级所有依赖到最新版本