#优质博文 #前端 #Node #JavaScript #ESM #CJS #工程化
require(esm) in Node.js: implementer's tales

AI 摘要：本文是 Node.js 核心贡献者 Joyee Cheung 关于 require(esm) 功能实现细节的深度解析。文章聚焦于该功能在落地过程中，为兼容现有生态系统而必须解决的几个关键互操作性问题：包括如何处理“伪 ESM (faux-ESM)”包的 __esModule 标记、如何通过特殊导出 "module.exports" 支持非对象字面量的 CommonJS 导出、如何引入 "module-sync" 导出条件来支持双包 (dual package) 的平滑迁移，以及如何通过 process.getBuiltinModule() 避免不必要的顶层 await。文章揭示了看似简单的功能背后，为保持生态稳定性和性能所付出的复杂工程努力，并强调了社区协作在推动此类停滞计划中的关键作用。

[以下是方便搜索索引的大纲(AI 生成)，请读原文]

1. 伪 ESM (Faux-ESM) 的兼容性挑战
• 问题根源：许多为浏览器打包的库在 Node.js 端发布的是转译后的 CommonJS 代码（即“伪 ESM”），它们依赖 __esModule 标记来模拟 ESM 的命名空间行为。
• 兼容性断裂：如果这些包直接迁移到纯 ESM，其现有的转译后消费者通过 require() 加载时将因缺少 __esModule 标记而中断。
• 解决方案评估与选择：在无法直接修改不可变的模块命名空间对象的前提下，评估了多种方案（对象拷贝、Proxy、原型继承、ESM 门面模块），最终选择了通过创建一个内部 ESM 门面模块（使用 export * from 并额外导出 __esModule）的方案，以在保证正确性（保持实时绑定、身份和可枚举性）的同时，将性能开销降至最低（约 2-4%）。

2. CommonJS 特殊导出模式的兼容
• 导出形状不匹配：CommonJS 允许 module.exports 被重新赋值为任何值（如一个类），而 ESM 的默认导出位于命名空间的 default 属性下，这导致迁移后 CommonJS 消费者无法正确获取导出值。
• 特殊导出方案：引入了名为 "module.exports" 的字符串字面量特殊导出。ESM 模块可以通过 export { Klass as "module.exports" } 来显式指定 require(esm) 应返回的值，从而无缝兼容旧的 CommonJS 消费者，而无需改变 ESM 消费者的导入方式。

3. 双包 (Dual Package) 的迁移路径
• 条件导出的演进：为了在支持旧版 Node.js（仅 CommonJS）的同时，为新版 Node.js 提供 ESM，包作者曾使用 "node" 条件指向 CommonJS。
• 新条件的引入：由于生态中已有的 "module" 条件常指向无法在 Node.js 直接运行的打包后代码，Node.js 引入了新的 "module-sync" 条件，专门用于指向可在 Node.js 中同步加载的 ESM 源文件，作为向纯 ESM 包过渡的临时方案。

4. 同步内置模块检测
• 问题背景：在 ESM 中动态检测内置模块（如 node:os ）过去只能通过异步的 import() 实现，这迫使代码使用顶层 await。
• 同步 API 的引入：为解决此问题并方便工具链（如 TypeScript），Node.js 引入了 process.getBuiltinModule() 这个同步 API，允许在 ESM 中同步获取内置模块引用，减少了对顶层 await 的依赖。

5. 底层实现与同步化
• 概念模型：require(esm) 的简化逻辑是同步地获取、链接、评估 ESM 模块，然后返回其命名空间。
• 同步化重构：实际的挑战在于与异步 import 共享的模块缓存和加载流程可能引发竞态条件。随着 Node.js 生态对同步模块加载的坚定依赖，原先为未来异步扩展设计的加载器例程被简化为完全同步，这既消除了竞态，也移除了不必要的异步开销。

6. 模块评估的可重入性保障
• 规范限制：ECMAScript 规范规定，一个正在评估中的 ESM 模块不能被再次评估。
• 循环依赖处理：当模块依赖循环跨越 ESM 和 CommonJS 边界时，Node.js 通过检测并抛出 ERR_REQUIRE_CYCLE_MODULE 错误来防止违规的重入评估。未来的 “Deferring Module Evaluation” 提案可能允许安全地跳过同步重入评估，从而支持此类循环。

author Joyee Cheung
由 @hyoban 投稿

Joyee Cheung's Blog

require(esm) in Node.js: implementer's tales

In earlier posts, I wrote about reviving require(esm) and its iteration process. The idea seems straightforward once you grasp the ESM semantics, but battle‑testing revealed interop edge cases rooted

#优质博文 #前端 #工程化 #esm
Move on to ESM-only

AI 摘要：作者倡导全面转向 ESM（ECMAScript Modules），因其更优的性能、静态分析能力和未来兼容性，而 CommonJS（CJS）因同步解析和动态 require 等问题已显局限。迁移建议包括启用 "type": "module" 并避免 CJS 专属特性。尽管部分工具仍依赖 CJS，长期来看，ESM 是更现代和可持续的选择。

