@icebreakers/monorepo 1.2.0 → 1.2.1

package/templates/apps/website/why/modern/typescript.md

@@ -0,0 +1,155 @@
+# 使用 TypeScript 编写代码
+
+既然我们需要写多份文件，然后再发布到 `npm` 包，不如只写一份 `typescript` 文件
+
+然后其他的格式 (`cjs`/`esm`)，还有 `d.ts` 产物都自动生成，这不是就非常方便吗?
+
+## 改造项目
+
+安装 `typescript` 以及完成初始化创建 `tsconfig.json`
+
+```bash
+npm i -D typescript # 安装 typescript
+npx tsc --init # 创建 tsconfig.json
+```
+
+添加 `src` 目录，在里面创建 `index.ts` 文件
+
+```ts
+export function sayHello() {
+  const message = 'hello world typescript'
+  console.log(message)
+  return message
+}
+
+console.log(`load package icebreaker-npm-basic-package`)
+```
+
+## 调整 `tsconfig.json`
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "rootDir": "./src",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true, // 支持 import json
+    "strict": true, // 严格模式
+    "declaration": true, // 生成 dts
+    "declarationMap": true, // dts 的 sourcemap
+    "outDir": "./dist", // 生成 dts 的目录
+    "sourceMap": true, // 生成 sourcemap
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+```
+
+更多的配置 https://www.typescriptlang.org/tsconfig/
+
+## 创建 `cjs` 和 `esm` 各自格式的 `tsconfig.json`
+
+:::code-group
+
+```jsonc [tsconfig.esm.json]
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "outDir": "./dist/esm"
+  }
+}
+```
+
+```jsonc [tsconfig.cjs.json]
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "moduleResolution": "node10",
+    "outDir": "./dist/cjs"
+  }
+}
+```
+
+:::
+
+## 开始编译
+
+在 `package.json` 的 `scripts` 中添加脚本
+
+```jsonc
+{
+  "build:cjs": "tsc --project tsconfig.cjs.json && node rename-ext.js dist/cjs .js .cjs && node rename-ext.js dist/cjs .js.map .cjs.map",
+  "build:esm": "tsc --project tsconfig.esm.json",
+  "build": "npm run build:cjs && npm run build:esm"
+}
+```
+
+为什么这里还需要执行 `rename-ext`? 因为你安装使用一个 `npm` 包的时候，默认情况下会使用 `package.json` 中的 `type` 字段去决定这个包 `js` 代码模块加载器
+
+通常 `nodejs` 中会存在 `2` 个模块加载器:
+
+- [Modules: CommonJS modules](https://nodejs.org/docs/latest/api/modules.html)
+- [Modules: ECMAScript modules](https://nodejs.org/docs/latest/api/esm.html)
+
+假如你声明了 `"type": "module"`，那么 `nodejs` 会使用 `ESM` 模块加载器，去加载这个包下面的所有 `.js`
+
+反之，则使用 `CJS` 模块加载器，去加载这个包下面的所有 `.js`
+
+但是有 `2` 个后缀是特例，`.cjs` 和 `.mjs` , 他们在 `js` 前面加了 `c` 和 `m` 代表指定 `cjs`/`esm` 模块加载器，去加载这个 `js` 代码
+
+而我们这个包，已经被声明了 `"type": "module"`，所以是无法直接运行后缀是 `.js` 的 `cjs` 文件的，必须把后缀从 `.js` 转变为 `.cjs`
+
+## 更改 `package.json` 中模块入口点
+
+```jsonc
+{
+  "name": "icebreaker-npm-basic-package",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist" // [!code highlight]
+  ]
+}
+```
+
+给不同的引入方式，设置不同的模块入口，和不同的类型提示。
+
+同时也要注意这里我们添加了 `files` 字段，因为此时 `src` 目录下的源代码是不需要发布到 `npmjs` 上去的
+
+你也可以通过执行 `npm pack --dry-run` 查看当前哪些文件会在发布的时候，被上传到 `npmjs` 上去
+
+## 调试项目
+
+### 利用 `sourcemap` 调试项目
+
+`source map`（源码映射） 是一种用来 把编译/打包/压缩后的代码映射回原始代码 的技术
+
+它是用来解决 生成的代码和原始代码不一样, 无法直接调试源代码，这样一个问题。
+
+使用方式，在打开 `sourcemap` 选项后，生成对应的 `sourcemap` 文件，然后就可以在 `ts` 代码中打上断点，直接调试源代码了。
+
+### 直接运行 `typescript` 调试项目
+
+过去我们使用 `ts-node` 来直接运行 `ts`，随着时代的发展，`ts-node` 已经逐渐被 `tsx` 所取代
+
+当然市面上直接转译运行 `typescript` 的工具还是非常多的，比如 `tsx` 和 `bundle-require` 都是基于 `esbuild`
+
+`jiti` 这种基于 `babel` 的，还有 `swc-node` 这种基于 `swc` 的， `@oxc-node/core` 这种基于 `oxc` 的
+
+当然，在不使用 `emitDecoratorMetadata` 这种 `typescript` 的装饰器的高级用法的情况下，使用 `tsx` 是比较好的选择

package/templates/apps/website/why/publish-basic-npm-package.md

@@ -0,0 +1,146 @@
+# 如何发布 npm 包
+
+其实发布基础的 `npm` 包非常非常简单
+
+## 创建目录
+
+随便创建一个目录，在创建目录之后执行 `npm init` 输入一些你的包的元数据之后，一个 `package.json` 就被创建了出来
+
+假如你懒得写，那就执行 `npm init -y` ，反正后续都是可以更改的，此时你得到的 `package.json` 如下
+
+```jsonc
+{
+  "name": "icebreaker-npm-basic-package",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": ""
+}
+```
+
+> 你操作到这里，`package.json` 的 `name` 一定要换成你自己的，因为这个包我已经发布了，所以名字已经被我占据了你用不了
+
+## 创建一个 `index.js`
+
+在你的 `package.json` 同目录下创建一个 `index.js`，内容如下
+
+```js
+console.log(`load ${__filename}`)
+
+function sayHello() {
+  console.log('hello world')
+}
+
+module.exports = {
+  sayHello
+}
+```
+
+> 按照现代包的要求，其实是优先 esm 格式的，但是上面的例子还是用的 cjs，这个会在下个章节提到
+
+## 发包到 npmjs
+
+然后你在 `package.json` 同级目录下，执行 `npm publish`
+
+然后恭喜你，你失败了！
+
+为什么失败？你连 `npmjs` 账号都还没有注册呢！
+
+执行 `npm publish` 是需要先 `npm login` 登录你的 `npmjs` 账号的
+
+赶紧去 [`www.npmjs.com`](https://www.npmjs.com/) 右上角注册一个账号吧！
+
+## 获取 Access Token
+
+注册好一个账号之后，再执行 `npm login`, 你就可以在弹出来的页面中，登录你的账号
+
+登录成功之后，默认情况下，他会给你去生成一个 `Access Token` 作为你的发包凭证
+
+此时会写入到你全局 `.npmrc` 的文件中，类似于下面一行
+
+```txt
+registry.npmjs.org/:_authToken=npm_hashhashhashhashhashhashhashhashhash
+```
+
+假如这一行存在，说明你本地的 `npm Access Token` 就设置好了，然后你才有发包的权限。
+
+> 你也可以在 `https://www.npmjs.com/settings/<你的用户名>/tokens` 中管理你的 `token`，给不同的 `token` 设置不同的作用域，有效期和 `ip` 限制，帮助你适配正常开发，`CI/CD`，`Token` 分发的各种场景
+
+同样发私有源包也是同理:
+
+```txt
+//npm.icebreaker.top/:_authToken=npm_hashhashhashhashhashhashhashhashhash
+```
+
+你必须有这个凭证，你才有这个权限。
+
+## 成功发包
+
+配置好 `npm Access Token` 执行 `npm publish` 然后就能发包成功了
+
+```sh
+npm notice
+npm notice 📦  icebreaker-npm-basic-package@1.0.0
+npm notice Tarball Contents
+npm notice 120B index.js
+npm notice 187B package.json
+npm notice Tarball Details
+npm notice name: icebreaker-npm-basic-package
+npm notice version: 1.0.0
+npm notice filename: icebreaker-npm-basic-package-1.0.0.tgz
+npm notice package size: 326 B
+npm notice unpacked size: 307 B
+npm notice shasum: fc4624e7bddd96a6ffac505f672b62de55898d6b
+npm notice integrity: sha512-2UtWkYX5tEUyu[...]ZFF64Wvq+Vw0Q==
+npm notice total files: 2
+npm notice
+npm notice Publishing to https://registry.npmjs.org/ with tag latest and default access
++ icebreaker-npm-basic-package@1.0.0
+```
+
+然后你就发现你的包可以通过访问 `https://www.npmjs.com/package/<你的包名>` 获取到了
+
+比如我这个包就能通过 `https://www.npmjs.com/package/icebreaker-npm-basic-package` 直接访问
+
+## 安装调用
+
+你可以执行 `npm i <你的包名>` 直接获取到你的包，进行调用了。
+
+> 假如你没有使用官方的 `registry.npmjs.org`，反而使用的是 `npmmirror.com` 这种国内的淘宝镜像源，那么你的包同步到国内镜像源，可能需要一段时间
+>
+> 你可以通过 `npm i -g cnpm`, `cnpm sync <你的包名>` 进行手动同步，加快这个流程。
+
+安装好之后，使用 `nodejs` 执行代码:
+
+```js
+const { sayHello } = require('icebreaker-npm-basic-package')
+
+sayHello()
+```
+
+出现
+
+```txt
+load /your/path/to/node_modules/icebreaker-npm-basic-package/index.js
+hello world
+```
+
+证明你安装调用成功了！实际上很简单吧！
+
+## 更进一步
+
+恭喜你，你已经踏出了你的第一步，你已经来到了 `Nodejs` 这座高山的山脚下准备进行攀登。
+
+山上云雾缭绕，看不到顶，攀登的路上, 险象环生，爬的越高越感觉举步维艰。
+
+但是也用不着害怕，正如荀子在《劝学》篇所写下的: `不积跬步,无以至千里。不积小流,无以成江海`。
+
+量变促成质变，等你到达那个质变的点，你就会发现自己看待代码的眼光已经完全改变了，从新的角度去看，很容易一眼看出问题的本质。
+
+所以，多看优秀的代码，多去调试开源项目的源代码，多写代码多思考，你就成长了！
+
+接下来让我们改进一下这个包，让他更加的现代化。

