Skip to main content

Getting Started

Before you begin, make sure you have Node.js 18 or later installed.

Installing from NPM​

PlayCanvas Web Components is available as a package on NPM. You can install it (and the PlayCanvas Engine) as follows:

npm install playcanvas @playcanvas/web-components

Next, in your HTML file, you will need an import map because the Web Components need to be able to find the PlayCanvas Engine (which is an external dependency). Mapping @playcanvas/web-components as well lets your own module scripts import the library's JavaScript API (such as whenReady):

<script type="importmap">
    {
        "imports": {
            "playcanvas": "/node_modules/playcanvas/build/playcanvas.mjs",
            "@playcanvas/web-components": "/node_modules/@playcanvas/web-components/dist/pwc.mjs"
        }
    }
</script>

You can then import the Web Components as follows:

<script type="module" src="/node_modules/@playcanvas/web-components/dist/pwc.mjs"></script>

You can now incorporate any of the PlayCanvas Web Components elements into your HTML!

Using a CDN​

Instead of loading the library from a local package, you can instead opt to load it from a CDN (such as jsDelivr). In this case, you would update the import map to use pwc.min.mjs — the minified build, less than half the size of pwc.mjs:

<script type="importmap">
    {
        "imports": {
            "playcanvas": "https://cdn.jsdelivr.net/npm/playcanvas@latest/build/playcanvas.mjs",
            "@playcanvas/web-components": "https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"
        }
    }
</script>

And the components would now be imported as follows:

<script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"></script>
Versioning

The snippets above use @latest for convenience. For production deployments, pin to a specific version to ensure deterministic builds (for example: playcanvas@2.x.y and @playcanvas/web-components@x.y.z). See the release notes for the latest stable versions: PlayCanvas Engine releases and Web Components releases.

Boilerplate HTML​

Let's see how this looks in a minimal boilerplate HTML file:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
        <title>My PlayCanvas Web Components App</title>
        <script type="importmap">
            {
                "imports": {
                    "playcanvas": "https://cdn.jsdelivr.net/npm/playcanvas@latest/build/playcanvas.mjs",
                    "@playcanvas/web-components": "https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"
                }
            }
        </script>
        <script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@latest/dist/pwc.min.mjs"></script>
        <style>
            body {
                margin: 0;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <!-- Your PlayCanvas Web Components elements go here -->
    </body>
</html>

You are now ready to start using the PlayCanvas Web Components to build a 3D scene!

Editor Support​

The package ships a Custom Elements Manifest, which editors use to offer tag and attribute completions, valid attribute values and hover documentation when authoring HTML.

VS Code — add the following to your workspace .vscode/settings.json:

{
  "html.customData": [
    "./node_modules/@playcanvas/web-components/dist/vscode.html-custom-data.json"
  ]
}

JetBrains IDEs (WebStorm, IntelliJ IDEA) — no setup required. The IDE discovers the bundled web-types.json automatically.

Other tooling — the manifest itself is at @playcanvas/web-components/dist/custom-elements.json and is declared in the package's customElements field, which is how tools such as lit-analyzer and Storybook locate it.