Viji SDK

Development environment for Viji scenes. Write scene code in your IDE, preview it live in the browser with real-time parameter controls, audio analysis, video input, and interaction handling — the same execution environment as the Viji platform. Supports Canvas 2D, WebGL, P5.js, and GLSL shaders.

Installation

Requires Node.js v18 or later.

npm install -g @viji-dev/sdk

To update to the latest version:

npm update -g @viji-dev/sdk

Quick Start

# Create a workspace folder (any name works)
mkdir my-viji-scenes && cd my-viji-scenes

# Create your first scene (native renderer is the default)
viji create my-scene

# Start the development server
viji dev

Open http://localhost:8454 in your browser to see the SDK UI. Edit scenes/my-scene/main.js in your IDE — changes appear in real time. Both JS and TS scenes get full autocompletion for the Viji API.

CLI Commands

viji create <scene-name> [--renderer <type>] [--ts]

Create a new scene in the scenes/ folder.

• viji create my-scene — native renderer (Canvas 2D / WebGL), the default
• viji create my-scene --renderer p5 — P5.js renderer
• viji create my-scene --renderer shader — GLSL fragment shader
• viji create my-scene --ts — TypeScript scene file (works with any renderer)

On the first run, the SDK sets up the workspace: it writes package.json, .gitignore, a workspace README.md, and AGENTS.md (a guide for AI coding assistants), and installs type definitions locally for IDE autocompletion. Each scene folder gets its own tsconfig.json + global.d.ts — all auto-generated, no manual setup needed. Each scene is isolated so they don't interfere with each other in your editor.

viji dev [--port <port>] [--host <host>] [--no-open]

Start the development server with live reload.

| Option | Default | Description | |--------|---------|-------------| | --port | 8454 | Server port | | --host | localhost | Server host | | --no-open | | Do not open the browser automatically |

The server watches the scenes/ directory for changes and pushes updates to the browser UI in real time via WebSocket.

On startup, viji dev checks whether the workspace's type definitions match the SDK version. If you've updated the SDK and the local types are out of date, they are updated automatically — no manual steps needed. This keeps IDE autocompletion in sync with the runtime.

viji build <scene-name> [-o <file>] [--copy]

Bundle a scene into a single file for deployment to the Viji platform.

viji build my-scene                       # outputs dist/my-scene.js
viji build my-scene --copy                # also copies the bundle to the clipboard
viji build my-scene -o bundle/output.js   # custom output path

Multi-file scenes (with local imports) are resolved and concatenated automatically. Publish by pasting the bundle into the Viji platform editor — --copy puts it on your clipboard, ready to paste.

viji docs [page | search <query>]

Browse the scene documentation in the terminal — offline, always matching your installed version.

viji docs                            # navigation tree of all pages
viji docs native-quickstart          # print one page as markdown
viji docs search beat detection      # keyword search

Writing Scenes

The SDK includes built-in documentation for the Viji scene API, parameter system, renderers, audio/video analysis, and interaction handling.

Start the development server and open the docs panel from the toolbar, or navigate directly to http://localhost:8454/docs.

The documentation includes live code playgrounds where you can experiment with the API directly in the browser.

Working with an AI coding assistant? The scaffolded AGENTS.md in your workspace tells it where to find the API types and docs — most assistants pick it up automatically.

Project Structure

After creating a few scenes, your workspace looks like this:

my-viji-scenes/
├── scenes/
│   ├── my-scene/
│   │   ├── main.js
│   │   ├── global.d.ts        # type definitions (auto-generated)
│   │   └── tsconfig.json      # IDE config (auto-generated)
│   ├── shader-demo/
│   │   └── main.glsl
│   └── p5-sketch/
│       ├── main.js
│       ├── global.d.ts
│       └── tsconfig.json
├── node_modules/              # type packages (auto-generated)
├── package.json               # workspace manifest (auto-generated)
├── .gitignore                 # auto-generated
├── README.md                  # workspace guide (auto-generated, yours to edit)
└── AGENTS.md                  # guide for AI coding assistants (auto-generated)

License

Copyright (c) 2025 Artem Verkhovskiy and Dmitry Manoilenko. All rights reserved — see the LICENSE file for details.