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 }).ready().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.3.0/bin/canvaskit.js"></script>
20 CanvasKitInit({
21 locateFile: (file) => 'https://unpkg.com/canvaskit-wasm@0.3.0/bin/'+file,
22 }).ready().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 }).ready().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().ready().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 API.
74
75More detailed docs will be coming soon.
76
77## Drop-in Canvas2D replacement
78For environments where an HTML canvas is not available (e.g. Node, headless servers),
79CanvasKit has an optional API (included by default) that mirrors the HTML canvas.
80
81 let skcanvas = CanvasKit.MakeCanvas(600, 600);
82
83 let ctx = skcanvas.getContext('2d');
84 let rgradient = ctx.createRadialGradient(200, 300, 10, 100, 100, 300);
85
86 // Add three color stops
87 rgradient.addColorStop(0, 'red');
88 rgradient.addColorStop(0.7, 'white');
89 rgradient.addColorStop(1, 'blue');
90
91 ctx.fillStyle = rgradient;
92 ctx.globalAlpha = 0.7;
93 ctx.fillRect(0, 0, 600, 600);
94
95 let imgData = skcanvas.toDataURL();
96 // imgData is now a base64 encoded image.
97
98See more examples in `example.html` and `node.example.js`.
99
100
101# Filing bugs
102
103Please file bugs at [skbug.com](skbug.com).
104It may be convenient to use [our online fiddle](jsfiddle.skia.org/canvaskit) to demonstrate any issues encountered.
105
106See CONTRIBUTING.md for more information on sending pull requests.
