nargo-compiler

🎯 简介

nargo-compiler 是 Nargo 编译链的核心调度中心，它集成了模板解析、脚本分析、样式提取、优化和代码生成，支持多种 DSL（如 Pug, Markdown, Scss 等）的混合编译。作为 Nargo 生态系统的核心组件，它实现了 Nargo 核心的 Reactive Transform 和 Atomic CSS 自动生成，为前端开发提供高效、优化的编译体验。

✨ 核心特性

Pipeline 编排

• 智能工作流: 自动协调 nargo-parser, nargo-optimizer 和各类 Target 生成器的工作流
• 并行处理: 支持多线程并行编译，提高编译速度
• 增量编译: 只重新编译变更的文件，大幅提升开发体验
• 错误处理: 提供详细的错误信息，帮助开发者快速定位问题

多语言支持

• 插件化架构: 通过插件化注册机制，支持多种语言和格式
• 原生支持: 原生支持 Pug, Markdown, Scss, Less, Tailwind, YAML, TOML 等多种格式
• 自定义插件: 支持自定义语言插件，扩展编译能力
• 语言集成: 支持在同一组件中混合使用多种语言

SSR & Hydration

• 服务端渲染: 支持一键生成服务端渲染函数
• 客户端激活: 生成客户端激活代码，实现 hydration
• 同构应用: 支持构建同构应用，兼顾 SEO 和用户体验
• 性能优化: 优化 SSR 性能，减少服务器负载

Reactive Transform

• 编译时优化: 在编译时识别响应式变量，自动处理变量访问
• 消除运行时开销: 消除运行时的 .value 开销，提升性能
• 智能转换: 智能处理响应式变量的读取和写入
• 类型安全: 保持类型安全，确保代码的可靠性

原子化样式引擎

• 深度集成: 深度集成 Tailwind CSS 支持
• 自动提取: 自动从组件中提取并生成最小化的 CSS
• 优化输出: 生成高效、最小化的原子化 CSS
• 运行时无依赖: 生成的 CSS 不依赖任何运行时库

高级优化

• 静态提升: 静态提升常量和不变表达式
• 常量折叠: 在编译时计算常量表达式
• 死代码消除: 移除未使用的代码
• 树摇优化: 智能移除未使用的模块

🚀 使用方法

命令行使用

# 构建项目
nargo build

# 启动开发服务器
nargo run dev

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

# 运行类型检查
nargo check

# 运行测试
nargo test

# 生成类型文档
nargo docs

API 使用

use nargo_compiler::{Compiler, CompilerOptions};
use std::path::Path;

fn main() -> anyhow::Result<()> {
    // 创建编译器实例
    let mut compiler = Compiler::new();

    // 配置编译选项
    let options = CompilerOptions {
        entry_point: Path::new("src/main.nargo").to_path_buf(),
        output_dir: Path::new("dist").to_path_buf(),
        enable_ssr: true,
        enable_hydration: true,
        optimization_level: 2,
        ..Default::default()
    };

    // 执行编译
    compiler.compile(&options)?;

    println!("编译成功！");
    Ok(())
}

🔧 配置选项

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

[tool.nargo.compiler]
# 编译配置
entry_point = "src/main.nargo"
output_dir = "dist"
optimization_level = 2  # 0-3，3 为最高优化级别

# 语言支持
[tool.nargo.compiler.languages]
enable_pug = true
enable_markdown = true
enable_scss = true
enable_less = true
enable_tailwind = true

# SSR 配置
[tool.nargo.compiler.ssr]
enable = true
enable_hydration = true
ssr_output_dir = "dist/ssr"

# 样式配置
[tool.nargo.compiler.style]
enable_atomic_css = true
css_output_dir = "dist/css"
minify_css = true

# 开发服务器配置
[tool.nargo.compiler.dev]
enable_hmr = true
port = 3000
host = "localhost"

📊 与其他编译器对比

🎯 应用场景

单页应用开发

在单页应用开发中，nargo-compiler 提供快速的开发体验和高效的构建产物，支持多种前端框架和库。

服务端渲染应用

在服务端渲染应用中，nargo-compiler 提供一键式 SSR 支持，生成优化的服务端渲染函数和客户端激活代码。

静态网站生成

在静态网站生成中，nargo-compiler 可以生成静态 HTML 文件，支持 Markdown 等多种内容格式。

组件库开发

在组件库开发中，nargo-compiler 提供高效的组件编译和优化，支持多种样式方案和组件格式。

🔧 核心 API

Compiler

编译器的核心类，负责整个编译过程的协调和执行：

• new: 创建新的编译器实例
• compile: 执行编译过程
• compile_file: 编译单个文件
• compile_dir: 编译整个目录
• set_options: 设置编译选项

CompilerOptions

编译选项，控制编译过程的各个方面：

• entry_point: 入口文件路径
• output_dir: 输出目录路径
• optimization_level: 优化级别
• enable_ssr: 是否启用 SSR
• enable_hydration: 是否启用 hydration
• languages: 启用的语言支持

Session

编译会话，管理编译过程中的状态和资源：

• new: 创建新的会话
• add_file: 添加文件到会话
• compile: 编译会话中的文件
• get_output: 获取编译输出

IRModule

中间表示模块，存储编译过程中的中间数据：

• new: 创建新的中间表示模块
• add_node: 添加节点到模块
• optimize: 优化模块
• generate_code: 生成代码

🏗️ 核心逻辑

1. Registry Init: 初始化解析器注册表，加载所有支持的语言插件
2. Parsing: 调用 nargo-parser 将 SFC 拆分为块，并使用匹配的子解析器生成 IRModule
3. Optimization: 使用 nargo-optimizer 进行静态提升、常量折叠和样式提取
4. Code Generation:
   • 若开启 SSR，调用 nargo-ssr 生成渲染函数
   • 若开启 Hydrate，调用 nargo-hydrate 生成激活逻辑
   • 默认调用 nargo-bundler 生成客户端运行时代码
5. Asset Bundling: 汇总生成的 JS、CSS 和 Source Map
6. Output: 将编译产物输出到指定目录

🔗 相关项目

• nargo-parser: 负责第一阶段的语法拆解
• nargo-optimizer: 负责中间表示的优化
• nargo-bundler: 负责代码打包和运行时生成
• nargo-types: 基础类型定义
• nargo-ssr: 服务端渲染支持
• nargo-hydrate: 客户端激活支持

📚 文档

• 官方文档 - 详细的使用文档
• API 参考 - 完整的 API 参考
• 优化指南 - 编译优化最佳实践指南
• 插件开发 - 编译器插件开发指南

🤝 贡献

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

⚖️ License

MIT.

📞 联系我们

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

• Email: team@nargo.dev
• GitHub: nargo-js/nargo