react-spring ESM-only 化改造单一现代 ESM 包、CommonJS 移除与消费端迁移指南【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-springreact-spring 在迈向 11.0 版本时通过一次破坏性重构changeset 标记为react-spring/web: major全面转向ESM-only 发布策略每个包只发布一个现代 ESM 产物dist/name.modern.mjs同时移除 CommonJS 输出、Webpack 4 专用回退与预编译 dev/prod 变体。本文将基于仓库中的变更说明.changeset/esm-only.md与真实构建配置、包清单源码完整还原这次改动的技术细节并给出 Vite、webpack 5、Next.js、Bun、Deno、Node ESM 与 CommonJS 各消费场景下的迁移与兼容方案。这次变更的本质一次发布形态的破坏性重构.changeset/esm-only.md以refactor!:前缀声明这是一次破坏性重构变更对象为react-spring/webmajor 级其核心动作可拆解为四点单一现代 ESM 产物每个包统一发布dist/name.modern.mjs作为唯一入口产物移除 CommonJS 输出不再提供.cjs/.jsCJS 格式文件包的exports映射中不再包含require条件移除 Webpack 4 的legacy-esm回退此前为兼容 Webpack 4 而额外产出的旧式 ESM bundle 被删除移除孤儿化的预编译 dev/prod 变体过去与主包并列发布、供构建工具按环境选择的预编译版本不再保留。这些动作在 .changeset/pre.json 中有清晰的时间上下文仓库正处于betapre-release 模式react-spring/core、react-spring/web等包的初始版本为10.1.1本次 changeset 将随 11.0 主版本一同发布。同批次还包含另一份 major changeset .changeset/remove-deprecated-targets.md移除废弃的 native/konva/zdog 目标与react-spring聚合包两件事共同构成了 11.0 对发布形态与目标矩阵的大清理。仓库源码如何落地 单一 modern ESM 包构建配置tsdown 统一产出.modern.mjs所有包共享同一份构建配置 tsdown.config.base.mjs它决定了单一现代 ESM 包在产物层面的具体形态export const defaultConfig ({ name: prefix, entry }) ({ name: ${prefix}.modern, entry: { [${prefix}.modern]: entry }, format: esm, // 只产出 ESM outDir: dist, platform: neutral, target: es2020, // 现代浏览器 / 现代运行时的语法基线 minify: false, sourcemap: false, clean: false, // 由包级 build 脚本先行清空 dist/ hash: false, dts: true, // 同时生成类型声明 deps: { neverBundle: sharedExternal }, outExtensions: () ({ js: .mjs, dts: .d.mts }), outputOptions: { codeSplitting: false }, })从源码可以确认几个关键事实format: esm与outExtensions强制输出.mjs类型声明为.d.mts从构建层面杜绝了 CJS 产物产生的可能target: es2020是语法基线说明该 bundle 面向的是现代运行环境这也是消费端需要具备 ESM 解析能力的原因dts: true保证 ESM-only 同时保留完整的 TypeScript 类型体验注释明确写道The library ships ESM only: onedist/prefix.modern.mjsbundle plus its.d.mtstypes与 changeset 描述完全一致。包清单exports映射只保留 ESM 条件各发布包的package.json已全部切换为 ESM-first 结构以react-spring/webtargets/web/package.json为例{ name: react-spring/web, version: 11.0.0-beta.0, type: module, module: ./dist/react-spring_web.modern.mjs, types: ./dist/react-spring_web.modern.d.mts, exports: { ./package.json: ./package.json, .: { types: ./dist/react-spring_web.modern.d.mts, default: ./dist/react-spring_web.modern.mjs } }, files: [dist/**/*, README.md, LICENSE] }需要强调的实现事实type: module整包按 ESM 语义解释这是 ESM-only 策略在 Node 侧的声明基础exports只有typesdefault两个条件对比旧版常见的require: ...条件映射这里完全没有 CommonJS 分支——require(react-spring/web)将无法命中默认导出同样的结构出现在 packages/core/package.json、packages/shared/package.json、packages/animated/package.json 与 targets/three/package.json 中印证了 changeset 中每个包Every package的说法——整个 monorepo 的发布形态是统一收敛的。影响面分析谁受影响谁不受影响changeset 给出了明确的消费者分类这是迁移决策的核心依据不受影响ESM 消费者零改动Vite天然 ESM-first开发服务器与生产构建均按 ESM 解析webpack 5原生支持 ESM 解析与exports条件映射Next.js底层使用 webpack 5 / Turbopack均支持 ESM 包esbuild原生 ESM 解析Bun内置 ESM 解析Deno原生 ESM原生 Node ESMimport语法直接加载.mjs。受影响CommonJS 消费者需要行动Node 的require(react-spring/web)在 Node 22.12 上会因包内无 CJS 入口而失败webpack 4legacy-esm回退被删除后不再有任何可用产物webpack 4 正式不再受支持这是本次变更明确的兼容性边界。changeset 同时给出了 CJS 消费者的两条出路原文要点必须完整保留迁移到 ESM把应用/库改为import语法与 ESM 解析流程这是推荐路径运行在 Node ≥ 22.12该版本起 Node 原生支持require()一个 ESM 包require(esm) 特性CommonJS 代码可在不改写语法的情况下继续加载。迁移清单与操作建议基于上述影响面给出可落地的迁移步骤判断自己的消费方式检查package.json是否包含type: commonjs或依赖require(react-spring/...)若你的应用由 Vite/webpack 5/Next/esbuild/Bun/Deno 驱动且使用import则无需任何操作。CJS Node 22.12 的库作者将源码迁移至 ESMtype: moduleimport或升级 Node 到 ≥ 22.12 利用原生 require(esm)。webpack 4 项目升级到 webpack 5或切换到 Vite/esbuild 等支持 ESM 的工具链这是唯一可行路径。注意同批次的另一项 major 变更安装时请直接依赖目标包react-spring/web或react-spring/threereact-spring聚合包与废弃 target 已在 .changeset/remove-deprecated-targets.md 中移除React Native 场景官方建议转向在 UI 线程运行动画的替代方案。类型检查dist/name.modern.d.mts随包发布TypeScript 消费者在moduleResolution: bundler/nodenext下应能无缝获得类型。在仓库中验证 ESM-only 构建如需在本仓库复现与验证可执行# 安装依赖仓库使用 pnpm workspace见 package.json 的 packageManager 字段 pnpm install # 构建全部包turbo 编排跳过文档站点 pnpm build-ci构建后检查任意包的dist/目录如targets/web/dist/应只看到react-spring_web.modern.mjs及其.d.mts类型声明不存在任何.cjs文件——这与 tsdown.config.base.mjs 的配置完全对应。注意仓库根 package.json 声明的开发环境为node 24.16.0、pnpm9.15.9这是开发构建环境要求与前面 changeset 所述消费者 Node ≥ 22.12 可 require(esm)是两回事请勿混淆。总结react-spring 的 ESM-only 重构是一次彻底的发布形态收敛从 tsdown.config.base.mjs 的单一esm产物配置到各包package.json中仅保留typesdefault的exports映射再到 changeset 中明示的兼容性边界——现代 ESM 工具链Vite、webpack 5、Next、esbuild、Bun、Deno、原生 Node ESM全程无感CommonJS 消费者则需迁移到 ESM 或使用 Node ≥ 22.12 的 require(esm) 能力webpack 4 正式退出支持范围。对下游开发者而言这次变更换来的是更小的包体、更清晰的产物矩阵以及与现代前端工具链完全对齐的模块语义。【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
react-spring ESM-only 化改造：单一现代 ESM 包、CommonJS 移除与消费端迁移指南
react-spring ESM-only 化改造单一现代 ESM 包、CommonJS 移除与消费端迁移指南【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-springreact-spring 在迈向 11.0 版本时通过一次破坏性重构changeset 标记为react-spring/web: major全面转向ESM-only 发布策略每个包只发布一个现代 ESM 产物dist/name.modern.mjs同时移除 CommonJS 输出、Webpack 4 专用回退与预编译 dev/prod 变体。本文将基于仓库中的变更说明.changeset/esm-only.md与真实构建配置、包清单源码完整还原这次改动的技术细节并给出 Vite、webpack 5、Next.js、Bun、Deno、Node ESM 与 CommonJS 各消费场景下的迁移与兼容方案。这次变更的本质一次发布形态的破坏性重构.changeset/esm-only.md以refactor!:前缀声明这是一次破坏性重构变更对象为react-spring/webmajor 级其核心动作可拆解为四点单一现代 ESM 产物每个包统一发布dist/name.modern.mjs作为唯一入口产物移除 CommonJS 输出不再提供.cjs/.jsCJS 格式文件包的exports映射中不再包含require条件移除 Webpack 4 的legacy-esm回退此前为兼容 Webpack 4 而额外产出的旧式 ESM bundle 被删除移除孤儿化的预编译 dev/prod 变体过去与主包并列发布、供构建工具按环境选择的预编译版本不再保留。这些动作在 .changeset/pre.json 中有清晰的时间上下文仓库正处于betapre-release 模式react-spring/core、react-spring/web等包的初始版本为10.1.1本次 changeset 将随 11.0 主版本一同发布。同批次还包含另一份 major changeset .changeset/remove-deprecated-targets.md移除废弃的 native/konva/zdog 目标与react-spring聚合包两件事共同构成了 11.0 对发布形态与目标矩阵的大清理。仓库源码如何落地 单一 modern ESM 包构建配置tsdown 统一产出.modern.mjs所有包共享同一份构建配置 tsdown.config.base.mjs它决定了单一现代 ESM 包在产物层面的具体形态export const defaultConfig ({ name: prefix, entry }) ({ name: ${prefix}.modern, entry: { [${prefix}.modern]: entry }, format: esm, // 只产出 ESM outDir: dist, platform: neutral, target: es2020, // 现代浏览器 / 现代运行时的语法基线 minify: false, sourcemap: false, clean: false, // 由包级 build 脚本先行清空 dist/ hash: false, dts: true, // 同时生成类型声明 deps: { neverBundle: sharedExternal }, outExtensions: () ({ js: .mjs, dts: .d.mts }), outputOptions: { codeSplitting: false }, })从源码可以确认几个关键事实format: esm与outExtensions强制输出.mjs类型声明为.d.mts从构建层面杜绝了 CJS 产物产生的可能target: es2020是语法基线说明该 bundle 面向的是现代运行环境这也是消费端需要具备 ESM 解析能力的原因dts: true保证 ESM-only 同时保留完整的 TypeScript 类型体验注释明确写道The library ships ESM only: onedist/prefix.modern.mjsbundle plus its.d.mtstypes与 changeset 描述完全一致。包清单exports映射只保留 ESM 条件各发布包的package.json已全部切换为 ESM-first 结构以react-spring/webtargets/web/package.json为例{ name: react-spring/web, version: 11.0.0-beta.0, type: module, module: ./dist/react-spring_web.modern.mjs, types: ./dist/react-spring_web.modern.d.mts, exports: { ./package.json: ./package.json, .: { types: ./dist/react-spring_web.modern.d.mts, default: ./dist/react-spring_web.modern.mjs } }, files: [dist/**/*, README.md, LICENSE] }需要强调的实现事实type: module整包按 ESM 语义解释这是 ESM-only 策略在 Node 侧的声明基础exports只有typesdefault两个条件对比旧版常见的require: ...条件映射这里完全没有 CommonJS 分支——require(react-spring/web)将无法命中默认导出同样的结构出现在 packages/core/package.json、packages/shared/package.json、packages/animated/package.json 与 targets/three/package.json 中印证了 changeset 中每个包Every package的说法——整个 monorepo 的发布形态是统一收敛的。影响面分析谁受影响谁不受影响changeset 给出了明确的消费者分类这是迁移决策的核心依据不受影响ESM 消费者零改动Vite天然 ESM-first开发服务器与生产构建均按 ESM 解析webpack 5原生支持 ESM 解析与exports条件映射Next.js底层使用 webpack 5 / Turbopack均支持 ESM 包esbuild原生 ESM 解析Bun内置 ESM 解析Deno原生 ESM原生 Node ESMimport语法直接加载.mjs。受影响CommonJS 消费者需要行动Node 的require(react-spring/web)在 Node 22.12 上会因包内无 CJS 入口而失败webpack 4legacy-esm回退被删除后不再有任何可用产物webpack 4 正式不再受支持这是本次变更明确的兼容性边界。changeset 同时给出了 CJS 消费者的两条出路原文要点必须完整保留迁移到 ESM把应用/库改为import语法与 ESM 解析流程这是推荐路径运行在 Node ≥ 22.12该版本起 Node 原生支持require()一个 ESM 包require(esm) 特性CommonJS 代码可在不改写语法的情况下继续加载。迁移清单与操作建议基于上述影响面给出可落地的迁移步骤判断自己的消费方式检查package.json是否包含type: commonjs或依赖require(react-spring/...)若你的应用由 Vite/webpack 5/Next/esbuild/Bun/Deno 驱动且使用import则无需任何操作。CJS Node 22.12 的库作者将源码迁移至 ESMtype: moduleimport或升级 Node 到 ≥ 22.12 利用原生 require(esm)。webpack 4 项目升级到 webpack 5或切换到 Vite/esbuild 等支持 ESM 的工具链这是唯一可行路径。注意同批次的另一项 major 变更安装时请直接依赖目标包react-spring/web或react-spring/threereact-spring聚合包与废弃 target 已在 .changeset/remove-deprecated-targets.md 中移除React Native 场景官方建议转向在 UI 线程运行动画的替代方案。类型检查dist/name.modern.d.mts随包发布TypeScript 消费者在moduleResolution: bundler/nodenext下应能无缝获得类型。在仓库中验证 ESM-only 构建如需在本仓库复现与验证可执行# 安装依赖仓库使用 pnpm workspace见 package.json 的 packageManager 字段 pnpm install # 构建全部包turbo 编排跳过文档站点 pnpm build-ci构建后检查任意包的dist/目录如targets/web/dist/应只看到react-spring_web.modern.mjs及其.d.mts类型声明不存在任何.cjs文件——这与 tsdown.config.base.mjs 的配置完全对应。注意仓库根 package.json 声明的开发环境为node 24.16.0、pnpm9.15.9这是开发构建环境要求与前面 changeset 所述消费者 Node ≥ 22.12 可 require(esm)是两回事请勿混淆。总结react-spring 的 ESM-only 重构是一次彻底的发布形态收敛从 tsdown.config.base.mjs 的单一esm产物配置到各包package.json中仅保留typesdefault的exports映射再到 changeset 中明示的兼容性边界——现代 ESM 工具链Vite、webpack 5、Next、esbuild、Bun、Deno、原生 Node ESM全程无感CommonJS 消费者则需迁移到 ESM 或使用 Node ≥ 22.12 的 require(esm) 能力webpack 4 正式退出支持范围。对下游开发者而言这次变更换来的是更小的包体、更清晰的产物矩阵以及与现代前端工具链完全对齐的模块语义。【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
