Quickstart

Fast paths into PanelWave — validate a manifest with the CLI, embed the player in an Angular app, create your first work in the CMS, or let an AI assistant build it with you.

Pick the path that matches what you want to do. Each one takes a few minutes and links into the deeper documentation for that layer.

Use @panelwave/cli to check a manifest against the official schema. This is the fastest way to get hands-on with the format.

Install the CLI

Install the CLI from npm (CLI 1.2.0 bundles the current format schema, 1.7.0):

npm install -g @panelwave/cli

Or run it without installing: npx @panelwave/cli validate ./panelwave.json. Details: CLI reference.

Create a minimal manifest

Save this as panelwave.json. It is the smallest useful work: two panels connected by one edge.

{
  "panelwave": {
    "version": "1.0.0",
    "schema": "https://panelwave.org/schema/1.0/panelwave.schema.json"
  },
  "meta": {
    "id": "my-first-work",
    "title": { "en-US": "My First Work" },
    "locales": ["en-US"],
    "default_locale": "en-US"
  },
  "assets": {
    "catalog": [
      {
        "id": "img-p1",
        "category": "image",
        "variants": [
          { "src": "https://picsum.photos/id/101/1280/720", "w": 1280, "h": 720, "mime": "image/jpeg" }
        ]
      },
      {
        "id": "img-p2",
        "category": "image",
        "variants": [
          { "src": "https://picsum.photos/id/102/1280/720", "w": 1280, "h": 720, "mime": "image/jpeg" }
        ]
      }
    ]
  },
  "chapters": [
    {
      "id": "ch-1",
      "panels": {
        "p1": { "layers": [{ "kind": "image", "id": "ly-1", "assetId": "img-p1", "z": 0 }] },
        "p2": { "layers": [{ "kind": "image", "id": "ly-2", "assetId": "img-p2", "z": 0 }] }
      },
      "graph": {
        "entry": "p1",
        "edges": [{ "from": "p1", "to": "p2", "transition": { "type": "fade", "durationMs": 300 } }]
      }
    }
  ]
}

Validate it

panelwave validate ./panelwave.json

Add --strict to fail on warnings, or --json for machine-readable output. See CLI reference.

Break it on purpose

Delete the meta.default_locale line and validate again to see how errors are reported. The validation page explains error output and common mistakes.

Explore the format

Read the manifest structure reference, then drill into chapters and pages, the graph, and panels.

Render a manifest in your own Angular application with @panelwave/player.

Install the library

The player runs in Angular 20 apps (21 and 22 from player 1.2.0) and is published on npm:

npm install @panelwave/player @ngx-translate/core

Then add provideHttpClient(), an ngx-translate loader, the package's UI translation files and the balloon font CSS to your app — Installation has the copy-paste snippets.

Add a manifest to your app

Place a panelwave.json (for example the one from the CLI tab, or one of the demo works) under src/assets/my-story/.

Drop in the player component

The embeddable component is PlayerShellComponent (selector pw-player-shell). Point it at the manifest:

import { Component } from '@angular/core';
import { PlayerShellComponent } from '@panelwave/player';

@Component({
  selector: 'app-root',
  imports: [PlayerShellComponent],
  template: `<pw-player-shell manifestUrl="assets/my-story/panelwave.json" [showToolbar]="true" />`,
  styles: `:host { display: block; height: 100dvh; }`,
})
export class AppComponent {}

You can also fetch the JSON yourself and bind the parsed object via [manifest] — see Quickstart: Embed.

Configure the player

Behavior is controlled through individual inputs on pw-player-shell:

<pw-player-shell
  manifestUrl="assets/my-story/panelwave.json"
  locale="de-DE"
  [showToolbar]="true"
  [entitlementSnapshot]="snapshot"
  (panelChange)="onPanel($event)">
</pw-player-shell>

All inputs and defaults: Configuration. To try a manifest before writing any code, open it in the live demo.

Go deeper

Wire up events and inputs on Inputs & outputs, save reader progress with Saving progress, and follow the full embedding guide.

Next steps

AI assistants

What assistants can do in PanelWave and how you stay in control.

Core concepts

How the schema, player, and CMS fit together.

Graph navigation

Entries, edges, conditions, and branching.

Sample manifests

Complete example works, from minimal to branching and video.

Was this page helpful?