amenui
en·中 github ↗ v0.0.1
01docs 02components 03lab 04works
en·中github ↗
×

docs / start / installation docs / start /

Installation

01.2
On this page ▾
  1. Native desktop (winit)
  2. The web (wasm bundle)
  3. Embedding: <amenui-view>
  4. Manual: copy components into your project

Pick the host your interface lives in. All three draw the same pixels: the framework draws everything itself, and the host only gives it a surface, input and time.

Native desktop (winit)

You need the latest stable Rust and a GPU, or Mesa's lavapipe (Vulkan on the CPU).

sh
cargo run --release --bin window -- body
cargo test --release
cargo run --release --bin check

The window opens on the page named after --: body (the landing scene), a component such as button, or a look:v3: recipe.

The web (wasm bundle)

WebGPU when the browser has it, else WebGL2. The WebGL2 path is the webgl feature, on by default; with default-features = false the module carries only WebGPU and is about a quarter smaller, and a browser without WebGPU reports opts.onFail('adapter', message) instead of starting. The site is built twice from the same code: the full module (dist/pkg, with webgl) and a WebGPU-only one (dist/pkg-gpu, --no-default-features). The page loads the WebGPU-only module where navigator.gpu exists, and the full one otherwise or when that one cannot start. web/build.py writes the site to dist/site/: one small HTML page per address, the glue script, both modules and the font subsets, each a separate file with a content hash in its name. The longer texts some pages show (the Lab's Markdown, the sources on component pages, the demos' English) are files beside the module, fetched by the page that shows them, not compiled in.

sh
cargo build --release --lib --target wasm32-unknown-unknown
wasm-bindgen --target no-modules --no-typescript --remove-name-section --out-dir dist/pkg target/wasm32-unknown-unknown/release/website.wasm
cargo build --release --lib --target wasm32-unknown-unknown --no-default-features
wasm-bindgen --target no-modules --no-typescript --remove-name-section --out-dir dist/pkg-gpu target/wasm32-unknown-unknown/release/website.wasm
BASE=/ python3 web/build.py
python3 -m http.server -d dist/site

BASE is where the site is served (/ on its own domain). The page follows its address: /components/button/ opens a component, /zh-Hans/… the same page in Chinese, and #look:v3:… applies a recipe.

Embedding: <amenui-view>

The same build defines a custom element, so any page or framework that renders HTML can hold the interface. dist/embed-example.html is a plain page that uses it.

One <amenui-view> per document: the module holds one runtime and one renderer. A second one (or one on the full page) is not drawn; it says so in its box and carries data-amenui-limit="one-per-document", and the first keeps working.

AttributeWhat it does
pageThe page to show: a component's name (button), body, any page's hash.
recipeA look:v3: recipe: the look it describes.
theme, materialBy name, as the render tool takes them (dark, dottr).
localezh-Hans or en.

It fires amenui-ready once it draws and amenui-route (with detail.page) whenever the page changes inside it, and it follows its own box as it is resized. One per document.

Plain HTML:

html
<amenui-view page="button" theme="light" locale="en" style="height: 480px"></amenui-view>

React (custom elements pass attributes as they are; listen with a ref):

tsx
const ref = useRef<HTMLElement>(null);
useEffect(() => { const v = ref.current; const f = (e: any) => setPage(e.detail.page); v?.addEventListener('amenui-route', f); return () => v?.removeEventListener('amenui-route', f); }, []);
return <amenui-view ref={ref} page={page} theme="dark" style={{ height: 480 }} />;

Vue (tell the compiler the tag is a custom element: compilerOptions.isCustomElement = t => t === 'amenui-view'):

html
<amenui-view :page="page" theme="dark" @amenui-route="page = $event.detail.page" style="height: 480px" />

Svelte:

html
<amenui-view page={page} theme="dark" on:amenui-route={(e) => (page = e.detail.page)} style="height: 480px"></amenui-view>

Angular (add CUSTOM_ELEMENTS_SCHEMA to the component):

html
<amenui-view [attr.page]="page" theme="dark" (amenui-route)="page = $event.detail.page" style="height: 480px"></amenui-view>

Manual: copy components into your project

Components are distributed as source, as shadcn/ui does it: amenui add copies a component and the files it depends on, as registry.json lists them, into your project at the same paths; files already there are left alone.

sh
cargo run --release --bin amenui -- add dialog --to ../my-app

Or copy by hand: the component's page lists its files under Installation.