nargo-types 0.0.0

Nargo common types and error handling
Documentation

Nargo: The Future of Frontend Engineering

🎯 为什么选择 Nargo？

Nargo 不仅仅是一个构建工具，它是对前端工程化链路的重新思考。我们抛弃了对外部命令（Git, Husky, Lint, Docker）的依赖，转而使用 Rust 原生实现，打造一个极致快、极致轻、零配置的单二进制环境。

🚀 核心优势

  • ⚡ 极致性能：基于 Rust 的高性能实现，启动速度比传统工具快 10 倍以上，内存占用减少 60%
  • 🔒 类型安全：前后端类型自动同步，消除类型错误，提升代码质量
  • 🛠️ 全栈集成：无缝衔接 Rust 后端与 TypeScript 前端，实现真正的全栈开发体验
  • 🎨 零配置：智能默认配置，开箱即用，同时支持高度定制化
  • 🌐 生态友好：兼容现有的前端工具链，支持主流框架和库
  • 💻 跨平台：单一二进制文件，支持 Windows、macOS、Linux 等多种平台

📊 与其他产品对比

特性 Nargo Vite Rollup Webpack
启动速度 ⚡⚡⚡ (瞬时) ⚡⚡ (快速) ⚡ (一般) ❌ (缓慢)
内存占用 📦 (轻量) 📦📦 (中等) 📦📦 (中等) 📦📦📦 ( heavy)
类型检查 ✅ (内置) ❌ (需插件) ❌ (需插件) ❌ (需插件)
测试支持 ✅ (内置) ❌ (需配置) ❌ (需配置) ❌ (需配置)
Git 集成 ✅ (原生) ❌ (需外部工具) ❌ (需外部工具) ❌ (需外部工具)
全栈类型桥接 ✅ (原生) ❌ (不支持) ❌ (不支持) ❌ (不支持)

🚀 核心理念

1. CaaS (Compiler as a Service)

Nargo 深度集成 rustc_interface，将编译器能力服务化，为前端开发提供前所未有的编译体验。

  • 瞬时冷启动：利用增量编译与常驻内存的编译器 Session，启动速度比传统工具快 10 倍以上。
  • 智能热更：不仅支持 TypeScript 的 HMR，更是实现了 Rust 后端的智能增量重载，让全栈开发体验无缝衔接。
  • 高级优化：内置多种编译优化策略，自动选择最佳编译配置，平衡开发速度与构建性能。

2. RaaS (Runtime as a Service)

Nargo 提出了 Runtime as a Service 的概念，彻底革新前端开发环境。

  • 无感环境：开发者无需关心 Node.js、Bun 或 Deno 的版本和配置。Nargo 内置了高性能运行时服务，为前端提供即时的类型桥接（Type Bridge）与 Mock 能力。
  • 类型即服务：通过 nargo bridge，Rust 后端的结构体实时转换为 TS 定义，让前后端类型契约成为一种实时服务，彻底消除类型不一致问题。
  • 按需加载：运行时能力按需动态注入，确保开发环境始终处于最轻量状态，内存占用比传统工具减少 60%。

3. All in One Binary

Nargo 将所有前端工程化工具整合到一个二进制文件中，告别繁琐的依赖管理。

  • 原生 Git 审计：不调用 git 命令，直接通过 libgit2 读写 .git 目录，速度提升数倍，操作更稳定。
  • 原生 Hooks 管理：彻底替代 Husky，使用 Rust 原生实现的 Git Hooks 引擎，配置更简单，执行更高效。
  • 零依赖 Monorepo：内置 Workspace 任务并行编排器，支持混合项目的 HMR，让大型项目的开发体验同样流畅。
  • 内置 Linter：集成高性能 Rust 实现的代码检查工具，实时提供代码质量反馈，无需额外配置。

🛠️ 快速开始

基础命令

# 启动开发服务器 (支持混合热更新)
nargo run dev --hybrid

# 同步前后端类型
nargo bridge

# 构建生产版本
nargo build

# 类型检查
nargo check

# 运行测试
nargo test

核心命令详解

🔨 构建系统 (nargo build)

