xref: /aosp_15_r20/external/skia/modules/canvaskit/npm_build/README.md (revision c8dee2aa9b3f27cf6c858bd81872bdeb2c07ed17) 
1A WASM version of Skia's Canvas API.
2
3See https://skia.org/user/modules/canvaskit for more background information.
4
5# Getting Started
6
7## Browser
8
9To use the library, run `npm install canvaskit-wasm` and then simply include it:
10
11```html
12<script src="/node_modules/canvaskit-wasm/bin/canvaskit.js"></script>
13```
14```javascript
15CanvasKitInit({
16    locateFile: (file) => '/node_modules/canvaskit-wasm/bin/'+file,
17}).then((CanvasKit) => {
18    // Code goes here using CanvasKit
19});
20```
21
22As with all npm packages, there's a freely available CDN via unpkg.com:
23
24```html
25<script src="https://unpkg.com/canvaskit-wasm@latest/bin/canvaskit.js"></script>
26```
27```javascript
28CanvasKitInit({
29    locateFile: (file) => 'https://unpkg.com/canvaskit-wasm@latest/bin/'+file,
30}).then((CanvasKit) => {
31    // Code goes here using CanvasKit
32});
33```
34
35## Node
36To use CanvasKit in Node, it's similar to the browser:
37
38```javascript
39const CanvasKitInit = require('canvaskit-wasm/bin/canvaskit.js');
40CanvasKitInit({
41    locateFile: (file) => __dirname + '/bin/'+file,
42}).then((CanvasKit) => {
43    // Code goes here using CanvasKit
44});
45```
46
47## WebPack
48
49WebPack's support for WASM is still somewhat experimental, but CanvasKit can be
50used with a few configuration changes.
51
52In the JS code, use require():
53
54```javascript
55const CanvasKitInit = require('canvaskit-wasm/bin/canvaskit.js')
56CanvasKitInit().then((CanvasKit) => {
57    // Code goes here using CanvasKit
58});
59```
60
61Since WebPack does not expose the entire `/node_modules/` directory, but instead
62packages only the needed pieces, we have to copy canvaskit.wasm into the build directory.
63One such solution is to use [CopyWebpackPlugin](https://github.com/webpack-contrib/copy-webpack-plugin).
64For example, add the following plugin:
65
66```javascript
67config.plugins.push(
68    new CopyWebpackPlugin([
69        { from: 'node_modules/canvaskit-wasm/bin/canvaskit.wasm' }
70    ])
71);
72```
73
74If webpack gives an error similar to:
75
76```warn
77ERROR in ./node_modules/canvaskit-wasm/bin/canvaskit.js
78Module not found: Error: Can't resolve 'fs' in '...'
79```
80
81Then, add the following configuration change to the node section of the config:
82
83```javascript
84config.node = {
85    fs: 'empty'
86};
87```
88
89
90# Different canvaskit bundles
91
92`canvaskit-wasm` includes 3 types of bundles:
93
94* default `./bin/canvaskit.js` - Basic canvaskit functionality
95
96
97```javascript
98const InitCanvasKit = require('canvaskit-wasm/bin/canvaskit');
99```
100
101* full `./bin/full/canvaskit.js` - includes [Skottie](https://skia.org/docs/user/modules/skottie/) and other libraries
102
103```javascript
104const InitCanvasKit = require('canvaskit-wasm/bin/full/canvaskit');
105```
106
107* profiling `./bin/profiling/canvaskit.js` - the same as `full` but contains full names of wasm functions called internally
108
109```javascript
110const InitCanvasKit = require('canvaskit-wasm/bin/profiling/canvaskit');
111```
112
113# ES6 import and node entrypoints
114
115This package also exposes [entrypoints](https://nodejs.org/api/packages.html#package-entry-points)
116
117```javascript
118import InitCanvasKit from 'canvaskit-wasm'; // default
119```
120
121```javascript
122import InitCanvasKit from 'canvaskit-wasm/full';
123```
124
125```javascript
126import InitCanvasKit from 'canvaskit-wasm/profiling';
127```
128
129If you use [typescript](https://www.typescriptlang.org/)
130
131you need to enable [resolvePackageJsonExports](https://www.typescriptlang.org/tsconfig#resolvePackageJsonExports) in your `tsconfig.json`
132
133```json
134{
135    "compilerOptions": {
136        "resolvePackageJsonExports": true
137    }
138}
139```
140
141# Using the CanvasKit API
142
143See `example.html` and `node.example.js` for demos of how to use the core API.
144
145See `extra.html` for some optional add-ins like an animation player (Skottie).
146
147See `types/index.d.ts` for a typescript definition file that contains all the
148APIs and some documentation about them.
149
150## Drop-in Canvas2D replacement
151For environments where an HTML canvas is not available (e.g. Node, headless servers),
152CanvasKit has an optional API (included by default) that mostly mirrors the [CanvasRenderingContext2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D).
153
154```javascript
155const skcanvas = CanvasKit.MakeCanvas(600, 600);
156
157const ctx = skcanvas.getContext('2d');
158const rgradient = ctx.createRadialGradient(200, 300, 10, 100, 100, 300);
159
160// Add three color stops
161rgradient.addColorStop(0, 'red');
162rgradient.addColorStop(0.7, 'white');
163rgradient.addColorStop(1, 'blue');
164
165ctx.fillStyle = rgradient;
166ctx.globalAlpha = 0.7;
167ctx.fillRect(0, 0, 600, 600);
168
169const imgData = skcanvas.toDataURL();
170// imgData is now a base64 encoded image.
171```
172
173See more examples in `example.html` and `node.example.js`.
174
175### Known issues with Canvas2D Emulation layer
176 - measureText returns width only and does no shaping. It is only sort of valid with ASCII letters.
177 - textAlign is not supported.
178 - textBaseAlign is not supported.
179 - fillText does not support the width parameter.
180
181# Filing bugs
182
183Please file bugs at [https://skbug.com](skbug.com).
184It may be convenient to use [our online fiddle](https://jsfiddle.skia.org/canvaskit) to demonstrate any issues encountered.
185
186See CONTRIBUTING.md for more information on sending pull requests.
187
188# Types and Documentation
189
190There are Typescript types and associated API docs in [types/](./types/).
191