为了提高 ESM 采用的透明度和可见性，我最近构建了一个可视化的工具，称为 Node Module Inspector，以分析包裹的依赖关系。它提供了有关依赖性 ESM 采用状态的见解，并在迁移到 ESM 时有助于识别潜在的问题。

via antfu

Anthony Fu

Move on to ESM-only

Let's move on to ESM-only

#优质博文 #前端 #工程化 #esm #typescript
Tutorial: publishing ESM-based npm packages with TypeScript

AI 摘要：过去两年，TypeScript、Node.js 和浏览器对 ESM（ECMAScript Modules）的支持取得了显著进展。本教程介绍了一种较为现代、简化的 TypeScript npm 包发布方案，适用于无需考虑向后兼容性的项目。

主要内容：

1. 项目结构：包含 src/ （源码）、test/ （测试）、dist/ （编译输出）、docs/ （文档）等目录。

2. tsconfig.json 配置：

• outDir: "dist" ：编译后的文件存放在 dist/ 目录。
• sourceMap: true、declaration: true、declarationMap: true，确保源码映射和类型定义文件生成。
• verbatimModuleSyntax: true 及 erasableSyntaxOnly: true，提高 TypeScript 代码的可移植性。

3. package.json 相关配置：

• "type": "module" ：确保 .js 文件按 ESM 解析。
• "exports"：明确定义包的 ESM 入口，支持子路径导出。
• "files"：严格控制发布到 npm 的文件，避免上传测试代码。

4. 构建与发布：

• 使用 npm run build 清理 dist/ 目录并重新编译。
• prepublishOnly 钩子在 npm publish 之前自动执行 build，确保发布的代码是最新的。
• publishd 命令用于 npm publish --dry-run，可预览上传的文件。

5. 测试与文档：

• 采用 Mocha 进行单元测试，并支持 source-maps 以优化错误追踪。
• 使用 TypeDoc 生成 API 文档，托管于 GitHub Pages。

6. 其他工具：

• publint、arethetypeswrong 等工具检查 npm 包的兼容性和 TypeScript 类型定义的正确性。
• shx 统一跨平台 shell 命令（如 rm -rf、chmod u+x）。

本指南基于 @rauschma/helpers 包的实践经验，提供了一种现代化、易于维护的 ESM npm 包构建方法。

via 2ality – JavaScript and more

2Ality

Tutorial: publishing ESM-based npm packages with TypeScript

During the last two years, ESM support in TypeScript, Node.js and browsers has made a lot of progress. In this blog post, I explain my modern setup that is relatively simple – compared to what we had to do in the past:

#css #tailwind #前端 #博客更新

Tailwind CSS 的最新版本 v3.3 的一些新特性和改进： Tailwind CSS v3.3：扩展的调色板、ESM/TS 支持、新的实用类

1. 用于深色的扩展调色板：为每种颜色添加了更深的色调——950，现在有11种色调，eg： bg-slate-950

2. ESM 和 TypeScript 支持：使用 ESM 或 TypeScript 编写您的配置文件。（好欸，终于）

3. 微调渐变颜色停止位置 ：可以准确指定渐变颜色中每个色标的位置。如 from-5%、via-35% 和 to-85%

4. 开箱即用的 Line-clamp ：无需插件即可截断多行文本（终于整合到官方啦），如 `line-clamp-3`。 官方：我们在两年多前发布了我们的官方 line-clamp 插件，尽管它使用了一堆奇怪的已弃用的 -webkit-* 东西，但它适用于所有浏览器，而且它将永远有效，所以我们决定将它整合到框架中本身。

5. 🌟字体大小及行高简写 ：这个很有用，可以使用一个类设置字体大小和行高（不在预设中时），如 text-lg/7、 text-sm/[17px] 、 text-[20px]/[24px]

6. 没有 var() 的 CSS 变量：任意值的新速记语法。如下使用
before: bg-[var(--brand-color)]
after: bg-[--brand-color]

7. 可配置的 font-variation-settings ：直接融入您的 font-* 实用程序。

8. 🌟新的 list-style-image 实用类： 这个也很有用，想使用图片作为您的列表项标记吗？那么现在可以使用新的 list-image-* 实用程序。eg： list-image-[url(carrot.png)]

9. 🌟新的 hyphens 实用类：用于微调断字行为。
听说过 ­ HTML 实体吗？在添加对这些 hyphens-* 实用程序的支持之前，我们也没听说。
使用 hyphens-manual 和仔细放置的 ­ ，您可以告诉浏览器在需要跨多行分隔单词时在何处插入连字符。

10. 🌟新的 caption-side 实用程序：用于控制表格内标题元素对齐的实用程序。 caption-bottom 将标题元素定位在表格的顶部，caption-bottom 将标题元素定位在表格的底部。

xLog链接🔗https://x.cosine.ren/tailwind-update-v3-3
Hexo博客地址🔗https://ysx.cosine.ren/tailwind-update-v3-3
RSS订阅📢 https://x.cosine.ren/feed/xml

Tailwindcss

Tailwind CSS v3.3: Extended color palette, ESM/TS support, logical properties, and more

Tailwind CSS v3.3 is here — bringing a bunch of new features people have been asking for forever, and a bunch of new stuff you didn't even know you wanted.