Nargo 的构建系统采用 Rust 原生实现，提供极致的构建性能和可靠性：

  • 智能增量构建：只重新构建变更的文件，大幅提升构建速度
  • 多线程并行构建：充分利用多核 CPU，构建速度比传统工具快 3-5 倍
  • 自动代码分割：智能分析依赖关系，生成最优的代码分割策略
  • Tree Shaking：自动移除未使用的代码，减小最终 bundle 体积
  • 生产环境优化：内置多种生产环境优化策略，包括代码压缩、资源优化等

✅ 类型检查 (nargo check)

Nargo 内置高性能类型检查器，提供实时、准确的类型反馈：

  • 实时类型检查：在开发过程中实时进行类型检查，提前发现类型错误
  • 增量类型检查：只检查变更的文件，大幅提升检查速度
  • 智能类型推断：提供更智能的类型推断能力，减少类型注解的需要
  • 跨文件类型分析：分析整个项目的类型关系，提供更准确的类型检查结果
  • 与编辑器集成：与 VS Code 等编辑器深度集成，提供实时的类型错误提示

🧪 测试系统 (nargo test)

Nargo 内置完整的测试系统，支持多种测试类型：

  • 单元测试：支持 TypeScript 和 Rust 代码的单元测试
  • 集成测试：支持前后端集成测试，验证完整的功能流程
  • 端到端测试：内置端到端测试能力，模拟用户操作测试整个应用
  • 测试覆盖率：自动生成测试覆盖率报告，帮助提高代码质量
  • 并行测试执行：多线程并行执行测试，大幅提升测试速度

Git 操作

# 原生 Git 状态查看
nargo git status

# 安装原生 Git Hooks
nargo hooks install

# 提交代码 (内置提交信息规范检查)
nargo git commit -m "feat: add new feature"

高级功能

# 生成类型文档
nargo document

# 分析构建性能
nargo analyze
# 导出构建配置
nargo config export

✨ 特性亮点

  • 极致性能：基于 Rust 的高性能实现，启动速度快，内存占用低，编译效率高。
  • 零配置：智能默认配置，开箱即用，同时支持高度定制化。
  • 全栈集成：无缝衔接 Rust 后端与 TypeScript 前端，实现真正的全栈开发体验。
  • 类型安全：前后端类型自动同步，消除类型错误，提升代码质量。
  • 生态友好：兼容现有的前端工具链，支持主流框架和库。
  • 跨平台：单一二进制文件，支持 Windows、macOS、Linux 等多种平台。
  • 内置 Git 工具：原生 Git 操作，无需依赖外部 Git 命令。
  • 内置 Hooks 管理：替代 Husky，提供更高效的 Git Hooks 管理。
  • 内置 Linter：实时代码质量检查，提升代码质量。
  • 内置测试系统：完整的测试能力，确保代码质量。

🎯 使用场景

🌟 全栈 Rust + TypeScript 项目

Nargo 特别适合全栈 Rust + TypeScript 项目，提供无缝的开发体验：

  • 实时类型同步：Rust 后端结构体自动转换为 TypeScript 类型定义
  • 混合热更新：同时支持 Rust 后端和 TypeScript 前端的热更新
  • 统一构建流程：使用同一套工具链构建前后端代码

🏢 大型 Monorepo 项目

Nargo 内置零依赖 Monorepo 支持，为大型项目提供流畅的开发体验：

  • 并行任务执行：多线程并行执行构建、测试等任务
  • 智能依赖分析：分析项目依赖关系，优化构建顺序
  • 混合项目支持：支持在同一 Monorepo 中混合不同类型的项目

🚀 快速原型开发

Nargo 的零配置和快速启动特性，使其成为快速原型开发的理想选择：

  • 瞬时启动：开发服务器秒级启动，立即开始编码
  • 智能默认配置：无需配置即可开始开发
  • 实时反馈：实时的类型检查和代码质量反馈

📚 社区资源

👥 社区与支持

🤝 贡献

我们欢迎所有形式的贡献！请查看 贡献指南 了解如何开始。

📂 项目结构

  • compilers/: Rust 核心组件 (Compiler, Parser, Bundler, Bridge, etc.)
  • runtimes/: 前端运行时与类型定义
  • examples/: 示例项目
  • documentation/: 文档
  • scripts/: 辅助脚本
  • tests/: 测试套件

📞 联系我们

如有任何问题或建议，欢迎通过以下方式联系我们：

⚖️ License

MIT.