Lakutata 工作区

由多个包组成的项目（应用、它的 Web 界面、共享库、原生插件）就是一个工作区：一个仓库，根目录的 package.json 列出各个包所在的目录。包管理器（npm、pnpm 或 yarn）负责把这些包互相链接起来；lakutata 命令按依赖顺序运行它们的脚本，给它们统一版本号，并添加新的包。lerna 中这类项目用得到的那部分功能，它都提供了。除 default 以外的模板创建的都是工作区（见 ProjectStructure 第 2 节）。

1. 工作区

用 lakutata create --name shop --template web-react 创建的项目，根目录的 package.json 如下（省略了迁移和 Docker 相关的脚本）：

json

{
  "name": "shop-workspace",
  "version": "0.0.1",
  "private": true,
  "workspaces": ["packages/*"],
  "scripts": {
    "build": "lakutata run rebuild",
    "test": "npm run build && lakutata run test",
    "dev": "lakutata run dev --parallel",
    "start": "npm start -w app",
    "version:patch": "lakutata version patch --yes"
  },
  "devDependencies": {
    "@lakutata/cli": "^3.0.0",
    "@types/node": "^22.0.0",
    "typescript": "^6.0.3"
  }
}

包：workspaces 中的模式所匹配、并且含有带 name 的 package.json 的目录。* 匹配一层目录名中的任意字符，** 匹配任意层目录，!packages/old 排除一个目录。node_modules 和以点开头的目录不会被搜索。pnpm 工作区把模式写在 pnpm-workspace.yaml 中，作为 packages: 下的列表（每行一个 - 'packages/*'，或者写成 ['packages/*']）。
在工作区的任何目录中都能运行这些命令：它们使用向上最近的一个声明了工作区的目录。
包之间的依赖：dependencies、devDependencies、peerDependencies 或 optionalDependencies 中的依赖，不论范围怎么写（^0.0.1、*、workspace:*、file:）。
构建工具（@lakutata/cli、typescript、@types/node）是根目录的开发依赖，所以每个包的脚本都能使用它们。

lakutata list 显示各个包、它们的版本和目录，以及每个包依赖的包。这里 app（服务器）依赖 ui（Web 界面），并提供 ui 构建好的页面：

2 packages, version 0.0.1
  app  0.0.1 (private)  packages/app  → ui
  ui   0.0.1 (private)  packages/ui

2. 运行脚本

lakutata run <script> 在每个有该 npm 脚本的包中运行它。一个包要等它（直接或间接）依赖的包都执行完才开始，互不依赖的包同时执行。每行输出都以所属包的名称开头：

lib   │ start lib
tools │ start tools
tools │ end tools
lib   │ end lib
app   │ start app
app   │ end app
✔ build ran in tools, lib, app

选项	含义
`--parallel`	所有包同时开始，不等待它们的依赖：用于一直运行的脚本，例如开发服务器和监视进程（`lakutata run dev --parallel`）
`--scope <names...>`	只运行这些包，`` 匹配任意字符（`--scope 'app' '@shop/'`）。它们依赖的包既不运行，也不等待；没有任何包匹配时报错
`--concurrency <n>`	同时运行的包数（默认为处理器数量）
`--no-bail`	失败后继续：依赖失败包的那些包被跳过，其他包照常运行

失败：默认情况下，有包失败后不再启动新的包，已经在运行的包会运行完。命令最后输出 error: build failed in lib, not run in app，退出码为 1。
没有任何包有这个脚本：命令输出 No package has the script lint，并正常结束。
包管理器：脚本用 npm run、pnpm run 或 yarn run 运行，根据根目录 package.json 的 packageManager 字段（"pnpm@9.15.0"）选择，没有这个字段时看根目录中的文件（pnpm-lock.yaml 或 pnpm-workspace.yaml、yarn.lock、package-lock.json），默认是 npm。
参数：脚本不接受额外的参数（lakutata run build -- --watch 会被拒绝），请另加一个脚本。

3. 设置版本号

工作区的所有包共用一个版本号。lakutata version <bump> 把新版本设置给所有包，并更新它们之间的依赖。从 1.2.3 开始：

bash

lakutata version patch                     # 1.2.4，在终端里会先请求确认
lakutata version minor --git --yes         # 1.3.0，提交修改并打上标签 v1.3.0
lakutata version preminor --preid beta     # 1.3.0-beta.0，之后 prerelease 得到 1.3.0-beta.1
lakutata version 2.0.0

在版本为 0.0.16 的工作区中，输出如下：

Version 0.0.16 → 0.0.17
  app    0.0.16 → 0.0.17
  lib    0.0.16 → 0.0.17
  tools  0.0.16 → 0.0.17
✔ Version 0.0.17 given (packages/app/package.json, packages/lib/package.json, packages/tools/package.json, package.json)

