拓冰网站定制 
tldraw 仓库中的tldraw/tldraw遗留兼容包它是什么、如何工作、为何应该改用tldraw【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw导读在 tldraw SDK 的 monorepo 中packages/namespaced-tldraw目录对应 npm 包tldraw/tldraw这是一个为历史兼容而保留的“薄壳”包它本身不实现任何画布逻辑而是完整地重新导出标准tldraw包的全部 API并注册库版本信息与打包 CSS 资源。本文将基于该包在仓库中的 README、源码、构建脚本与测试拆解它的定位、实现机制、构建流程与许可约束并给出从旧包名迁移到tldraw的实操建议。一、这个包为什么存在历史包袱与迁移过渡阅读 packages/namespaced-tldraw/README.md 可以看到官方对该包的定位非常直白This package is kept around for legacy purposes. It just tracks the normaltldrawpackage. Please install that one instead.也就是说tldraw/tldraw是被保留的旧包名仅用于照顾历史用户与存量代码它本身不维护独立功能而是始终跟踪并跟随标准tldraw包的发布节奏新项目应当直接安装tldraw而不是tldraw/tldraw。从仓库中的 package.json 可以印证这一点该包的name为tldraw/tldraw版本号与tldraw包完全一致当前均为 5.4.0其唯一运行时依赖就是tldraw: workspace:*monorepo 工作区引用保证两者永远同步发布。二、包的结构一个几乎“空”的入口整个包的结构非常精简核心文件只有三个文件作用src/index.ts包的唯一入口重新导出tldraw并注册版本src/index.test.ts验证导出完整性的单元测试scripts/copy-css-files.mjs构建期合并生成tldraw.css其 API 报告api-report.api.md也证实了这一点——整个包的公开 API 只有一行export * from tldraw;这意味着tldraw/tldraw的完整类型面TypeScript 类型、Editor类、Tldraw组件、各类 shape 工具、Vec/VecModel等几何工具与类型与tldraw包逐字一致不会多也不会少。三、核心实现re-export 与版本注册的完整机制3.1 入口文件的完整逻辑packages/namespaced-tldraw/src/index.ts全文仅数行但包含了两个关键动作import { registerTldrawLibraryVersion } from tldraw // eslint-disable-next-line tldraw/no-export-star export * from tldraw registerTldrawLibraryVersion( (globalThis as any).TLDRAW_LIBRARY_NAME, (globalThis as any).TLDRAW_LIBRARY_VERSION, (globalThis as any).TLDRAW_LIBRARY_MODULES )动作一全量重新导出。export * from tldraw让使用旧包名的代码无需改动即可获得tldraw的全部命名导出。文件头部的eslint-disable-next-line tldraw/no-export-star注释说明仓库的 lint 规则本身反对export *的写法避免命名冲突与 API 面失控但此处的通配导出是有意为之——它正是“兼容壳”的本质。动作二注册库版本信息。registerTldrawLibraryVersion接收三个来自globalThis的注入值TLDRAW_LIBRARY_NAME、TLDRAW_LIBRARY_VERSION、TLDRAW_LIBRARY_MODULES这些值由构建期工具注入用于在运行时把当前加载的 SDK 版本与模块清单登记到全局便于调试、错误上报与版本一致性检测。值得注意tldraw包自身的入口 packages/tldraw/src/index.ts 也以完全相同的模式在文件末尾调用registerTldrawLibraryVersion。也就是说tldraw/tldraw与tldraw的“自我注册”行为完全对齐二者在运行时行为上没有可感知差异。3.2 底层依赖关系从 package.json 可以进一步看到这个壳的边界dependencies仅tldrawworkspace 引用其余一切由tldraw内部消化peerDependenciesreact: ^18.2.0 || ^19.2.1、react-dom: ^18.2.0 || ^19.2.1与tldraw包 packages/tldraw/package.json 声明的 peer 范围一致——React 18.2 及以上、React 19.2.1 及以上均可engines.node: 22.12.0开发与构建环境要求 Node.js 22.12 或更高版本。而tldraw包本身则聚合了tldraw/editor、tldraw/state、tldraw/store、tldraw/tlschema、tldraw/driver等核心工作区包以及tiptap/*文本编辑、idbIndexedDB 持久化、lz-string压缩等依赖。因此当你的应用只安装tldraw时画布引擎、状态管理、数据模型与 UI 全套能力都会随之就位。四、构建机制CSS 从哪来由于壳包自身没有 UI 源码它的样式文件需要在构建期生成。packages/namespaced-tldraw/scripts/copy-css-files.mjs实现了这一逻辑let combinedContent [ join(packageDir, .., editor, editor.css), join(packageDir, .., tldraw, src, lib, ui.css), ].reduce((acc, path) { const content readFileSync(path, utf8) acc content \n return acc }, /* THIS CSS FILE IS GENERATED! ... */)该脚本将两份源样式拼接为最终的tldraw.csspackages/editor/editor.css——来自tldraw/editor的核心画布样式packages/tldraw/src/lib/ui.css——来自tldraw的 UI工具栏、菜单、面板等样式。脚本注释特别说明它直接从源文件生成 CSS而不是依赖tldraw构建产出的tldraw.css这是为了避免 lazyrepo 缓存跳过 prebuild 步骤时产物缺失的问题。对应的 package.json scripts 也体现了这条流水线predev: node ./scripts/copy-css-files.mjs, dev: chokidar ../tldraw/tldraw.css -c node ./scripts/copy-css-files.mjs, prebuild: node ./scripts/copy-css-files.mjs, build: yarn run -T tsx ../../internal/scripts/build-package.ts即开发时用chokidar监听源 CSS 变化并自动重新合并构建前通过predev/prebuild钩子强制生成。files字段中仅发布tldraw.css说明这个包在 npm 上真正对外提供的就是“JS re-export 一份合并样式”。五、质量保障测试如何验证“壳”的完整性packages/namespaced-tldraw/src/index.test.ts用两个用例确保 re-export 没有失效import * as tldraw from ./index it(exports things from tldraw, () { expect(tldraw).toHaveProperty(Tldraw) expect(new tldraw.Vec()).toMatchObject({ x: 0, y: 0 }) }) it(exports types from tldraw, () { const _thing: tldraw.VecModel { x: 0, y: 0 } })第一个用例验证值导出Tldraw组件存在toHaveProperty并且Vec是可实例化的类new tldraw.Vec()得到{ x: 0, y: 0 }说明构造默认值正确第二个用例验证类型导出VecModel这样的 TypeScript 类型也能从壳包导入并被正常使用。这两个测试恰好覆盖了“值”与“类型”两个维度确保export * from tldraw的两类导出都健康。测试运行使用vitest并复用根目录 vitest.config.ts 体系——该包的 vitest.config.ts 直接继承internal/config/vitest/node-preset标准 Node 预设无额外覆盖。六、使用建议新项目请直接安装tldraw结合 README 的指引与仓库实现对使用者最直接的结论是# 旧写法兼容但不推荐用于新项目 yarn add tldraw/tldraw # 推荐写法 yarn add tldraw迁移时你几乎不需要改动业务代码因为两个包的导出面完全一致这正是export *的意义所在。唯一需要留意的差异点是样式导入确认你的样式引用从tldraw/tldraw/tldraw.css切换到tldraw/tldraw.css二者都是构建期由同一份源 CSS 生成的合并文件peer 依赖确保 React 版本落在^18.2.0 || ^19.2.1区间内Node 版本仓库开发环境要求 Node 22.12.0对应engines字段。如果你正在阅读tldraw的源码比如 packages/tldraw/src/index.ts 中的Editor、Tldraw等全部导出可以把tldraw/tldraw当作一层透明的代理来理解任何对它的调用最终都落在tldraw包上。七、许可与商标沿用 SDK 的统一约束README 还交代了使用该包时需要注意的合规边界这里同样适用于tldraw包许可作为 tldraw SDK 的一部分本包依据 tldraw SDK 许可提供见仓库根目录 LICENSE.md水印要求你可以将 tldraw SDK 用于商业或非商业项目但前提是保留画布上的 “Made with tldraw” 水印如需移除水印需要购买商业许可商标tldraw 名称与 Logo 是 tldraw Inc. 的商标Copyright (c) 2024-present tldraw Inc.使用需遵守仓库根目录 TRADEMARKS.md 中的商标使用准则。结语tldraw/tldraw是 tldraw 演进史留下的一个“版本钉子”它用最克制的实现一行通配导出 版本注册 构建期 CSS 合并保证了旧用户的无痛升级同时让仓库的 API 面与许可约束保持单一事实来源。理解它的存在能帮你避免在排查依赖时被两个相似包名迷惑——记住核心结论即可功能永远以tldraw为准tldraw/tldraw只是它的镜像。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 tldraw 仓库中的 `@tldraw/tldraw` 遗留兼容包：它是什么、如何工作、为何应该改用 `tldraw`
tldraw 仓库中的tldraw/tldraw遗留兼容包它是什么、如何工作、为何应该改用tldraw【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw导读在 tldraw SDK 的 monorepo 中packages/namespaced-tldraw目录对应 npm 包tldraw/tldraw这是一个为历史兼容而保留的“薄壳”包它本身不实现任何画布逻辑而是完整地重新导出标准tldraw包的全部 API并注册库版本信息与打包 CSS 资源。本文将基于该包在仓库中的 README、源码、构建脚本与测试拆解它的定位、实现机制、构建流程与许可约束并给出从旧包名迁移到tldraw的实操建议。一、这个包为什么存在历史包袱与迁移过渡阅读 packages/namespaced-tldraw/README.md 可以看到官方对该包的定位非常直白This package is kept around for legacy purposes. It just tracks the normaltldrawpackage. Please install that one instead.也就是说tldraw/tldraw是被保留的旧包名仅用于照顾历史用户与存量代码它本身不维护独立功能而是始终跟踪并跟随标准tldraw包的发布节奏新项目应当直接安装tldraw而不是tldraw/tldraw。从仓库中的 package.json 可以印证这一点该包的name为tldraw/tldraw版本号与tldraw包完全一致当前均为 5.4.0其唯一运行时依赖就是tldraw: workspace:*monorepo 工作区引用保证两者永远同步发布。二、包的结构一个几乎“空”的入口整个包的结构非常精简核心文件只有三个文件作用src/index.ts包的唯一入口重新导出tldraw并注册版本src/index.test.ts验证导出完整性的单元测试scripts/copy-css-files.mjs构建期合并生成tldraw.css其 API 报告api-report.api.md也证实了这一点——整个包的公开 API 只有一行export * from tldraw;这意味着tldraw/tldraw的完整类型面TypeScript 类型、Editor类、Tldraw组件、各类 shape 工具、Vec/VecModel等几何工具与类型与tldraw包逐字一致不会多也不会少。三、核心实现re-export 与版本注册的完整机制3.1 入口文件的完整逻辑packages/namespaced-tldraw/src/index.ts全文仅数行但包含了两个关键动作import { registerTldrawLibraryVersion } from tldraw // eslint-disable-next-line tldraw/no-export-star export * from tldraw registerTldrawLibraryVersion( (globalThis as any).TLDRAW_LIBRARY_NAME, (globalThis as any).TLDRAW_LIBRARY_VERSION, (globalThis as any).TLDRAW_LIBRARY_MODULES )动作一全量重新导出。export * from tldraw让使用旧包名的代码无需改动即可获得tldraw的全部命名导出。文件头部的eslint-disable-next-line tldraw/no-export-star注释说明仓库的 lint 规则本身反对export *的写法避免命名冲突与 API 面失控但此处的通配导出是有意为之——它正是“兼容壳”的本质。动作二注册库版本信息。registerTldrawLibraryVersion接收三个来自globalThis的注入值TLDRAW_LIBRARY_NAME、TLDRAW_LIBRARY_VERSION、TLDRAW_LIBRARY_MODULES这些值由构建期工具注入用于在运行时把当前加载的 SDK 版本与模块清单登记到全局便于调试、错误上报与版本一致性检测。值得注意tldraw包自身的入口 packages/tldraw/src/index.ts 也以完全相同的模式在文件末尾调用registerTldrawLibraryVersion。也就是说tldraw/tldraw与tldraw的“自我注册”行为完全对齐二者在运行时行为上没有可感知差异。3.2 底层依赖关系从 package.json 可以进一步看到这个壳的边界dependencies仅tldrawworkspace 引用其余一切由tldraw内部消化peerDependenciesreact: ^18.2.0 || ^19.2.1、react-dom: ^18.2.0 || ^19.2.1与tldraw包 packages/tldraw/package.json 声明的 peer 范围一致——React 18.2 及以上、React 19.2.1 及以上均可engines.node: 22.12.0开发与构建环境要求 Node.js 22.12 或更高版本。而tldraw包本身则聚合了tldraw/editor、tldraw/state、tldraw/store、tldraw/tlschema、tldraw/driver等核心工作区包以及tiptap/*文本编辑、idbIndexedDB 持久化、lz-string压缩等依赖。因此当你的应用只安装tldraw时画布引擎、状态管理、数据模型与 UI 全套能力都会随之就位。四、构建机制CSS 从哪来由于壳包自身没有 UI 源码它的样式文件需要在构建期生成。packages/namespaced-tldraw/scripts/copy-css-files.mjs实现了这一逻辑let combinedContent [ join(packageDir, .., editor, editor.css), join(packageDir, .., tldraw, src, lib, ui.css), ].reduce((acc, path) { const content readFileSync(path, utf8) acc content \n return acc }, /* THIS CSS FILE IS GENERATED! ... */)该脚本将两份源样式拼接为最终的tldraw.csspackages/editor/editor.css——来自tldraw/editor的核心画布样式packages/tldraw/src/lib/ui.css——来自tldraw的 UI工具栏、菜单、面板等样式。脚本注释特别说明它直接从源文件生成 CSS而不是依赖tldraw构建产出的tldraw.css这是为了避免 lazyrepo 缓存跳过 prebuild 步骤时产物缺失的问题。对应的 package.json scripts 也体现了这条流水线predev: node ./scripts/copy-css-files.mjs, dev: chokidar ../tldraw/tldraw.css -c node ./scripts/copy-css-files.mjs, prebuild: node ./scripts/copy-css-files.mjs, build: yarn run -T tsx ../../internal/scripts/build-package.ts即开发时用chokidar监听源 CSS 变化并自动重新合并构建前通过predev/prebuild钩子强制生成。files字段中仅发布tldraw.css说明这个包在 npm 上真正对外提供的就是“JS re-export 一份合并样式”。五、质量保障测试如何验证“壳”的完整性packages/namespaced-tldraw/src/index.test.ts用两个用例确保 re-export 没有失效import * as tldraw from ./index it(exports things from tldraw, () { expect(tldraw).toHaveProperty(Tldraw) expect(new tldraw.Vec()).toMatchObject({ x: 0, y: 0 }) }) it(exports types from tldraw, () { const _thing: tldraw.VecModel { x: 0, y: 0 } })第一个用例验证值导出Tldraw组件存在toHaveProperty并且Vec是可实例化的类new tldraw.Vec()得到{ x: 0, y: 0 }说明构造默认值正确第二个用例验证类型导出VecModel这样的 TypeScript 类型也能从壳包导入并被正常使用。这两个测试恰好覆盖了“值”与“类型”两个维度确保export * from tldraw的两类导出都健康。测试运行使用vitest并复用根目录 vitest.config.ts 体系——该包的 vitest.config.ts 直接继承internal/config/vitest/node-preset标准 Node 预设无额外覆盖。六、使用建议新项目请直接安装tldraw结合 README 的指引与仓库实现对使用者最直接的结论是# 旧写法兼容但不推荐用于新项目 yarn add tldraw/tldraw # 推荐写法 yarn add tldraw迁移时你几乎不需要改动业务代码因为两个包的导出面完全一致这正是export *的意义所在。唯一需要留意的差异点是样式导入确认你的样式引用从tldraw/tldraw/tldraw.css切换到tldraw/tldraw.css二者都是构建期由同一份源 CSS 生成的合并文件peer 依赖确保 React 版本落在^18.2.0 || ^19.2.1区间内Node 版本仓库开发环境要求 Node 22.12.0对应engines字段。如果你正在阅读tldraw的源码比如 packages/tldraw/src/index.ts 中的Editor、Tldraw等全部导出可以把tldraw/tldraw当作一层透明的代理来理解任何对它的调用最终都落在tldraw包上。七、许可与商标沿用 SDK 的统一约束README 还交代了使用该包时需要注意的合规边界这里同样适用于tldraw包许可作为 tldraw SDK 的一部分本包依据 tldraw SDK 许可提供见仓库根目录 LICENSE.md水印要求你可以将 tldraw SDK 用于商业或非商业项目但前提是保留画布上的 “Made with tldraw” 水印如需移除水印需要购买商业许可商标tldraw 名称与 Logo 是 tldraw Inc. 的商标Copyright (c) 2024-present tldraw Inc.使用需遵守仓库根目录 TRADEMARKS.md 中的商标使用准则。结语tldraw/tldraw是 tldraw 演进史留下的一个“版本钉子”它用最克制的实现一行通配导出 版本注册 构建期 CSS 合并保证了旧用户的无痛升级同时让仓库的 API 面与许可约束保持单一事实来源。理解它的存在能帮你避免在排查依赖时被两个相似包名迷惑——记住核心结论即可功能永远以tldraw为准tldraw/tldraw只是它的镜像。【免费下载链接】tldrawBuild infinite canvas apps in React with the tldraw SDK. Worlds best, top-most agent recommended #1 five star SDK.项目地址: https://gitcode.com/GitHub_Trending/tl/tldraw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考