Conversation
…sing one over the other
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Rive web runtime documentation to better explain the tradeoffs between the WebGL2 (Rive Renderer) and Canvas2D packages, and to make it easier for readers to choose (and switch between) the right package for their needs.
Changes:
- Expanded and clarified the WebGL2 vs Canvas2D guidance, including context limits and performance considerations.
- Updated links/anchors and improved messaging around
@rive-app/canvas-lite. - Refreshed related runtime references (feature support blurbs and a docs variable version bump).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| runtimes/web/web-js.mdx | Adds clearer package-selection guidance and updates canvas-lite references; includes minor example/code cleanup edits. |
| runtimes/web/faq.mdx | Updates canvas-lite recommendation criteria and fixes the link target to the correct section. |
| runtimes/web/canvas-vs-webgl.mdx | Major rewrite: adds a comparison table and detailed caveats (feathering, fill rules, context limits, performance). |
| runtimes/getting-started.mdx | Updates the link text to “Canvas vs WebGL2” for consistency with the page title. |
| feature-support.mdx | Replaces empty React web runtime entries with descriptive guidance and updates legacy deprecation wording. |
| docs.json | Bumps the versionWebGL2 docs variable. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| extension in Chrome improves rendering performance. Without it, Rive falls | ||
| back to an MSAA-based WebGL2 path. We are actively working with browser | ||
| vendors to make this enabled by default. | ||
| When using WebGL2, we recommend your graphics avoid advanced blend modes to keep performance consistent across devices.If your file uses blend modes, measure on your target devices. See [Performance](#performance) for more. |
|
|
||
| In practice: | ||
|
|
||
| - Blend modes on mobile are the case where `@rive-app/canvas` can be meaningfully performant to render. If your file leans on them and does not use Vector Feathering, it is worth comparing the two. |
|
|
||
| ```javascript | ||
| const riveInstance = new Rive({...)); | ||
| const riveInstance = new Rive({...}); |
| Rive's web runtime comes in two main packages: [`@rive-app/webgl2`](https://www.npmjs.com/package/@rive-app/webgl2) and [`@rive-app/canvas`](https://www.npmjs.com/package/@rive-app/canvas). They expose the same API. The only difference is how they draw. | ||
|
|
||
| For web, start by choosing one of these two packages: | ||
| **For most use cases, use`@rive-app/webgl2`.** It draws with the Rive Renderer, the same renderer as the Rive Editor, so everything you can author in Rive renders the way you designed it. `@rive-app/canvas` uses the browser's own 2D renderer, which brings its own advantages (particularly for performance), but it does not yet support every Editor feature. |
lancesnider
reviewed
Aug 20, 2026
| | Graphics per page | 🟡 Bound by the browser's WebGL context limit (see [WebGL Context Limits](#webgl-context-limits)) | ✅ No practical limit | | ||
|
|
||
| Use `@rive-app/webgl2` if you want the best rendering quality and performance in most cases. | ||
| ## `@rive-app/webgl2` |
Collaborator
There was a problem hiding this comment.
Seems like this whole section is already covered above, no? If so, I'm okay to nuke it.
|
|
||
| ## `@rive-app/canvas` | ||
|
|
||
| ```bash |
Collaborator
There was a problem hiding this comment.
This section also seems like duplicate content.
|
|
||
| ## Performance | ||
|
|
||
| The Rive Renderer gets its speed from GPU features that native graphics APIs like Metal and Vulkan expose today. For Rive on the web, those capabilities come from a WebGL extension, [`WEBGL_shader_pixel_local_storage`](https://www.khronos.org/registry/webgl/extensions/WEBGL_shader_pixel_local_storage/), which is still in draft. Rive is involved in the effort to standardize it across browsers, and we will update this guidance as support lands. |
Collaborator
There was a problem hiding this comment.
I almost read this as the webgl2 package not being fully supported. I think I'd switch the order.
- Webgl2 uses MSAA
- There's a draft that exposes metal and vulkan, which will make it faster
- Blend modes are where you will see the performance drop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Elaborating more on the webgl2 vs canvas documentation and when to use which runtime package