@fuman/build

中文文档
0.0.23发布于 2026/10/21MITTypeScriptES Module构建来源已验证近 30 天下载 1988

utils for building packages and managing monorepos

原始使用文档
文档目录7 节
  1. @fuman/build
  2. why exactly?
  3. package.json pre-processing features
  4. usage with vite
  5. usage with jsr
  6. cli
  7. ci/cd

@fuman/build

this package contains utilities for building packages and managing monorepos.

existing similar tools try to do too much and accomodate for every possible use case, which makes them quite hard to use and don't provide enough consistency. unlike them, this package is very opinionated and might not be for you.

this package works on some assumptions, allowing to abstract some of the complexity away:

  • for workspaces, it assumes that the workspace is managed with pnpm
    • packages within the workspace are linked using workspace: protocol, and versions are replaced with the actual version at build time
  • packages are built using vite (i.e. rollup). i might support some other bundler down the line, though
    • tsc is explicitly not supported, because using tsc to build is such a pain that it's just not worth it.
  • all packages must be type: module, because commonjs sucks (you can still build into commonjs, tho)
  • .exports and .bin fields in package.json are build entrypoints, e.g.:
    {
      "exports": {
        ".": "./src/index.ts"
      },
      "bin": {
        "fuman-build": "./src/cli.ts"
      }
    }
    
  • .main, .module, .types, .browser are explicitly not supported. for browser-specific code, you should make a secondary entrypoint/package instead of relying on bundle-time magic
  • package versioning is continous and semver-compliant (except "fixed version" releases, which all share the same version)
  • this package currently focuses on non-frontend libraries

it might work with other setups, but that is not supported.

why exactly?

because node sucks. package.json is an absolute mess – it's not standardized properly, and it's a pain to work with. when it was invented, typescript wasn't even a thing, and as such it's a pain to set it up correctly for libraries. and npm is also a pain due to similar reasons. everything is so fragile and inconsistent that it's very easy to make mistakes.

deno and jsr fix some of the issues, but i just generally don't like deno because it feels very limiting and vendor-locking, and there isn't any tool to write cross-runtime code under deno anyway.

additionally there's quite some pain writing release ci/cd flows for libraries. especially for monorepos, especially when you want to cross-publish to npm and jsr.

package.json pre-processing features

...provided by processPackageJson function

  • copying common fields from root package.json
  • replacing workspace: dependencies with the actual version from the workspace
  • removing scripts (except ones listed in keepScripts)
  • removing devDependencies, typedoc/prettier/etc
  • collecting entrypoints from exports and bin
  • running hooks declared in build.config.js files

this allows to:

  • simplify the inner package.jsons and keep them in sync with the root package.json
  • simplify the release flow by not having to manually update dependency versions in each package
    • (i know that pnpm/yarn basically fix this with workspace: protocol, but i don't like the idea of using something other than npm cli to publish to npm)
  • ensures you don't accidentally publish unwanted prepare/install/etc. scripts to npm (and also reduces install size by a bit)
  • reduces install size a bit
  • improve dx by a lot
    • you no longer need to build the packages before you can import them, nor do you need to repeat yourself by manually providing .types field for development
    • you no longer need to sync vite build entrypoints with package.json across all packages (and accidentally publish them broken)
  • since we generate a new package.json, you can do pretty much any modifications to the production package.json (despite the above, there might still be cases that we don't cover and you want a bit more control. feel free to open an issue if you feel like this should be in the package tho!)

usage with vite

just put this in your vite.config.js:

import { fumanBuild } from '@fuman/build/vite'

export default {
  plugins: [
    fumanBuild({
      root: __dirname,
      // if you're using `vite-plugin-dts`, make sure to add this option,
      // otherwise additional entrypoints will not have proper types
      // (and DO NOT add this option to the dts plugin itself)
      insertTypesEntry: true,
    }),
  ],
}

usage with jsr

fuman-build also supports jsr by being able to convert a pnpm workspace into a deno workspace, which can then be published via simple deno publish command.

to generate a deno workspace, run fuman-build jsr gen-deno-workspace.

cli

fuman-build has a pretty cool cli, check it out via fuman-build --help

ci/cd

fuman-build also makes it very easy to use in CI/CD pipelines. a very simple release flow powered by fuman build and github actions can be found here.

the release command basically combines a bunch of other commands (namely, bump-version, gen-changelog, publish and jsr subcommands) into one and adds some additional release-specific features (like git tagging and github release generation), and is the recommended way to use fuman-build in CI/CD pipelines.

though it is definitely possible to use the other commands directly, in case you need to do something that is not supported out of the box.

版本与发布记录

@fuman/build 共发布 21 个版本,首次发布于 2024/12/02;过去 12 个月发布了 5 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.0.23latest2026/10/2125 天前
0.0.212026/07/164 个月前
0.0.202026/07/034 个月前
0.0.192026/01/259 个月前
0.0.182025/11/2311 个月前
0.0.172025/11/161 年前

关于 @fuman/build 的常见问题

@fuman/build 是什么?

utils for building packages and managing monorepos

如何安装 @fuman/build?

在项目目录运行 npm install @fuman/build,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:vite(^5.4.0 || ^6.0.0 || ^7.0.0)、typescript(^5.2.2)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 fuman-build,可以用 npx fuman-build 直接运行。

@fuman/build 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@fuman/build 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@fuman/build 可以商用吗?

@fuman/build 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@fuman/build 的下载量有多少?

根据 npm 官方下载统计,@fuman/build 在 2026/10/16 – 2026/11/14 这 30 天内被下载 1,988 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@fuman/build 还在维护吗?

最新版本 0.0.23 发布于 2026/10/21(25 天前);至今共发布 21 个版本,其中过去 12 个月发布了 5 个;首次发布于 2024/12/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。