Getting Started

You can be rendering 3D in the browser inside a minute — no installs and no build step required. Load PlayCanvas Web Components straight from a CDN, or install the npm package if you are integrating them into an existing project.

Scaffold a project

For a Vite and TypeScript project, use create-playcanvas and choose the Web Components format:

npm create playcanvas@latest my-app -- -f web-components

The generated project includes one of 12 runnable starters and PlayCanvas Skills for compatible AI coding agents. Use the CDN or npm setup below when integrating Web Components manually.

Installation

You can load the library in one of two ways. If you're not sure which to pick, start with the CDN — you can switch to npm later without changing any of your markup:

• CDN (no install) — nothing to download and no tooling required. The fastest way to get started, and fine for production too as long as you pin to specific versions.
• npm — the right choice when your project already has a package.json, a dev server or a bundler. The engine and components are versioned alongside the rest of your dependencies and served from your own infrastructure.

Unless a bundler builds your pages (see the npm tab), your HTML file needs an import map, because the Web Components need to be able to find the PlayCanvas Engine (which is an external dependency). The map also lists @playcanvas/web-components itself — the tags don't need that entry, but it means any JavaScript you write later can import the library's API (introduced in Programmatic Access).

CDN (no install)

Load both the engine and the components from a CDN such as jsDelivr, using pwc.min.mjs — the minified build, under a third 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>

You can then import the Web Components 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). Choose a pair that works together: each release of @playcanvas/web-components supports a range of engine versions, declared as the playcanvas peer dependency in its package.json.

The library's URL appears twice, in the import map and in the <script> tag, so pin both to the same version. If the two URLs differ, the browser treats them as two different modules: as soon as your own code imports the library through the map, a second copy loads and fails to register the tags, which the first copy already defined.

See the release notes for the latest stable versions: PlayCanvas Engine releases and Web Components releases.

npm

Make sure you have Node.js 18 or later installed. 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

How you load it from there depends on whether a bundler builds your pages.

With a bundler such as Vite, webpack or Rollup, import the package once from your JavaScript entry point. The bundler resolves playcanvas for you, so you need no import map and no extra <script> tag:

main.js

import '@playcanvas/web-components';

Without a bundler, when your files are served as they are, point an import map at the installed packages and load the library from the same path:

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

These paths assume your site is served from the project root, so that /node_modules/... resolves.

Your First Page

Here is a complete page that renders a lit sphere — the "hello, world" of 3D. It uses the CDN setup, so there is nothing to install:

index.html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <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;
            }
            pc-app {
                width: 100%;
                height: 100vh;  /* fallback for browsers without dynamic viewport units */
                height: 100dvh;
            }
        </style>
    </head>
    <body>
        <pc-app>
            <pc-scene>
                <pc-entity name="camera" position="0 0 3">
                    <pc-camera></pc-camera>
                </pc-entity>
                <pc-entity name="light" rotation="45 45 0">
                    <pc-light></pc-light>
                </pc-entity>
                <pc-entity name="ball">
                    <pc-render type="sphere"></pc-render>
                </pc-entity>
            </pc-scene>
        </pc-app>
    </body>
</html>

One rule in the <style> block deserves a mention: <pc-app> is sized like a <video> element — a block-level box that your CSS controls, just 300×150 pixels by default. The pc-app rule stretches it to fill the viewport; size it however you like to embed the scene in a normal page layout instead. See Sizing for the details.

Save this as index.html and open it in your browser. Everything loads from the CDN, so you can open the file straight from disk, with no web server. You should see a lit sphere, just like the live preview below, which runs the same scene. Edit its markup and the preview re-runs:

Live Example

<pc-app>
    <pc-scene>
        <pc-entity name="camera" position="0 0 3">
            <pc-camera></pc-camera>
        </pc-entity>
        <pc-entity name="light" rotation="45 45 0">
            <pc-light></pc-light>
        </pc-entity>
        <pc-entity name="ball">
            <pc-render type="sphere"></pc-render>
        </pc-entity>
    </pc-scene>
</pc-app>

note

Installed from npm instead? Swap the import map and <script> tag for the /node_modules/... versions in the npm tab above or, with a bundler, delete both and import the package from your entry script.

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. Editors read these files from node_modules, so install the npm package to get them, even if your page loads the library from the CDN.

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.

Next Steps

• Continue to Building a Scene to build up a scene element by element — and go further, with materials, shadows and a ground plane.
• Skim the Tag Reference to see every element you can declare.
• Browse the Examples to see what the components can do.