Install

This page explains what ClientX is, its architecture layers, and two ways to install core: the local workspace package (source, for customization) and the prebuilt bundle (extract and run). It then shows how to create your first resource with clientx create.

1. What is ClientX

ClientX is a resource-decoupled frontend application framework. It splits a complete frontend application into core and pluggable resources:

• core: the app frame, runtime loader, kernel registries and shared packages (@clientx/runtime / @clientx/common). Core contains no concrete resource names — it only knows how to boot.
• resources: self-contained functional units with their own identity, routes, capabilities, slots, i18n and code. Examples: client (app shell), msgx (messaging), userx (users), agix (AI engine), sitex (site framework), portal (website).

The three rules that matter:

1. core does not import resources: core-loader.ts reads the closure from manifest.json at runtime and loads resources dynamically.
2. resources declare themselves: each resource uses register.ts with declare / activate; dependencies and capabilities enter the kernel registries automatically.
3. one React instance: the react family resolves through the importmap to shared-vendor.js, so core and every resource share one React, one i18n and one query client.

2. Install core: two options

Option A: workspace source (for customization)

Download and extract clientx-core-source.tar.gz:

tar xzf clientx-core-source.tar.gz
cd clientx/
npm install

The toolchain source contains the @clientx/runtime and @clientx/common workspace packages, the CLI (scripts/clientx.mjs), all builders (scripts/p3/) and project configuration. Once installed:

node scripts/clientx.mjs build     # build the default composition
node scripts/clientx.mjs run       # start the dev server

Option B: prebuilt bundle (extract and run)

No Node toolchain required. Download and extract clientx-core-prebuild.tar.gz:

tar xzf clientx-core-prebuild.tar.gz
# dist/ contains core-app + shared-vendor + vendor(@clientx) + default resources + manifest

Serve dist/ with any static server:

npx serve dist           # or python3 -m http.server --directory dist 3007

The prebuilt output is the default closure (client+userx+msgx+agix+conn+e2ee). It does not include the website resources (portal / docs / help). To compose a custom combination (for example, only the website), use Option A and build from source (see the Package guide).

3. Create a project: clientx create

After installing core from source, generate a new resource skeleton:

node scripts/clientx.mjs create hello --deps client

Arguments:

• hello: resource name. It must start with a lowercase letter; the first segment needs at least 2 characters and later segments at least 1, separated by single hyphens (demo, my-site, my-a are valid).
• --deps client: declares a dependency on client (written to package.json under clientx.deps). Every id in --deps must be a buildable resource under src/resource/.
• --kind app|site: resource type, default app. Use --kind site for a site resource (then depend on sitex).

The command generates a minimal buildable skeleton at src/resource/hello/:

src/resource/hello/
├── package.json     # name: @me/hello + clientx: { id, kind, deps, entry }
├── register.ts      # declareHello() + activateHello()
└── i18n/
    ├── zh.json      # {}
    └── en.json      # {}

Verify the build:

node scripts/clientx.mjs build --resources hello,client

4. Directory layout

clientx/
├── packages/@clientx/
│   ├── runtime/            # kernel: resource/route/slot/feature registries, i18n
│   └── common/             # shared components (markdown/content/ui) and utilities
├── scripts/
│   ├── clientx.mjs         # CLI: build / create / run
│   └── p3/                 # builders, closure resolution, download artifact generation
├── src/
│   ├── App.tsx             # app frame (layout / query client / theme)
│   ├── main.tsx            # entry (static dev registration / production loader)
│   ├── core-loader.ts      # production runtime: load resources from manifest
│   └── resource/<id>/      # resources (register.ts + modules + i18n)
└── vite.config.ts          # aliases / proxy / download middleware

5. Downloads

The downloads area provides several artifacts (see the downloads page):

Next: read the Develop guide to learn about register.ts and the resource lifecycle.