package/templates/apps/website/why/what-is-npm-package.md

@@ -0,0 +1,162 @@
+---
+outline: [2, 4]
+---
+
+# 什么是 npm 包
+
+在 `Node.js` 中，**npm 包（npm package）** 是指一个通过 [npm（Node Package Manager）](https://www.npmjs.com/) 发布和管理的可重用 `JavaScript` 模块。它可以是一个库、工具、框架、命令行工具，甚至是一个完整的应用程序。
+
+### 什么是 npm？
+
+**npm（Node Package Manager）** 是 Node.js 的官方包管理工具，用于：
+
+- 安装依赖库；
+- 管理项目依赖；
+- 发布自己的模块到 npm 生态。
+
+命令行工具：`npm install`, `npm update`, `npm publish` 等。
+
+同样 `yarn` / `pnpm` 也是 **npm（Node Package Manager）**，不过他们是非 `Nodejs` 官方的
+
+他们的出现或多或少的解决了官方 `npm` 的很多问题，完全可以作为官方 `npm` 工具的平替，在社区里备受推崇，展现出 `Nodejs` 社区旺盛的生命力。
+
+尤其是 `pnpm`，比官方 `npm` 好用太多，目前大家把很多对 `npm` 包管理器的期望都寄托在他身上。
+
+> `pnpm` 对于 `Nodejs`，地位类似于 [`uv`](https://github.com/astral-sh/uv) 对于 `Python` 他们都不是官方项目，但是却逐渐成为了主流
+
+<!-- `deno` / `bun` -->
+
+---
+
+### 什么是一个 npm 包？
+
+一个 **npm 包** 通常具有以下结构：
+
+```
+my-package/
+├── package.json     // 包的元数据（名字、版本、依赖等）
+├── index.js         // 主文件（或其它入口）
+└── lib/             // 模块代码
+```
+
+`package.json` 是核心文件，定义了：
+
+- `name`：包的名称（唯一，不能与其它包冲突）
+- `version`：版本号（如 `1.0.0`）
+- `main`：主入口文件（默认是 `index.js`）
+- `dependencies`：依赖的其他 npm 包
+- `files`: 哪些文件应该被上传，用于忽略掉不需要的文件类型
+
+> 更多字段，可以查看 [`configuring-npm/package-json`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json)
+
+### npm 包关系类型
+
+#### **公共包**
+
+来自 [npmjs.com](https://www.npmjs.com/) ，如 `lodash`, `react`, `axios`
+
+[yarnpkg.com](https://yarnpkg.com/), [npmmirror(淘宝源)](https://npmmirror.com/) 这种本质上都是 [npmjs.com](https://www.npmjs.com/) 的镜像源，定期从 [npmjs.com](https://www.npmjs.com/) 同步包到他们的源上 (所以 `npmmirror` 有 `cnpm sync` 命令和 `同步功能` 就是为了在自动同步不及时的时候，手动同步的)
+
+假如我们要发 **公共包**，那肯定把包发到 [npmjs.com](https://www.npmjs.com/) 上的，因为发其他公共源没有意义。
+
+#### **私有包**
+
+企业内部发布的包，需配置私有 `npm registry`。
+
+注册源可以在用户本地 `User` 全局的 `.npmrc`, 或者是项目中的 `.npmrc` 进行配置
+
+比如:
+
+```txt
+registry=https://registry.npmmirror.com/
+@ice:registry=http://npm.icebreaker.top
+```
+
+就代表所有 `@ice/xxx` 这种包都从 `http://npm.icebreaker.top` 这里获取，其他包从 `https://registry.npmmirror.com/`
+
+假如你不设置 `registry` 默认从最官方的源 `https://registry.npmjs.org/` 中获取包
+
+假如你对 `npm私有源` 的搭建感兴趣，可以看看我写的这篇文章 [使用 Verdaccio 私有化 npm 源指南](https://juejin.cn/post/7357016488698839050)
+
+#### **本地包**
+
+可直接从 `文件夹`, `Git 仓库`, `monorepo workspace` 安装的包
+
+因为其实我们在 `dependencies` 和 `devDependencies` 注册的包，协议可以是多种多样的，比如:
+
+```jsonc
+{
+  "dependencies": {
+    // npm 注册源上拿
+    "foo": "1.0.0 - 2.9999.9999",
+    "bar": ">=1.0.2 <2.1.2",
+    "baz": ">1.0.2 <=2.3.4",
+    "boo": "2.0.1",
+    "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
+    "til": "~1.2",
+    "elf": "~1.2.3",
+    "two": "2.x",
+    "thr": "3.3.x",
+    "lat": "latest",
+    // http 协议拿
+    "asd": "http://npmjs.com/example.tar.gz",
+    // git 协议拿
+    "xxx": "git+ssh://git@github.com:npm/cli#semver:^5.0",
+    // 从 github 拿
+    "express": "expressjs/express",
+    "mocha": "mochajs/mocha#4727d357ea",
+    "module": "npm/example-github-repo#feature/branch",
+    // 本地文件协议拿
+    "dyl": "file:../dyl",
+    "kpg": "file:../foo/bar",
+    // monorepo workspace
+    "xya": "workspace:*"
+  }
+}
+```
+
+详见官方文档 [dependencies详解](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#dependencies)
+
+### 注意点
+
+值得注意的是，这个包的类型只和它的来源还有和当前包的关系有关，也就是说一个包，既可以是公共包，也可以是私有包，也可以是本地包。
+
+比如在本 `monorepo` 中，`@icebraekers/monorepo` 是公共包，因为它已经发布到了 `https://www.npmjs.com` 上了
+
+同时它也是一个本地包，因为本 `monorepo` 中，其他项目使用 `workspace` 的方式直接使用了这个包。
+
+它也可以是一个私有包，比如你在公司内部网络，快速使用 [verdaccio](https://www.npmjs.com/package/verdaccio) 搭建一个私有源, 然后把 `@icebraekers/monorepo` 发布上去，那它就变成一个内网里的私有包了。
+
+### 使用 npm 包的示例
+
+这里我以一个最简单的一个 `cowsay` 包为例，这个包作用就是输出一个牛说话的字符画
+
+- **安装第三方包：**
+
+```bash
+npm install cowsay
+```
+
+- **在代码中使用：**
+
+```js
+const cowsay = require('cowsay')
+
+console.log(cowsay.say({
+  text: '我爱中国!',
+  e: 'oO',
+  T: 'U '
+}))
+```
+
+- **在 CLI 中使用 ：**
+
+```bash
+npx cowsay 我爱中国!
+```
+
+> `npx` 是 Node.js 提供的一个命令行工具，用来直接运行 npm 包，无需全局安装。
+
+---
+
+接下来，就让我们开始 `npm` 包的发布之旅吧

package/templates/packages/tsup-template/build.config.ts

@@ -0,0 +1,24 @@
+import path from 'node:path'
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  // entries: ['./src/index', './src/cli'],
+  rollup: {
+    // 内联，相当于 nodeResolve
+    inlineDependencies: true,
+    // cjs
+    emitCJS: true,
+    // 添加 cjs 注入
+    cjsBridge: true,
+    dts: {
+      // https://github.com/unjs/unbuild/issues/135
+      respectExternal: false,
+    },
+  },
+  alias: {
+    // 别名
+    '@': path.resolve(__dirname, './src'),
+  },
+  // dts
+  declaration: true,
+})

package/templates/packages/tsup-template/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@icebreakers/tsup-template",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "tsup package template",
+  "author": "ice breaker <1324318532@qq.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonofmagic/monorepo-template.git",
+    "directory": "packages/tsup-template"
+  },
+  "bugs": {
+    "url": "https://github.com/sonofmagic/monorepo-template/issues"
+  },
+  "keywords": [],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "stub": "unbuild --stub",
+    "dev": "tsup --watch --sourcemap",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:dev": "vitest",
+    "release": "pnpm publish",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "publishConfig": {}
+}

package/templates/packages/tsup-template/src/index.ts

@@ -0,0 +1,12 @@
+export function bar() {
+  return 'foo'
+}
+
+export function getDirname() {
+  return __dirname
+}
+
+export enum xx {
+  id,
+  dd,
+}

package/templates/packages/tsup-template/test/index.test.ts

@@ -0,0 +1,7 @@
+import { bar } from '@/index'
+
+describe('index', () => {
+  it('foo bar', () => {
+    expect(bar()).toBe('foo')
+  })
+})

package/templates/packages/tsup-template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    }
+  },
+  "include": [
+    "src",
+    "test"
+  ]
+}

package/templates/packages/tsup-template/tsup.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'], // , 'src/cli.ts'],
+  shims: true,
+  format: ['cjs', 'esm'],
+  clean: true,
+  dts: true,
+  // https://github.com/egoist/tsup/pull/1056
+  // https://github.com/egoist/tsup/issues?q=cjsInterop
+  cjsInterop: true,
+  splitting: true,
+  outExtension({ format }) {
+    return {
+      js: `.${format === 'esm' ? 'mjs' : 'cjs'}`,
+    }
+  },
+})

