takumi

环境要求

• Bun 运行时（README 示例用 Bun 直接运行 JSX 文件）
• Node.js 或 Bun 环境（会自动加载预编译原生绑定）
• 如需在 Cloudflare Workers / 浏览器使用，则走 WebAssembly 构建
• 如需在 Rust 项目中使用，需引入 takumi crate

安装与启动步骤

1. 1安装图像渲染包

   在项目目录安装 takumi-js，支持输出 PNG、JPEG、WebP、SVG 和动画。

   bun i takumi-js

   复制

2. 2安装 PDF 渲染包

   如需生成分页 PDF，额外安装 takumi-pdf，可与 takumi-js 并存。

   bun i takumi-pdf

   复制

3. 3编写图片脚本

   新建 image.tsx，用 render 传入 JSX 和尺寸，README 示例输出 1200×630 PNG。

   import { render } from "takumi-js";
   import { writeFile } from "node:fs/promises";
   
   const image = await render(
     <div tw="w-full h-full flex items-center justify-center bg-linear-to-b from-blue-100 to-red-50">
       <h1 tw="text-6xl font-bold">Hello from Takumi</h1>
     </div>,
     { width: 1200, height: 630 },
   );
   
   await writeFile("./output.png", image);

   复制

4. 4运行图片脚本

   用 Bun 直接执行 tsx 文件，在当前目录写出 output.png。

   bun image.tsx

   复制

5. 5编写 PDF 脚本

   新建 document.tsx，可指定 a4 尺寸并通过 footer 加页码页脚。

   import { render } from "takumi-pdf";
   import { PageNumber, TotalPages } from "takumi-pdf/primitives";
   import { writeFile } from "node:fs/promises";
   
   const pdf = await render(
     <main>
       <h1>Invoice</h1>
       <p>Total: $1,250.00</p>
     </main>,
     {
       size: "a4",
       footer: (
         <div tw="flex w-full justify-center text-[10px] text-gray-500">
           <PageNumber /> / <TotalPages />
         </div>
       ),
     },
   );

   复制

6. 6运行 PDF 脚本

   执行 Bun 命令生成 A4 分页 PDF 文档文件。

   bun document.tsx

   复制

关键配置

如何确认成功

运行 bun image.tsx 后当前目录生成 output.png（1200×630）；运行 bun document.tsx 生成对应 A4 PDF。

常见问题

注意事项

• README 示例统一使用 Bun 运行 JSX，若换用其他运行时请自行确认是否支持直接执行 TSX。
• 样式写在 JSX 的 tw 属性中（Tailwind 风格），尺寸通过 render 的第二个参数传入。
• 安装方式按包区分：takumi-js 负责 PNG/JPEG/WebP/SVG 与动画，takumi-pdf 负责分页 PDF。