Aster UI / Guides

Organize an application

Group an application's code by the work it does. Keep a screen's definition, model, registered components and views together, so you can understand or change that screen without searching a collection of unrelated files.

The showcase source uses this convention:

src/
  app/
    showcase.ui.yaml
    main.ts
    model.ts
    registry.ts
    routing.ts
    catalogue.ts
    views/
  examples/
    composition/
      composition.html
      composition.js
      composition.ui.yaml
      composition-model.js
      composition-registry.js
      composition-details.js
      composition-mock.js
    mail/
    foundations/
  shared/
    navigation/

These are application conventions, not required filenames. Use JavaScript or TypeScript; begin with fewer files and separate responsibilities as they grow. A small field example does not need a registry, model factory and view directory.

Keep structure and behaviour close

A definition declares named children, properties, bindings, layout and rules. The showcase shell's YAML declares a sidebar, gallery and lazy preview. It does not contain a second copy of the catalogue or executable functions.

A model owns queries, selection, edit state, commands and cleanup. Derived signals express what the screen should show. In the showcase, the selected route determines the preview title, filename and active deck surface.

A registry connects names in the definition to trusted functions, components and module loaders. Keep custom rendering functions and lazy factories beside their screen. YAML can refer to those registrations; it cannot evaluate code.

The entry point supplies inputs, mounts the composition and connects browser events to application actions. Keep route and history handling explicit. Release the composition when its host disconnects, and release subscriptions or services owned by the application separately.

See Compose a workspace for the APIs and Customize workspaces for variants and ownership.

Share deliberate boundaries

Keep feature-specific fixtures, styles and renderers in their feature folder. Move a module to shared/ when several features need the same behaviour. Shared navigation and appearance are useful; one global object holding every screen's query, draft and selection makes ownership harder to follow.

The showcase's standalone examples import the public packages. Its static build provides a browser import map and compiles YAML to JSON. A build manifest maps feature files to stable example URLs, so reorganizing source does not invalidate bookmarks. Your application can instead use its normal bundler and router.

Keep documentation connected to working code

The documentation site lives in apps/docs/. Reading pages use static HTML; interactive examples run the same code as the showcase. Search, navigation, appearance, article enhancement and API rendering have separate modules.

Guides live in docs/guide/. Example walkthroughs read their feature excerpts from executable source, and API pages are extracted from the public packages. The build checks source boundaries and public links. This keeps the explanation, the running example and the reference tied to the same implementation.