在 Next.js 中集成 tldraw SDK基于官方模板从零搭建无限画布应用【免费下载链接】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导读本指南以官方 Next.js 模板 为核心讲解如何把 tldraw SDK 集成进 Next.js 应用从安装依赖、启动开发服务器到理解Tldraw组件的挂载方式与相关配置文件的底层作用。读完本文你将能够基于 App Router 架构快速搭建一个全屏可用的画布应用并掌握在生产构建、TypeScript 与样式加载等环节中需要注意的关键配置。模板定位一个最小可运行的 tldraw Next.js 起点仓库根目录下的templates/目录维护了多套官方脚手架nextjs模板正是其中为 Next.js 框架量身定制的一套它把 tldraw SDK 与 Next.js 的 App Router 目录结构整合在一起开箱即用。模板的真实文件结构如下templates/nextjs/ ├── LICENSE.md # 模板自身的 MIT 许可 ├── README.md # 使用说明本指南依据的文档 ├── next.config.mjs # Next.js 配置 ├── package.json # 依赖与脚本 ├── tsconfig.json # TypeScript 配置 └── src/ └── app/ ├── favicon.ico ├── globals.css # 全局样式引入 tldraw 的样式文件 ├── layout.tsx # 根布局输出页面 metadata └── page.tsx # 首页挂载 Tldraw / 组件模板的核心目标是展示“在 Next.js 中使用 tldraw 的最小正确姿势”一个page.tsx、一个根布局、一个全局样式文件外加三条 npm scripts。所有其他能力持久化、多人协作、自定义 UI都建立在这套骨架之上。本地开发三步跑起来README 明确给出了本地开发的完整流程这是从零开始的第一步共三步安装依赖使用yarn或npm install项目包管理器可二选一package.json 中声明了全部依赖。启动开发服务器运行yarn dev或npm run dev。打开浏览器访问http://localhost:3000/即可看到全屏画布应用。在 monorepo 场景下开发者通常从仓库根目录执行yarn dev配合lerna.json与根 package.json 的工作区机制模板内的脚本定义如下scripts: { dev: next dev -H 0.0.0.0, build: next build, start: next start, lint: yarn run -T tsx ../../internal/scripts/lint.ts }几个值得注意的细节dev脚本带有-H 0.0.0.0允许通过局域网 IP 访问开发服务器便于在容器或远程环境中调试lint复用了仓库根目录internal/scripts/lint.ts的统一 lint 流程而不是在模板内单独配置 lintbuild/start分别是生产构建与生产启动命令与next dev形成完整闭环。核心代码拆解画布是如何挂载的1. 页面组件三行代码渲染画布模板的首页位于 page.tsx全文如下use client import { Tldraw } from tldraw export default function Home() { return ( main div style{{ position: fixed, inset: 0 }} Tldraw / /div /main ) }这里有两个关键点use client指令由于Tldraw组件依赖浏览器 API如 Pointer Events、IndexedDB 等在 Next.js App Router 中必须显式声明为客户端组件否则服务端渲染阶段会报错。这是模板中最重要的集成要点。position: fixed; inset: 0将外层容器固定并撑满整个视口使画布获得全屏的交互区域。Tldraw组件会创建自己的编辑器实例与无限画布坐标系无需任何其他 props 即可获得完整功能选择、绘制、标注、导出等。2. 根布局注入全局样式与 metadatalayout.tsx 定义了根布局导入全局样式并输出页面元信息import ./globals.css export const metadata { title: tldraw Next.js app template, description: An example of how to use tldraw in a Next.js app, }值得注意的是模板没有引入任何 UI 库或字体渲染框架metadata也保持极简把渲染空间完全交给 tldraw。3. 全局样式必须引入 tldraw.cssglobals.css 是让画布“看起来正常”的关键import url(https://fonts.googleapis.com/css2?familyInter:wght500;700displayswap); import url(tldraw/tldraw.css); body { font-family: Inter; overscroll-behavior: none; }import url(tldraw/tldraw.css)通过包名直接引入 tldraw 打包产出的样式文件。该文件由 packages/tldraw 的构建脚本scripts/copy-css-files.mjs拷贝生成并被列入包的files字段随 npm 包一起发布overscroll-behavior: none禁用浏览器在画布边缘的滚动链式回弹避免拖动画布时触发整页滚动——这是所有嵌入类画布应用的通用最佳实践模板选用 Inter 字体并声明了500/700两个字重以满足工具面板的文字渲染需求。4. Next.js 配置将 tldraw 标记为服务端外部包next.config.mjs 中有一项容易被忽视但至关重要的配置/** type {import(next).NextConfig} */ const nextConfig { serverExternalPackages: [tldraw/tldraw], } export default nextConfigserverExternalPackages告诉 Next.js 不要把tldraw/tldraw打进服务端 bundle而是作为外部包在运行时解析。tldraw 内部依赖浏览器全局对象与第三方库如idb、lz-string、tiptap/*此配置可以有效规避服务端打包时的兼容性问题确保use client组件在客户端正确加载。5. TypeScript 配置路径别名与项目引用tsconfig.json 采用 Next.js 标准配置其中有两点与 tldraw 相关paths定义/*指向./src/*方便业务代码使用短路径导入references指向../../packages/tldraw让模板在 monorepo 中直接引用 tldraw 源码包package.json中tldraw: workspace:*与之对应这是模板能够跟随 SDK 主分支实时迭代的前提。底层原理Tldraw组件从何而来模板只引入了Tldraw这一个组件但它背后是完整的 SDK 导出体系。packages/tldraw/src/index.ts 中的导出语句说明了组件来源export { Tldraw, type TLComponents, type TldrawBaseProps, type TldrawProps } from ./lib/Tldraw该文件同时通过export * from tldraw/editorindex.ts透传了编辑器层能力并从 packages/editor含tldraw/state、tldraw/store、tldraw/tlschema等核心包逐层构建出完整 SDK。从依赖声明看packages/tldraw/package.json 的 peerDependencies 要求react/react-dom版本为^18.2.0 || ^19.2.1而模板固定使用 React 19 与 Next.js 16版本组合是官方验证过的。需要特别说明Tldraw /不带任何 props 时提供的是完整的编辑器 默认 UI工具栏、样式面板、菜单等。SDK 还导出TldrawImageindex.ts等组件以及大量可替换的 UI 部件DefaultToolbar、DefaultMainMenu等模板的“零配置可用”正是这套默认装配的体现。生产构建与部署完成yarn dev本地验证后生产环境流程为yarn build # 产出 .next 静态构建产物 yarn start # 以生产模式启动服务由于画布状态默认保存在浏览器本地tldraw 自带基于 IndexedDB 的持久化该模板无需后端即可作为一个完整的单机白板应用部署到任意支持 Node.js 的平台。如果需要多人实时协作或云端存储可以在此基础上接入仓库中的 sync、sync-core 等协作包或参考apps/dotcom的生产级实现。许可与使用边界模板自身采用 MIT 许可见 templates/nextjs/LICENSE.md而 tldraw SDK 采用其独立的商业许可二者是分离的MIT 许可只覆盖模板脚手架代码不覆盖 SDK 本体。仓库根目录的 LICENSE.md 与 TRADEMARKS.md 分别说明了 SDK 的许可条款与 tldraw 名称、Logo 的商标使用规范商用前务必阅读确认。小结官方 Next.js 模板用最精简的文件证明了 tldraw 与 Next.js 的集成路径一个use client页面挂载Tldraw /、一份引入tldraw/tldraw.css的全局样式、一条serverExternalPackages配置再加上dev/build/start三条脚本即可完成从本地开发到生产部署的完整闭环。以这套骨架为起点你可以继续借助 packages/tldraw/src/index.ts 中导出的编辑器 API 与 UI 覆盖机制逐步定制属于自己的无限画布应用。【免费下载链接】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），仅供参考