Troubleshooting

General Issues

Layout is not correct

Set the drawDebugBorder option to outline every node.

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<></>, {
    width: 100,
    height: 100,
    drawDebugBorder: true,
    // ...
  });
}

If the issue persists, file an issue on our GitHub repository.

Browser Issues

Export default doesn't exist in target module

takumi-js/wasm picks its wasm loader from the export conditions the bundler sets. Vite, webpack, and Turbopack set the same conditions for a browser build. All three land on the Vite entry, and its ?url import only works in Vite.

Load the binary yourself instead:

import wasmUrl from "takumi-js/wasm-url";
import { init, Renderer } from "takumi-js/wasm/no-init";

await init({ module_or_path: wasmUrl });

takumi-js/wasm-url resolves the binary with new URL(specifier, import.meta.url). Vite, webpack, and Turbopack rewrite that call to the asset they emit. Server code should keep takumi-js/wasm, which locates the binary for the runtime it lands on.

On Turbopack, drop any turbopack.rules entry mapping *.wasm to type: "wasm". That rule makes Turbopack instantiate the binary and look for wasm-bindgen glue the package does not ship.

@takumi-rs/wasm and takumi-pdf export wasm-url too.

Node.js Issues

Cannot find native binding

@takumi-rs/core loads a platform-specific native package. This error means the package for the current platform is missing.

Hoist the native package

If you are using a package manager with virtual store such as pnpm or yarn, allow it to hoist the native binary. The following examples are for pnpm; after updating the configuration, re-run pnpm i.

publicHoistPattern:
  - "@takumi-rs/core-*"

With pnpm versions earlier than 10.5.0, add the equivalent setting to .npmrc instead:

public-hoist-pattern[]=@takumi-rs/core-*

For other package managers, refer to their docs for hoist config instructions.

Install the native package for your deploy target

Package managers only install the native package matching the machine that runs the install. Installing on one platform and deploying to another (for example installing on macOS and deploying to a Linux server) leaves the target's native package missing.

Install the package for the deploy target explicitly:

npm install @takumi-rs/core-linux-x64-gnu

Pick the package matching the target platform:

TypeError: fetch failed

Node.js fetch (via undici) can drop the socket while loading a remote img URL (#349). Pass the image as a base64 data URL so Takumi skips the fetch.