nargo 0.0.0

Nargo compiler and toolchain
Documentation

nargo

🎯 简介

nargo 是 Nargo 编译工具链的核心入口点，它不仅是一个命令行工具，更是一个高度集成的开发工作站。通过封装底层的编译器、打包器、测试运行器、Linter 以及开发服务器，nargo 为开发者提供了一套完整、一致且极速的开发流程。无论是在单体应用还是复杂的 Monorepo 项目中，nargo 都能提供卓越的性能支撑。

✨ 核心特性

  • 一站式工作流: 集成了从项目初始化、开发调试、自动化测试、静态分析到生产构建的全生命周期指令。
  • Monorepo 原生支持: 深度集成 nargo-workspace，能够自动识别工作区结构，支持跨包任务编排与混合热更新。
  • 极致性能: 核心链路均采用 Rust 编写，利用多线程并发与增量编译技术，显著提升开发反馈速度。
  • 全方位的质量保障: 内置 Linter、安全审计 (Audit)、代码格式化 (Format) 以及高精度的基准测试 (Bench)。
  • 原生能力扩展: 提供高性能的 Git 操作封装及 Git Hooks 自动化管理。
  • 智能类型桥接: 通过 nargo bridge 命令，实现 Rust 后端与 TypeScript 前端的类型自动同步。

🏗️ 核心指令详解

开发与调试

nargo run dev

启动带有 HMR 和 Mock 功能的高性能开发服务器：

  • 混合热更新: 同时支持 TypeScript 前端和 Rust 后端的热更新
  • 智能 Mock: 内置 Mock 服务，无需后端即可进行前端开发
  • 实时类型检查: 开发过程中实时进行类型检查，提前发现错误
  • 多线程编译: 利用多核 CPU 加速编译过程
# 启动开发服务器
nargo run dev

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

# 指定端口
nargo run dev --port 3000

构建与部署

nargo build

执行生产环境构建，生成极致优化的代码产物：

  • 智能增量构建: 只重新构建变更的文件
  • 多线程并行构建: 充分利用多核 CPU
  • 自动代码分割: 智能分析依赖关系，生成最优的代码分割策略
  • Tree Shaking: 自动移除未使用的代码
  • 生产环境优化: 内置多种生产环境优化策略
# 构建生产版本
nargo build

# 构建特定环境
nargo build --env staging

# 启用详细输出
nargo build --verbose

测试与质量

nargo test

运行单元测试、集成测试，并支持基于插桩的代码覆盖率收集：

  • 多测试类型支持: 单元测试、集成测试、端到端测试
  • 并行测试执行: 多线程并行执行测试
  • 测试覆盖率: 自动生成测试覆盖率报告
  • 智能测试选择: 支持按模式选择测试
# 运行所有测试
nargo test

# 运行特定测试
nargo test --pattern "user*"

# 生成测试覆盖率报告
nargo test --coverage

nargo lint

对项目进行全方位的静态代码检查，识别潜在风险：

  • 多语言支持: 支持 TypeScript、Rust、CSS 等多种语言
  • 实时检查: 开发过程中实时进行代码检查
  • 可配置规则: 支持自定义检查规则
  • 自动修复: 支持自动修复某些类型的问题
# 运行代码检查
nargo lint

# 自动修复问题
nargo lint --fix

# 检查特定目录
nargo lint src/components

nargo format

自动化格式化 Nargo 组件（Template, Script, Style）：

  • 统一代码风格: 确保项目代码风格一致
  • 多语言支持: 支持多种语言的格式化
  • 可配置规则: 支持自定义格式化规则
  • 批量处理: 支持批量格式化多个文件
# 格式化所有文件
nargo format

# 检查格式但不修改
nargo format --check

# 格式化特定文件
nargo format src/components/Button.tsx

性能与安全

nargo bench

执行高精度的性能基准测试，辅助开发者进行性能调优：

  • 高精度测量: 提供精确的性能测量数据
  • 趋势分析: 跟踪性能变化趋势
  • 多维度测试: 支持多种性能指标测试
  • 比较模式: 支持与历史版本比较
# 运行基准测试
nargo bench

# 与历史版本比较
nargo bench --compare

# 测试特定功能
nargo bench --pattern "render*"

nargo audit

进行项目安全扫描，识别硬编码凭据与危险依赖：

  • 依赖扫描: 检查依赖项的安全漏洞
  • 代码审计: 识别硬编码的凭据和敏感信息
  • 配置检查: 检查项目配置中的安全问题
  • 报告生成: 生成详细的安全审计报告
# 运行安全审计
nargo audit

# 生成详细报告
nargo audit --report

# 忽略特定漏洞
nargo audit --ignore CVE-2023-1234

Monorepo 管理

nargo run

在 Monorepo 环境下跨包运行任务，支持复杂的依赖关系处理：

  • 智能依赖分析: 自动分析包之间的依赖关系
  • 并行任务执行: 多线程并行执行任务
  • 任务编排: 支持复杂的任务编排
  • 环境一致性: 确保所有包使用一致的环境
# 运行特定包的任务
nargo run build --package my-package

# 并行运行多个任务
nargo run build --parallel

# 运行工作区所有包的任务
nargo run test --workspace

类型桥接

nargo bridge

同步 Rust 后端与 TypeScript 前端的类型定义：

  • 实时同步: 自动同步 Rust 结构体到 TypeScript 类型
  • 类型安全: 确保前后端类型一致
  • 减少手动工作: 无需手动编写类型定义
  • 支持复杂类型: 支持复杂的嵌套类型和泛型
# 同步类型
nargo bridge

# 生成类型文档
nargo bridge --docs

# 自定义输出路径
nargo bridge --output src/types/rust.d.ts

📊 与其他工具对比

特性 Nargo CLI npm/yarn pnpm Cargo
启动速度 ⚡⚡⚡ (瞬时) ⚡ (一般) ⚡⚡ (快速) ⚡⚡ (快速)
内存占用 📦 (轻量) 📦📦📦 (heavy) 📦📦 (中等) 📦📦 (中等)
内置测试 ✅ (完整) ❌ (需配置) ❌ (需配置) ✅ (完整)
内置 lint ✅ (完整) ❌ (需插件) ❌ (需插件) ❌ (需插件)
内置格式化 ✅ (完整) ❌ (需插件) ❌ (需插件) ❌ (需插件)
Monorepo 支持 ✅ (原生) ❌ (需工具) ✅ (原生) ❌ (需工具)
类型桥接 ✅ (原生) ❌ (不支持) ❌ (不支持) ❌ (不支持)

🔧 配置选项

nargo 支持通过 nargo.config.toml 文件进行配置：

[tool.nargo]
# 开发服务器配置
[tool.nargo.dev]
port = 3000
hmr = true

# 构建配置
[tool.nargo.build]
env = "production"
optimization = "aggressive"

# 测试配置
[tool.nargo.test]
coverage = true
parallel = true

# Linter 配置
[tool.nargo.lint]
enable = true
rules = ["no-unused-vars", "no-console"]

🚀 快速开始

安装

# 从源码构建
cargo install --path compilers/nargo

# 或使用预编译二进制文件
curl -fsSL https://nargo.dev/install.sh | bash

初始化项目

# 初始化新项目
nargo init my-project

# 初始化 Monorepo 项目
nargo init my-monorepo --workspace

# 使用特定模板
nargo init my-project --template react

🔗 相关项目

📚 文档

🤝 贡献

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

⚖️ License

MIT.

📞 联系我们

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