---
id: "api-playground"
type: "guide"
title: "Embed @x12i/api-playground"
summary: "Build a catalog-driven Try-it UI for any HTTP API using the reusable API playground shell."
why: "Stand up endpoint docs + Try-it for a new service set without forking the web-agentic playground."
audiences: ["developers"]
related: ["playground", "host-web-agentic-api"]
confirmationRequired: false
updatedAt: "2026-08-03T17:53:34.418Z"
---
# Embed @x12i/api-playground

# Embed @x12i/api-playground

`@x12i/api-playground` is a **catalog-driven API playground shell**: nav, docs, Try-it chrome, local runs history, env settings, static server, and dual-process launcher. Product apps supply catalogs and domain renderers. The shell never imports your service packages — browser ↔ HTTP only.

## Use this when

- You want a playground for **any** REST surface (not only web-agentic)
- You need zero-build browser modules (no Vite/webpack required)
- You already have (or will have) an HTTP API with `/health`

## Install

```bash
pnpm add @x12i/api-playground
```

## Steps

1. Create a static product app (`index.html`, `app.js`, forms, catalog data).
2. Serve it with `createStaticServer` and mount the package:

```js
import { createRequire } from "node:module";
import { dirname, join } from "node:path";
import { createStaticServer } from "@x12i/api-playground/server.mjs";

const require = createRequire(import.meta.url);
const pkg = dirname(require.resolve("@x12i/api-playground/package.json"));

createStaticServer({
  root: /* product dir */,
  port: 7081,
  apiOrigin: "http://localhost:7080",
  mounts: [
    { urlPrefix: "/@api-playground/", fsRoot: join(pkg, "src") },
    { urlPrefix: "/@api-playground-assets/", fsRoot: join(pkg, "assets") },
  ],
});
```

3. Link shell CSS: `/@api-playground-assets/shell.css`.
4. Import factories from `/@api-playground/create-playground.js` and pass your `groups` / `endpoints`.
5. Optionally wire `launchDevUi` so `pnpm ui`-style starts API + UI together.

## Product vs shell

| Shell (`@x12i/api-playground`) | Product app |
|---|---|
| Catalog nav, docs view, env, runs drawer | Endpoint list + grouping |
| Response mode chrome | Domain response renderers |
| Static server + mounts | Try-it forms + submit handlers |
| `launchDevUi` | API start command / ports / branding |

Reference implementation: `apps/playground` in this monorepo (web-agentic catalog + forms).

## Verification

- Package resolves: `node -e "require('module').createRequire('file:///x').resolve('@x12i/api-playground/server.mjs')"` (or ESM equivalent)
- UI serves `/@api-playground/catalog-nav.js` with HTTP 200
- Catalog selection renders docs; Try-it calls your API origin

## See also

- npm: [`@x12i/api-playground`](https://www.npmjs.com/package/@x12i/api-playground)
- Guide [playground](./playground.md) for the web-agentic product UI