因缘
不久前打算将我的博客内容格式从mdx?转到?orgmode?，此前我一直在使用contentlayer[1]管理我的mdx文档，但是因为一些原因这个项目停止维护了，并且虽然它具有一定的定制化能力，但和Markdown的绑定太深，无法满足我迁移到orgmode的需求，于是我花了点时间做了我个人的第一个JavaScript/TypeScript库：docube[2]。
设计
通常我更喜欢使用可定制性高的软件，但是像Vim、Emacs这类软件常常被抱怨新手上手难度太高，似乎高度可定制和开箱即用是非常冲突的理念，所以我希望做一个硬核用户可以自定义行为，普通用户又可以快速上手使用的应用。在具体实践上，我借助了effect[3]这个库，抽象出了一个通用的转换流程：
我的原始的需求就是将本地的org文件读取解析成HTML文本格式，并和其它元数据一起组成JSON文件+TypeScript定义文件的形式，之后在React里直接引用。核心的流程就是通过?Loader?获取抽象的?FileLkie[]?，再调用?FileConverter?转换内容，最后通过?Writer?写入，因为我想尽量保持核心的通用性，所以?ModuleResolver?（主要是用来生成JS模块和类型定义）在这里是可选的，用户可以通过注入对应的依赖来改变默认的行为。
常规的使用方式并不需要了解这些概念，下面是这段是我的博客从contentlayer迁移后的代码：
import { transform } from '@docube/mdx'
import rehypeProbeImageSize from './lib/rehypeImage'
import remarkGfm from 'remark-gfm'
transform({
name: 'Post',
directory: './posts',
include: '**/*.mdx',
fields: (s) => ({
title: s.String,
tags: s.Array(s.String),
series: s.String,
createdAt: s.String,
publishedAt: s.String,
summary: s.String,
}),
remarkPlugins: [remarkGfm],
rehypePlugins: [rehypeProbeImageSize],
})执行这段代码就可以得到一个生成的?.docube/generated/posts?模块，顶层导出了?allPosts?变量，在NextJS里，可以这样使用[4]：
import { allPosts } from '@docube/generated'
import { getMDXComponent } from 'mdx-bundler/client'
// ...
const MDXContent = getMDXComponent(post.body)
// ...
// ...
export async function generateMetadata({ params }: Props): Promise {
const { slug } = params
// post即是自动生成的Post类型
const post = allPosts.find((post) => post._meta.slug === slug)
if (!post) notFound()
return {
title: `${post.title} - Elliot`,
keywords: post.tags as string[],
description: post.summary,
}
} 而如果需要个性化使用，如提供一种新的文本格式的支持，只需要引用?@docube/common?的?makeTransformer?，修改传入的FileConverter依赖就可实现，具体见@docube/markdown[5]的实现。
问题
虽说我已经写过不少TypeScript代码，但在npm上发布库还是第一次，过程中还是遇到了不少问题的，在此记录一下，避免后来人踩坑。
Monorepo
考虑到我至少需要默认支持mdx和org两种格式，所以一开始我就想要创建多个库，因此采用了monorepo的形式。Monorepo说白了就是在一个代码仓库里包含有关联的多个项目，可以共享同样的外围工具如lint、format等，项目之间需要重构更新依赖相对来说要比多仓库轻松些。
对于JS项目，在根目录的package.json添加如?"workspaces": ["packages/*"]?，就可以在packages目录里包含多个子包。但是在开发时，如果B包依赖A包，?tsserver?实际上检查的是A包build后的dist，而不是A包的TS代码，也就是说如果A包更新了，需要先build一下，才能使LSP正确地工作。如果不想手动执行命令，可以用一些工具的?Watch Mode?功能，检测到包变化自动rebuild，当然前提是开发机器内存够用:)。
同步依赖
多个子项目依赖同一个依赖的情况是非常常见的，一般来说最好能全局共享这种相同的依赖，将其保持在一个相同版本。这方面NPM那边没有定义这个功能，不像?Cargo?可以让子项目继承Workspace的依赖。要实现这个目的的话，要么用syncpack[6]这类专门处理这个问题的工具，要么用?pnpm?这类的包管理工具的Workspace支持[7]。
发版
将包发布到npm上只需要build后执行?npm publish?就可以了，但是如果更新的包被另外几个包依赖了，那么后者也需要更新。这个问题有个辅助工具changesets[8]，它能自动帮助更新相关有改动的包的版本，并维护?Changelog?。
scope
NPM有一个比较好的设计是你可以给包名加一个范围前缀，比如有个通用的名字叫time，不同的组织可以用?@google/time?、?@microsoft/time?，一方面是避免想用的名字被抢，一方面是对于大企业来说可以标识一下这是自己的官方包。这里对新手的一个坑点是，当你创建了一个scope，然后想发布一个包，如?@docube/mdx?，默认情况下这个包会被当做是你组织下的私有包，而私有包是要收费的，需要用?npm publish --access=public?明确表明这是个公开的包，或者在package.json里写明：
{
"publishConfig": {
"access": "public"
},
...
}lint
turbo?默认生成的Monorepo模板内部使用了eslint v8?，而当前最新的eslint版本是?v9?，这两个版本之间有不兼容的改动，所以如果在这个模板上新建项目，并且不指定安装的eslint版本的话，将无法使用?turbo lint?命令，解决办法一个是安装eslint时指定使用v8版本，另一个详见我的配置[9]。
可选依赖
我本人对软件使用有一点小洁癖，不会用到的依赖就尽量不想要装到我的电脑上。如在Markdown支持上，很多人会在Markdown文件的开头放上一段?yaml?格式的文本来提供一些如撰写时间、作者等元信息：
---
date: 2024-02-02T04:14:54-08:00
draft: false
params:
author: John Smith
title: Example
weight: 10
---
...这个被称为?front matter?，但是处理这段文本的库每个人可能有不同的偏好选择（NPM上下载量较大的两个都有三年以上没有更新了）；并且有些情况下，这个front matter不一定是yaml格式，如静态站生成器hugo就提供了yaml、toml和json三种选择。
如果我在我的库里直接依赖一个实现，那么既便我为用户提供了自定义解析这段文本的配置，用户也必须下载一个他用不到的第三方库，甚至就算是不需要front matter的用户也不得不安装。为此我使用了可选依赖，可选依赖定义在package.json的?optionalDependencies?，我在开发中使用的是bun，使用?bun add gray-matter --optional?就可以将这个?gray-matter?包安装为可选模式。
在我的库代码里，可以用?tye-catch=加?=import?来判断用户有没有安装我默认的依赖，大致逻辑如下：
if (options.frontMatterExtractor) {
frontMatterData = options.frontMatterData(content)
} else {
try {
const matter = import("gray-matter")
// ...
} catch (e) {
// ...
}
}不想要front matter的用户，或者想用自己的逻辑处理的用户，可以用?npm install --omit=optinal?来避免安装我默认的可选包（具体命令根据使用的包管理器不同）。
终
这篇博客就是我用org格式写的(’?’)
引用链接
[1] contentlayer: https://contentlayer.dev/
[2] docube: https://codeberg.org/Elliot00/docube
[3] effect: https://effect.website/
[4] 这样使用: https://github.com/Eliot00/elliot00.com/blob/master/app/posts/%5Bslug%5D/page.tsx
[5] @docube/markdown: https://codeberg.org/Elliot00/docube/src/branch/main/packages/markdown/src/index.ts
[6] syncpack: https://www.npmjs.com/package/syncpack
[7] Workspace支持: https://pnpm.io/cli/update#--recursive--r
[8] changesets: https://github.com/changesets/changesets
[9] 我的配置: https://codeberg.org/Elliot00/docube/src/branch/main/packages/eslint-config
