Getting Started

Your First Extension

Build, run, and hot-reload your first OXP extension in under five minutes.

This tutorial walks you through creating, running, and hot-reloading your very first OXP extension. By the end, you'll have a working extension running in VS Code with live reload.

Step 1: Scaffold the Project

bash
oxp create hello-world
cd hello-world

This creates a new directory with the hello-html template (the default). You'll see:

hello-world/
├── oxp.json           The extension manifest
├── ui/
│   └── index.html     Your extension's UI
└── README.md

Step 2: Examine the Manifest

Open oxp.json:

oxp.jsonjson
{
  "specVersion": "1",
  "id": "@yourname/hello-world",
  "publisher": "yourname",
  "version": "0.0.1",
  "displayName": "Hello World",
  "description": "Hello, OXP world.",
  "license": "MIT",
  "categories": ["other"],
  "engines": { "oxp": "^1.0.0" },
  "main": { "ui": "ui/index.html" },
  "ui": { "components": "oxp-ui-only", "preferredSurface": "panel" },
  "permissions": []
}

Key fields:

  • **id** — unique identifier in @publisher/slug format
  • **main.ui** — path to your HTML entry point
  • **permissions** — empty because this extension doesn't need any capabilities beyond rendering UI
  • **ui.components** — set to oxp-ui-only which means declarative mode (no executable code)

Step 3: Start the Dev Server

bash
oxp dev

You'll see output like:

╭───────────────────────────────────────────────────────────╮
│  oxp dev — DEV MODE (signature bypass, do not ship)       │
│  ws:    ws://localhost:7373/dev                            │
│  http:  http://localhost:7373/info                         │
│  root:  /path/to/hello-world                              │
╰───────────────────────────────────────────────────────────╯

The dev server watches your files, re-packs on every change, and pushes updates over WebSocket. Connected hosts hot-reload instantly.

Step 4: Open in the Extension Development Host

While oxp dev is running, a fresh Extension Development Host (EDH) window of your IDE has already opened automatically. You don't need to run any command, paste any URL, or change any setting.

In the EDH window:

  1. Click the OXP icon in the activity bar (or, on JetBrains, the OXP stripe button on the right tool window).
  2. The sidebar opens with your extension rendered natively.
  3. The status bar shows $(plug) OXP Dev — your live connection indicator.
  4. A "DEV: signature bypass" chip is painted in the sidebar header — this is expected in dev mode.

If anything goes wrong, open View → Output → OXP Dev Host (VS Code family) or the OXP Dev Host tool window (JetBrains) for live pack/reload logs.

See the Extension Development Host guide for the full reference: chrome, commands, output channel, hot-reload semantics, and error boundary.

Step 5: Make Changes

Edit ui/index.html. As soon as you save, the dev server re-packs and the EDH hot-reloads your extension — typically in 100–250 ms. No window reload. Form values and scroll positions in your sidebar survive the reload.

To end the session, press Ctrl+C in the terminal. The dev server stops and the EDH window closes itself.

Step 6: Choose a Template

OXP ships five templates for different use cases:

TemplateCommandDescription
hello-htmloxp create -t hello-html myextReact + TypeScript + esbuild (default)
hello-reactoxp create -t hello-react myextAlias for hello-html — React + TSX UI with esbuild bundling
hello-treeoxp create -t hello-tree myextDeclarative oxp-ui-v1 tree (no JS/HTML)
hello-codeoxp create -t hello-code myextTypeScript extension with logic
hello-rustoxp create -t hello-rust myextRust WASI component

For your first extension, hello-html / hello-react or hello-tree are the simplest starting points. Move to hello-rust when you need logic beyond declarative UI.

Step 7: Pack and Publish

When you're ready to share:

bash
oxp pack                    # Build a signed .oxp bundle
oxp login                   # Authenticate with the registry
oxp publish                 # Upload to oxp.sh

The pack command creates a deterministic, Ed25519-signed .oxp bundle in your dist/ directory. The publish command uploads it to the registry where anyone can install it.

What's Next