fuels-ts SDK API 参考站实现基于 TypeDoc 的 docs-api 工作区详解【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts本篇围绕apps/docs-api这一应用展开它是 fuels-tsFuel v2 的 TypeScript SDK的 API 文档站由 TypeDoc 从各子包的源码与 TSDoc 注释生成。读完本文你会了解该文档站的主页结构index.md、TypeDoc 配置中每个字段的作用、pnpm Turborepo 下的构建链路以及 16 个包入口与packages/目录实际结构之间的对应关系从而能够在本仓库中定位、验证并复现整套 API 文档的生成流程。1. docs-api一个只含 4 个文件的应用在 fuels-ts 这个 pnpm Turborepo monorepo 中apps/docs-api是专门负责生成 SDK API 参考文档的工作区应用。它的全部文件只有 4 个文件职责index.md文档站首页内容TypeDoc 的readme包含站点标题与模块导航列表typedoc.jsonTypeDoc 核心配置入口包列表、输出目录、站点名、导航链接等package.json声明私有包docs-api及构建脚本build: typedocturbo.json声明 build 任务的缓存输出为src/**从 package.json 可以看到关键信息{ private: true, name: docs-api, version: 0.0.1, type: module, scripts: { build: typedoc }, devDependencies: { fuels: workspace:*, typedoc: 0.26.3 } }两点值得注意private: true且版本号固定为0.0.1说明它是一个纯内部工具包不会发布到 npmdevDependencies 里通过workspace:*依赖了聚合包fuels使 TypeDoc 能解析到 monorepo 内部包之间的类型引用TypeDoc 固定使用0.26.3版本。2. 站点首页 index.md一句话定位 模块导航index.md 会被 TypeDoc 作为首页渲染。其内容结构非常紧凑一张 SDK Logo 图片picture元素按浅色/深色主题切换两张图源一句话定位第 6 行fuels-tsis a library for interacting withFuel v2.即 fuels-ts 是用于与 Fuel v2 交互的 TypeScript 库这是整个 SDK 的自我定位一组徽章测试状态、npm 上fuels包版本、文档入口、社区频道分别指向 CI workflow、npm 包页面、官方文档站与社区一个Modules导航列表第 13–26 行列出 12 个模块abi-coder、abi-typegen、account、address、crypto、errors、hasher、math、program、script、transactions、utils。需要注意链接的解析基准index.md中的模块链接形如modules/_fuel_ts_abi_coder.html这是TypeDoc 生成站点输出目录src/api见下文内部的相对路径解析基准是生成后的站点根而不是仓库根目录——因此在本仓库中不应按相对路径直接访问这些链接它们是构建产物的页面文件名。首页模块列表与仓库实际包结构的差异将index.md的 12 个模块与 packages/ 目录实际内容对照可以观察到两处不一致均为对现状的客观描述index.md的列表未包含contract、recipes、merkle等实际存在的包。contract合约工厂与合约调用、recipesSway 程序模板示例其 package.json 描述为 “Recipes for Sway Programs”等都有独立源码目录但未出现在首页导航中反过来typedoc.json 的入口列表里包含packages/interfaces与packages/predicate而当前仓库packages/目录下并不存在这两个目录。从源码结构看这很可能是包拆分/迁移历史留下的陈旧配置谓词、接口相关能力如今分布在account、program等包中但配置本身尚未清理。这类“首页导航、TypeDoc 入口、真实目录”三者不一致的情况正是阅读 API 文档生成配置时需要特别注意的地方。3. typedoc.json逐项解读核心配置apps/docs-api/typedoc.json 是理解整个文档站的关键全文仅 31 行{ $schema: https://typedoc.org/schema.json, entryPointStrategy: packages, entryPoints: [ ../../packages/abi-coder, ../../packages/abi-typegen, ../../packages/address, ../../packages/interfaces, ../../packages/predicate, ../../packages/account, ../../packages/program, ../../packages/contract, ../../packages/script, ../../packages/utils, ../../packages/crypto, ../../packages/errors, ../../packages/hasher, ../../packages/math, ../../packages/transactions, ../../packages/recipes ], out: src/api, readme: ./index.md, name: Fuels TS SDK API Documentation, navigationLinks: { Docs: …官方文档站…, GitHub: …项目源码仓库… }, logLevel: Error }各字段的作用字段取值作用entryPointStrategypackages以npm 包为入口单元解析类型TypeDoc 会读取每个入口的package.json来确定包名与类型入口而不是以单个 TS 文件为单位entryPoints16 个包路径文档化范围从apps/docs-api出发以../../packages/*相对路径列出。当前packages/下还有create-fuels、fuel-gauge、fuels、logger、merkle、versions等包不在入口列表中——其中fuels是纯再导出聚合包create-fuels是脚手架 CLI、fuel-gauge是测试包不单独生成 API 文档是合理的取舍outsrc/api生成的静态站点输出到apps/docs-api/src/api/下readme./index.md首页取自该 Markdown 文件即第 2 节分析的内容nameFuels TS SDK API Documentation站点标题navigationLinks两个外部链接在文档站导航栏提供通往官方使用文档与源码仓库的跳转外链地址见配置文件原文本文不重复罗列logLevelError配置注释写明“Suppress all the warnings that are being thrown by typedoc”即把日志级别提到 Error压制生成过程中的告警噪音与 typedoc.base.json 及子包配置的关系仓库根目录还有一份 typedoc.base.json内容只有includeVersion: true表示生成的文档携带 SDK 版本号。各子包如 packages/abi-coder/typedoc.json各自维护一份继承自它的配置形如{ extends: [../../typedoc.base.json], entryPoints: [src/index.ts], readme: none }也就是说每个包既可以独立生成带版本的 API 文档也可以被docs-api聚合为一个统一站点。docs-api使用entryPointStrategy: packages时TypeDoc 正是借助各包的package.json与其入口配置来解析类型的。4. 构建链路pnpm workspace → Turborepo → typedoc文档站的构建完全嵌入 monorepo 的标准流程依赖安装根 package.json 声明运行环境为 Node^20.0.0 || ^22.0.0 || ^24.0.0、pnpm^9.4.0packageManager: pnpm9.4.0工作区结构由 pnpm-workspace.yaml 定义构建编排根 turbo.json 定义build任务依赖^build与prebuild、产物缓存为dist/**而 apps/docs-api/turbo.json 将其覆盖为outputs: [src/**]即文档站的缓存产物就是输出目录src/apisrc/**下的静态文件执行生成apps/docs-api的build脚本就是裸的typedoc命令由 TypeDoc 读取当前目录的typedoc.json完成整个站点生成。因此在本仓库中复现文档生成只需安装依赖后在 monorepo 根执行 turbo 过滤构建例如pnpm turbo run build --filterdocs-api或进入apps/docs-api目录执行pnpm build产物会落在apps/docs-api/src/api/中。由于 TypeDoc 以包为入口解析类型建议先完成各packages/*的构建根脚本pnpm build:packages会构建除 docs 与模板外全部包以让入口解析稳定。5. 文档化对象fuels 聚合包与各子包index.md声明 fuels-ts 是“与 Fuel v2 交互的库”而 API 文档站实际上就是把packages/下的能力分层暴露给开发者。从各包 package.json 的元信息看当前各包统一处于0.103.0版本命名遵循fuel-ts/*前缀聚合包为fuels职责划分清晰abi-coder / abi-typegenABI 编解码以及“Generates Typescript definitions from Sway ABI Json files”的 TypeScript 定义生成器对应文档站入口中的abi-typegenaccount账户、钱包、Provider、连接器等入口数最多的包之一含wallet、providers、connectors、hdwallet、predicate等子模块目录address“Utilities for encoding and decoding addresses”crypto“Utilities for encrypting and decrypting data”提供浏览器/Node 双端实现errors“Error class and error codes that the fuels-ts library throws”hasher“Sha256 hash utility for Fuel”math、merkle数值计算与默克尔树merkle未纳入文档站入口program、contract、script、transactions、utils、recipes程序调用、合约/脚本执行、交易构造、通用工具与示例配方。所有面向使用者的 API 最终由聚合包统一出口。packages/fuels/src/index.ts 通过export * from fuel-ts/…把abi-coder、account、address、contract、crypto、errors、hasher、math、program、recipes、transactions、utils等子包含configs子路径再导出并额外导出fuels/vm-asm的FuelAsm命名空间与 CLI 编程接口。这与typedoc.json入口列表高度吻合——API 文档站的模块划分基本就是 SDK 公开 API 的划分。6. 阅读该配置时的注意点结合仓库现状使用或评审docs-api配置时建议核对以下几点入口列表含失效路径typedoc.json 中的../../packages/interfaces与../../packages/predicate在packages/目录下不存在。TypeDoc 的logLevel: Error会压制告警这类问题在生成日志中不易暴露需人工核对入口与真实目录的一致性首页导航不完整index.md 的 Modules 列表只有 12 项缺少contract、recipes等实际入口包读者从首页出发不一定能浏览到全部模块页链接基准不同首页模块链接相对生成站点src/api解析而非仓库根目录输出目录即缓存产物out: src/api与 turbo.json 的outputs: [src/**]配合使增量构建可基于输出目录做缓存版本随包更新typedoc.base.json的includeVersion会把包版本当前各包均为0.103.0写入文档阅读生成产物时可据此判断对应 SDK 版本。7. 小结apps/docs-api用一个极小的应用一个 Markdown 首页 一份 TypeDoc 配置 一条typedoc构建脚本支撑起 fuels-ts 的 API 参考站以entryPointStrategy: packages将packages/下 16 个入口包含contract、recipes等聚合为统一站点首页由 index.md 提供定位语“fuels-ts is a library for interacting with Fuel v2”与模块导航产物输出到src/api并纳入 Turborepo 缓存。理解这一流程后开发者既能顺着typedoc.json的入口列表快速定位各模块源码目录如packages/abi-coder、packages/account也能在维护文档站时准确判断入口配置、首页导航与实际包结构之间的偏差。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考