README.md
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
8To use the library, run `npm install canvaskit-wasm` and then simply include it:
9
10 <script src="/node_modules/canvaskit-wasm/bin/canvaskit.js"></script>
11 CanvasKitInit({
12 locateFile: (file) => '/node_modules/canvaskit-wasm/bin/'+file,
13 }).then((CanvasKit) => {
14 // Code goes here using CanvasKit
15 });
16
17As with all npm packages, there's a freely available CDN via unpkg.com:
18
19 <script src="https://unpkg.com/canvaskit-wasm@0.18.1/bin/canvaskit.js"></script>
20 CanvasKitInit({
21 locateFile: (file) => 'https://unpkg.com/canvaskit-wasm@0.18.1/bin/'+file,
22 }).then(...)
23
24## Node
25To use CanvasKit in Node, it's similar to the browser:
26
27 const CanvasKitInit = require('/node_modules/canvaskit-wasm/bin/canvaskit.js');
28 CanvasKitInit({
29 locateFile: (file) => __dirname + '/bin/'+file,
30 }).then((CanvasKit) => {
31 // Code goes here using CanvasKit
32 });
33
34With node, you also need to supply the `--expose-wasm` flag.
35
36## WebPack
37
38WebPack's support for WASM is still somewhat experimental, but CanvasKit can be
39used with a few configuration changes.
40
41In the JS code, use require():
42
43 const CanvasKitInit = require('canvaskit-wasm/bin/canvaskit.js')
44 CanvasKitInit().then((CanvasKit) => {
45 // Code goes here using CanvasKit
46 });
47
48Since WebPack does not expose the entire `/node_modules/` directory, but instead
49packages only the needed pieces, we have to copy canvaskit.wasm into the build directory.
50One such solution is to use [CopyWebpackPlugin](https://github.com/webpack-contrib/copy-webpack-plugin).
51For example, add the following plugin:
52
53 config.plugins.push(
54 new CopyWebpackPlugin([
55 { from: 'node_modules/canvaskit-wasm/bin/canvaskit.wasm' }
56 ])
57 );
58
59If webpack gives an error similar to:
60
61 ERROR in ./node_modules/canvaskit-wasm/bin/canvaskit.js
62 Module not found: Error: Can't resolve 'fs' in '...'
63
64Then, add the following configuration change to the node section of the config:
65
66 config.node = {
67 fs: 'empty'
68 };
69
70
71# Using the CanvasKit API
72
73See `example.html` and `node.example.js` for demos of how to use the core API.
74
75See `extra.html` for some optional add-ins like an animation player (Skottie).
76
77See `types/index.d.ts` for a typescript definition file that contains all the
78APIs and some documentation about them.
79
80## Drop-in Canvas2D replacement
81For environments where an HTML canvas is not available (e.g. Node, headless servers),
82CanvasKit has an optional API (included by default) that mostly mirrors the HTML canvas.
83
84 let skcanvas = CanvasKit.MakeCanvas(600, 600);
85
86 let ctx = skcanvas.getContext('2d');
87 let rgradient = ctx.createRadialGradient(200, 300, 10, 100, 100, 300);
88
89 // Add three color stops
90 rgradient.addColorStop(0, 'red');
91 rgradient.addColorStop(0.7, 'white');
92 rgradient.addColorStop(1, 'blue');
93
94 ctx.fillStyle = rgradient;
95 ctx.globalAlpha = 0.7;
96 ctx.fillRect(0, 0, 600, 600);
97
98 let imgData = skcanvas.toDataURL();
99 // imgData is now a base64 encoded image.
100
101See more examples in `example.html` and `node.example.js`.
102
103### Known issues with Canvas2D Emulation layer
104 - measureText returns width only and does no shaping. It is only sort of valid with ASCII letters.
105 - textAlign is not supported.
106 - textBaseAlign is not supported.
107 - fillText does not support the width parameter.
108
109# Filing bugs
110
111Please file bugs at [skbug.com](skbug.com).
112It may be convenient to use [our online fiddle](jsfiddle.skia.org/canvaskit) to demonstrate any issues encountered.
113
114See CONTRIBUTING.md for more information on sending pull requests.
115
116# Types and Documentation
117
118There are Typescript types and associated API docs in types/.
119