{"id":16309,"library":"canvaskit-wasm","title":"CanvasKit WASM","description":"The `canvaskit-wasm` package provides a WebAssembly (WASM) implementation of Skia's 2D graphics API, enabling high-performance rendering capabilities across diverse JavaScript environments including browsers, Node.js, and WebWorkers. Currently at version 0.41.1, its release cycle generally aligns with updates from the upstream Skia project, which is known for its robust and feature-rich graphics engine. A key differentiator is its ability to offer a comprehensive, portable alternative to native Canvas2D APIs, particularly for complex vectorial graphics, text rendering, and advanced animations like Lottie/Skottie. The package offers several bundles – a default minimal version, a 'full' version including Skottie and other advanced features, and a 'profiling' version – allowing developers to optimize for bundle size and debugging needs. This flexibility, combined with its C++ backend performance via WASM, positions it as a powerful tool for demanding visual applications.","status":"active","version":"0.41.1","language":"javascript","source_language":"en","source_url":"https://github.com/google/skia/tree/main/modules/canvaskit","tags":["javascript","typescript"],"install":[{"cmd":"npm install canvaskit-wasm","lang":"bash","label":"npm"},{"cmd":"yarn add canvaskit-wasm","lang":"bash","label":"yarn"},{"cmd":"pnpm add canvaskit-wasm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { InitCanvasKit } from 'canvaskit-wasm';","symbol":"InitCanvasKit","correct":"import InitCanvasKit from 'canvaskit-wasm';"},{"note":"Imports the 'full' bundle which includes Skottie and other extended functionalities. For CommonJS, use `require('canvaskit-wasm/bin/full/canvaskit.js')`.","wrong":"import { InitCanvasKit } from 'canvaskit-wasm/full';","symbol":"InitCanvasKit (full bundle)","correct":"import InitCanvasKit from 'canvaskit-wasm/full';"},{"note":"The primary CanvasKit API object is obtained asynchronously after `InitCanvasKit` has loaded the WASM module and its assets. It is not directly importable.","wrong":"import { CanvasKit } from 'canvaskit-wasm';","symbol":"CanvasKit (resolved object)","correct":"CanvasKitInit({ /* ... */ }).then((CanvasKit) => { /* use CanvasKit */ });"},{"note":"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.","wrong":"const InitCanvasKit = require('canvaskit-wasm');","symbol":"InitCanvasKit (CommonJS)","correct":"const InitCanvasKit = require('canvaskit-wasm/bin/canvaskit.js');"}],"quickstart":{"code":"import InitCanvasKit from 'canvaskit-wasm';\n\nasync function setupCanvasKit() {\n  // Ensure an HTML canvas element with id 'my-canvas' exists in your page.\n  // Example HTML: <canvas id=\"my-canvas\" width=\"200\" height=\"200\"></canvas>\n  const CanvasKit = await InitCanvasKit({\n    // `locateFile` tells CanvasKit where to find its .wasm file.\n    // Using unpkg.com for a quick CDN example.\n    locateFile: (file: string) => `https://unpkg.com/canvaskit-wasm@0.41.1/bin/${file}`\n  });\n\n  if (!CanvasKit) {\n    console.error('Failed to initialize CanvasKit.');\n    return;\n  }\n\n  // Create a SkSurface attached to the HTML canvas element.\n  const surface = CanvasKit.MakeSWCanvasSurface('my-canvas');\n  if (!surface) {\n    console.error('Could not create SkSurface');\n    // Handle error or fallback\n    return;\n  }\n  \n  const canvas = surface.getCanvas();\n  const paint = new CanvasKit.SkPaint();\n  paint.setColor(CanvasKit.RED);\n  paint.setStyle(CanvasKit.PaintStyle.Stroke);\n  paint.setStrokeWidth(5);\n  canvas.drawRect(CanvasKit.SkRect.MakeXYWH(10, 10, 100, 100), paint);\n  \n  // Flush the SkSurface to render content to the HTML canvas.\n  surface.flush();\n\n  // Clean up Skia objects when no longer needed to prevent memory leaks.\n  paint.delete();\n  surface.delete();\n  // Note: CanvasKit itself should only be initialized once.\n}\n\n// Execute the setup function.\nsetupCanvasKit();","lang":"typescript","description":"Initializes CanvasKit from a CDN, creates a canvas surface, draws a red rectangle, and flushes the drawing to an HTML canvas element."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Add `\"resolvePackageJsonExports\": true` to your `compilerOptions` in `tsconfig.json`.","message":"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`).","severity":"gotcha","affected_versions":">=0.30.0"},{"fix":"Always initialize CanvasKit using the asynchronous `CanvasKitInit()` function and wait for its Promise to resolve: `CanvasKitInit({...}).then((CanvasKit) => { /* use CanvasKit */ });`","message":"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`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"In your Webpack configuration, add `node: { fs: 'empty' }` to the configuration object to tell Webpack to ignore the `fs` module in browser builds.","cause":"Webpack attempts to bundle a Node.js-specific `fs` module usage when targeting a browser environment, as `canvaskit.js` might have conditional imports.","error":"Module not found: Error: Can't resolve 'fs' in '.../node_modules/canvaskit-wasm/bin/canvaskit.js'"},{"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.","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.","error":"Failed to load WebAssembly module: CompileError: WebAssembly.instantiate(): expected magic word 00 61 73 6d, found ..."}],"ecosystem":"npm"}