package/templates/packages/tsup-template/vitest.config.ts

@@ -0,0 +1,15 @@
+import path from 'node:path'
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+  test: {
+    alias: [
+      {
+        find: '@',
+        replacement: path.resolve(__dirname, './src'),
+      },
+    ],
+    globals: true,
+    testTimeout: 60_000,
+  },
+})

package/templates/packages/unbuild-template/build.config.ts

@@ -0,0 +1,24 @@
+import path from 'node:path'
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  // entries: ['./src/index', './src/cli'],
+  rollup: {
+    // 内联，相当于 nodeResolve
+    inlineDependencies: true,
+    // cjs
+    emitCJS: true,
+    // 添加 cjs 注入
+    cjsBridge: true,
+    dts: {
+      // https://github.com/unjs/unbuild/issues/135
+      respectExternal: false,
+    },
+  },
+  alias: {
+    // 别名
+    '@': path.resolve(__dirname, './src'),
+  },
+  // dts
+  declaration: true,
+})

package/templates/packages/unbuild-template/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@icebreakers/unbuild-template",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "unbuild package template",
+  "author": "ice breaker <1324318532@qq.com>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonofmagic/monorepo-template.git",
+    "directory": "packages/unbuild-template"
+  },
+  "bugs": {
+    "url": "https://github.com/sonofmagic/monorepo-template/issues"
+  },
+  "keywords": [],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "unbuild --stub",
+    "build:watch": "unbuild --watch --sourcemap",
+    "build": "unbuild",
+    "test": "vitest run",
+    "test:dev": "vitest",
+    "release": "pnpm publish",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "publishConfig": {}
+}

package/templates/packages/unbuild-template/src/index.ts

@@ -0,0 +1,9 @@
+export function foo() {
+  return 'bar'
+}
+
+export function getDirname() {
+  return __dirname
+}
+
+export { format } from '@/utils'

package/templates/packages/unbuild-template/src/utils.ts

@@ -0,0 +1,3 @@
+export function format(str: string) {
+  return str.replaceAll(/[a-z]/g, s => s.toUpperCase())
+}