当前版本：lerna.json 中有 version 时取它，否则取根目录 package.json 的版本，再否则取各包中最高的版本，预发布版本也算在内（都没有时为 0.0.0）。新版本写回原处，也写入每个包，私有包也一样。
版本的递增方式：major、minor、patch、premajor、preminor、prepatch、prerelease，或者直接给出版本号。--preid <id> 给 pre… 这几种递增方式指定预发布标识（beta 得到 1.3.0-beta.0；不指定时是 1.3.0-0）。
包之间的依赖随之更新：^0.0.16 变成 ^0.0.17，~、>=、= 和 workspace:^ 范围也一样。*、workspace:* 和 file: 依赖保持不变。在 0.x 版本中这一点很重要，因为 ^0.0.16 不接受 0.0.17。
锁文件也随之更新：更新 package-lock.json 或 pnpm-lock.yaml，使 npm ci（或 pnpm install --frozen-lockfile）仍然接受它。yarn.lock 不会更新：命令会提醒你运行 yarn install。
--git 只提交这些改动的文件，提交信息为 v1.3.0，并给这个提交打上标签 v1.3.0。不推送任何内容。命令在修改任何文件之前，先检查仓库和标签。
确认：只在终端里询问。在 CI 中，或者输出被管道接走时，直接设置版本。--yes 在终端里也跳过确认。

4. 添加包

lakutata add <name> 在工作区中创建一个 TypeScript 包，--to <package> 把它加入另一个包的依赖。在第 1 节的 web-react 项目中，添加一个由服务器和 Web 界面共用代码的包：

bash

lakutata add @shop/shared --to app

✔ Package @shop/shared 0.0.1 added: packages/shared (package.json, tsconfig.json, src/index.ts, src/tests/index.spec.ts, README.md), a dependency of app
Next: npm install (links the package), then npm run rebuild -w @shop/shared

--to 只能指定一个包，ui 的依赖请在 packages/ui/package.json 中手动添加：

json

{
  "dependencies": {
    "@shop/shared": "^0.0.1"
  }
}

然后 npm install 链接新的包，lakutata list 中就能看到它：

3 packages, version 0.0.1
  app           0.0.1 (private)  packages/app  → ui, @shop/shared
  @shop/shared  0.0.1 (private)  packages/shared
  ui            0.0.1 (private)  packages/ui  → @shop/shared

现在 npm run build（lakutata run rebuild）先构建 @shop/shared，再构建 ui，最后构建 app。两者都像导入其他包一样导入它：import {greet} from '@shop/shared'。

位置：在工作区存放包的目录中，目录名是去掉作用域的包名。存放包的目录取第一个形如 apps/* 的模式的目录（有 packages/* 时取它）。如果工作区的模式中没有这样的目录（只逐个列出了包，或者是 packages/**），命令会拒绝添加。
版本：就是工作区的版本（工作区没有版本，或者使用 lerna 的独立版本时为 0.0.1），--to 加入的依赖是 "@shop/shared": "^0.0.1"。
文件：src/index.ts（一个示例函数，请换成你的代码）、一个由 node --test 运行的测试，以及一个 package.json，其中的脚本是 clean、build（tsc）、rebuild 和 test。它把 src 连同类型声明编译到 build 中，并通过 exports 提供给其他包。Web 界面也要用到的代码，不能使用 Node.js 的模块。
私有：这个包是 "private": true。要发布它，请删掉这一行（npm publish -w @shop/shared）。
不安装任何东西：之后请按命令的提示，运行工作区所用包管理器的安装命令（pnpm install、yarn install），其他包才能看到新的包。

lakutata add <name> --native gyp|cmake|rust 则创建原生插件，见 NativeAddons。

5. 从 lerna 迁移

lerna	lakutata
`lerna run rebuild`	`lakutata run rebuild`
`lerna run dev --parallel`	`lakutata run dev --parallel`
`lerna version patch --no-git-tag-version --no-push -y`	`lakutata version patch --yes`
`lerna version patch`	`lakutata version patch --git`（不推送标签）

工作区可以保留 lerna.json：lakutata 只读写其中的 version。包来自根目录 package.json 的 workspaces（或 pnpm-workspace.yaml），而不是 lerna.json 的 packages。
lakutata 给所有包用同一个版本号："version": "independent" 的 lerna.json 无法递增版本。
它不生成变更日志，不缓存构建结果，不挑选自上次发布以来有改动的包，也不发布：发布请用 npm publish -w <package>。需要这些功能的工作区可以同时保留 lerna（或 nx、turborepo）。

Lakutata 工作区 ​

1. 工作区 ​

2. 运行脚本 ​

3. 设置版本号 ​

4. 添加包 ​

5. 从 lerna 迁移 ​