nargo

⚡ 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 支持通过 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

🔗 相关项目

• nargo-compiler: 提供核心转译能力
• nargo-server: 驱动开发环境的 Web 服务
• nargo-workspace: 处理多包工作区的管理与调度
• nargo-types: 定义了跨模块共享的通用数据模型
• nargo-bundler: 提供高性能的代码打包能力
• nargo-linter: 提供代码静态分析能力

📚 文档

• 官方文档 - 详细的使用文档
• API 参考 - 完整的 API 参考
• 贡献指南 - 如何为 Nargo 项目做贡献

🤝 贡献

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

⚖️ License

MIT.

📞 联系我们

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

• Email: [email protected]
• GitHub: nargo-js/nargo