CanvasKit WASM

Common errors

• Module not found: Error: Can't resolve 'fs' in '.../node_modules/canvaskit-wasm/bin/canvaskit.js'

  cause Webpack attempts to bundle a Node.js-specific `fs` module usage when targeting a browser environment, as `canvaskit.js` might have conditional imports.
  fix In your Webpack configuration, add `node: { fs: 'empty' }` to the configuration object to tell Webpack to ignore the `fs` module in browser builds.

• Failed to load WebAssembly module: CompileError: WebAssembly.instantiate(): expected magic word 00 61 73 6d, found ...

  cause The browser or Node.js environment failed to load or compile the `canvaskit.wasm` file, often because `locateFile` provided an incorrect path, or the file was not served correctly.
  fix Verify that the path provided by the `locateFile` function in `CanvasKitInit` accurately points to the `canvaskit.wasm` file. Ensure the `.wasm` file is correctly placed in your deployment, has correct permissions, and is being served with the `application/wasm` MIME type.

Warnings

• gotcha The `locateFile` function passed to `CanvasKitInit` is critical. It determines how the browser or Node.js locates the `canvaskit.wasm` binary. Incorrect paths will lead to `Failed to load WebAssembly module` errors.
  Fix: Ensure the `locateFile` function correctly returns the URL or local path to `canvaskit.wasm` relative to where your application will be served or run. For bundlers, this often requires specific asset handling.
• breaking Webpack users (and similar bundlers) must configure asset handling to copy `canvaskit.wasm` to their build directory, as Webpack typically does not include raw WASM files by default.
  Fix: Use `CopyWebpackPlugin` in your Webpack configuration to copy `node_modules/canvaskit-wasm/bin/canvaskit.wasm` (and other bundle variants if used) to your output directory. Adjust `locateFile` accordingly.
• gotcha TypeScript users leveraging modern ESM imports need to enable `resolvePackageJsonExports` in their `tsconfig.json` to properly resolve `canvaskit-wasm`'s subpath exports (e.g., `canvaskit-wasm/full`).
  Fix: Add `"resolvePackageJsonExports": true` to your `compilerOptions` in `tsconfig.json`.
• gotcha The `CanvasKit` object (the main API) is not directly importable or available globally; it is provided as the resolved value of the Promise returned by `CanvasKitInit`.
  Fix: Always initialize CanvasKit using the asynchronous `CanvasKitInit()` function and wait for its Promise to resolve: `CanvasKitInit({...}).then((CanvasKit) => { /* use CanvasKit */ });`

Install

• npm install canvaskit-wasm npm
• yarn add canvaskit-wasm yarn
• pnpm add canvaskit-wasm pnpm

Imports

• InitCanvasKit
  wrong:

  import { InitCanvasKit } from 'canvaskit-wasm';

  correct:

  import InitCanvasKit from 'canvaskit-wasm';

  This imports the default bundle's initialization function. It is a default export, not a named one. This function returns a Promise that resolves to the main CanvasKit API object.
• InitCanvasKit (full bundle)
  wrong:

  import { InitCanvasKit } from 'canvaskit-wasm/full';

  correct:

  import InitCanvasKit from 'canvaskit-wasm/full';

  Imports the 'full' bundle which includes Skottie and other extended functionalities. For CommonJS, use `require('canvaskit-wasm/bin/full/canvaskit.js')`.
• CanvasKit (resolved object)
  wrong:

  import { CanvasKit } from 'canvaskit-wasm';

  correct:

  CanvasKitInit({ /* ... */ }).then((CanvasKit) => { /* use CanvasKit */ });

  The primary CanvasKit API object is obtained asynchronously after `InitCanvasKit` has loaded the WASM module and its assets. It is not directly importable.
• InitCanvasKit (CommonJS)
  wrong:

  const InitCanvasKit = require('canvaskit-wasm');

  correct:

  const InitCanvasKit = require('canvaskit-wasm/bin/canvaskit.js');

  When using CommonJS (e.g., in Node.js or Webpack), specify the direct path to the JavaScript wrapper for the WASM module. The root package export is often for ESM.

Quickstart

Initializes CanvasKit from a CDN, creates a canvas surface, draws a red rectangle, and flushes the drawing to an HTML canvas element.

import InitCanvasKit from 'canvaskit-wasm';

async function setupCanvasKit() {
  // Ensure an HTML canvas element with id 'my-canvas' exists in your page.
  // Example HTML: <canvas id="my-canvas" width="200" height="200"></canvas>
  const CanvasKit = await InitCanvasKit({
    // `locateFile` tells CanvasKit where to find its .wasm file.
    // Using unpkg.com for a quick CDN example.
    locateFile: (file: string) => `https://unpkg.com/canvaskit-wasm@0.41.1/bin/${file}`
  });

  if (!CanvasKit) {
    console.error('Failed to initialize CanvasKit.');
    return;
  }

  // Create a SkSurface attached to the HTML canvas element.
  const surface = CanvasKit.MakeSWCanvasSurface('my-canvas');
  if (!surface) {
    console.error('Could not create SkSurface');
    // Handle error or fallback
    return;
  }
  
  const canvas = surface.getCanvas();
  const paint = new CanvasKit.SkPaint();
  paint.setColor(CanvasKit.RED);
  paint.setStyle(CanvasKit.PaintStyle.Stroke);
  paint.setStrokeWidth(5);
  canvas.drawRect(CanvasKit.SkRect.MakeXYWH(10, 10, 100, 100), paint);
  
  // Flush the SkSurface to render content to the HTML canvas.
  surface.flush();

  // Clean up Skia objects when no longer needed to prevent memory leaks.
  paint.delete();
  surface.delete();
  // Note: CanvasKit itself should only be initialized once.
}

// Execute the setup function.
setupCanvasKit();