DocsStartInstall

Install

You need Node 22.12 or newer. The libraries themselves have no runtime dependencies; Node is only for the tools (xoong sync, dev, build).

1. Install

@xoong/xoong is one install for the runtime, the admin set and the xoong command. Or take single packages: @xoong/core, @xoong/data, @xoong/forms, @xoong/ui, @xoong/controls, @xoong/richtext, @xoong/i18n, @xoong/cli.

npm install @xoong/xoong@next

npm install @xoong/core@next @xoong/data@next @xoong/ui@next @xoong/controls@next

2. Or use a release file

Each GitHub Release has one tarball per package and a consume.json that says what to copy into your package.json. Use it to try an unreleased tag or to work without the registry.

gh release download v0.0.54 -R fpt-duongtx/xoong -D vendor/xoong

{
  "dependencies": {
    "@xoong/xoong": "file:./vendor/xoong/xoong-xoong-0.0.54.tgz",
    "@xoong/ui": "file:./vendor/xoong/xoong-ui-0.0.54.tgz"
  },
  "overrides": {
    "@xoong/core": "file:./vendor/xoong/xoong-core-0.0.54.tgz"
  }
}

3. Generate typed operations and run

Give xoong sync your OpenAPI document (a file or a URL). It writes .xoong/operations.json, which the data layer reads, and api.d.ts for TypeScript.

npx xoong sync openapi.json      # writes .xoong/operations.json and api.d.ts
npx xoong dev                    # static server with an API proxy
npx xoong build --out dist       # static output for strict-CSP hosting

{
  "port": 5173,
  "proxy": { "/api": "http://localhost:8080" }
}

4. A first screen

Or let xoong new do steps 3 and 4: npx xoong new my-app --spec openapi.json creates a project with a first list screen.

<!doctype html>
<link rel="stylesheet" href="/@xoong/ui/src/xoong.css">
<script type="module" src="main.js"></script>

<xo-view get="listPeople">
  <p xo-if="$loading">Loading…</p>
  <xo-table columns="name,email:E-mail,role" sortable></xo-table>
</xo-view>

import { configure } from '@xoong/data';
import '@xoong/data/view';
import '@xoong/ui';
import operations from '/.xoong/operations.json' with { type: 'json' };

configure({ api: operations, baseUrl: '/api' });

Run npx xoong check index.html to lint the markup against your API; each message says how to fix it.

Every command and option is on the Command line page; an AI assistant can use the MCP server, and your editor can complete and explain the elements with editor support.