UI Developer

UI Developer Guide

UI lives in src/ui/. Strict layered architecture — React is a dumb display layer. All state, logic, and data transformation live in plain TypeScript classes wired through @webiny/di. Shared types, errors, and domain models go in src/shared/.

Layer Rules

React (display only) ← reads vm, calls actions
  ↑ useFeature() hook
Presenter (MobX observable) ← owns vm() getter, single source of UI truth
  ↑ DI constructor injection
UseCase (orchestration) ← all reads and writes
  ↑
Repository (plain class) ← holds domain state, NOT MobX observable
  ↑
Gateway (HTTP calls) ← translates API responses to domain types

Result Pattern (no throws)

All layers use Result<T, E> from @webiny/stdlib — same as CLI. Nothing throws. Gateways catch HTTP errors and return Result.fail(). Use cases return Result. Presenters check result.isOk() / result.isFail() and update state accordingly. Presenters that trigger async work must use try/finally to reset loading state.

Directory Structure

src/ui/
├── features/                    # Headless layer (Gateway + Repository)
│   └── {featureName}/
│       ├── abstractions/
│       │   ├── {Action}{Entity}Gateway.ts
│       │   ├── {Entity}Repository.ts
│       │   └── index.ts
│       ├── {Action}{Entity}Gateway.ts
│       ├── {Entity}Repository.ts
│       └── feature.ts
├── presentation/                # Presentation layer (Presenter + React)
│   └── {domain}/
│       └── {Page}/
│           ├── abstractions/
│           │   ├── {Page}Presenter.ts
│           │   └── index.ts
│           ├── useCases/
│           │   └── {Action}{Entity}/
│           │       ├── abstractions/
│           │       └── {Action}{Entity}UseCase.ts
│           ├── {Page}Presenter.ts
│           ├── {Page}Provider.tsx
│           ├── feature.ts
│           └── components/
│               ├── {Page}Page.tsx
│               └── {Feature}List.tsx
└── feature.ts                   # Root UiFeature

Gateway — HTTP Only

Calls the backend API. Returns Result<T, E>.

// features/projects/abstractions/ProjectsGateway.ts
import { createAbstraction } from "@webiny/stdlib";
import type { Result } from "@webiny/stdlib";

export interface IProjectDto {
  id: string;
  name: string;
  apiUrl: string;
}

export interface IProjectsGateway {
  getAll(): Promise<Result<IProjectDto[], ProjectsGateway.Error>>;
  create(input: ProjectsGateway.CreateInput): Promise<Result<IProjectDto, ProjectsGateway.Error>>;
}

export const ProjectsGateway = createAbstraction<IProjectsGateway>("Ui/ProjectsGateway");

export namespace ProjectsGateway {
  export type Interface = IProjectsGateway;
  export type ProjectDto = IProjectDto;
  export type CreateInput = { name: string; apiUrl: string; token: string };
  export type Error = import("../errors.ts").HttpError;
}

Repository — Plain Class, NO MobX

Holds domain state. Exposes via getter methods. Singleton scope.

class ProjectsRepositoryImpl implements Abstraction.Interface {
  private projects: Abstraction.Project[] = [];

  public constructor(
    private readonly gateway: ProjectsGateway.Interface,
  ) {}

  public getProjects(): Abstraction.Project[] {
    return this.projects;
  }

  public async loadProjects(): Promise<Result<void, Abstraction.Error>> {
    const result = await this.gateway.getAll();
    if (result.isFail()) {
      return Result.fail(result.error);
    }
    this.projects = result.value;
    return Result.ok(undefined);
  }
}

UseCase — Orchestration

Coordinates repositories. Transient scope. Presenters call use cases, never repositories or gateways directly.

Presenter — The Only MobX Layer

Owns vm() getter. Maps domain state to view-ready data. Transient scope.

import { makeAutoObservable, runInAction, computed } from "mobx";

class ProjectListPresenterImpl implements Abstraction.Interface {
  private loading = false;

  public constructor(
    private readonly loadProjectsUseCase: LoadProjectsUseCase.Interface,
    private readonly projectsRepository: ProjectsRepository.Interface,
  ) {
    makeAutoObservable(this, { vm: computed });
  }

  public get vm(): Abstraction.ViewModel {
    const projects = this.projectsRepository.getProjects();
    return {
      loading: this.loading,
      projects: projects.map(p => ({ id: p.id, name: p.name, apiUrl: p.apiUrl })),
      isEmpty: projects.length === 0,
    };
  }

  public load = async (): Promise<void> => {
    this.loading = true;
    try {
      await this.loadProjectsUseCase.execute();
    } finally {
      runInAction(() => { this.loading = false; });
    }
  };
}

Rules:

• makeAutoObservable(this, { vm: computed }) in constructor
• vm is a computed getter returning a plain object with view-ready data
• All methods (except vm) are arrow function class properties (lexical this)
• Async mutations wrapped in runInAction()
• Presenter provides correct values — views never do value ?? "" or null coercion

React — Display Only

Zero business logic. Zero data transformation. Reads vm, calls presenter actions.

import { useEffect } from "react";
import { observer } from "mobx-react-lite";
import type { ProjectListPresenter } from "../abstractions/ProjectListPresenter.ts";

interface ProjectListPageProps {
  presenter: ProjectListPresenter.Interface;
}

export const ProjectListPage = observer(function ProjectListPage({
  presenter
}: ProjectListPageProps) {
  const { vm } = presenter;

  useEffect(() => { presenter.load(); }, [presenter]);

  if (vm.loading) return <div>Loading...</div>;
  if (vm.isEmpty) return <div>No projects configured.</div>;

  return (
    <ul>
      {vm.projects.map(p => <li key={p.id}>{p.name} — {p.apiUrl}</li>)}
    </ul>
  );
});

Provider

Connects DI to React via render props:

import type React from "react";
import { useFeature } from "../../shared/di/useFeature.ts";
import { ProjectListFeature } from "./feature.ts";
import type { ProjectListPresenter } from "./abstractions/ProjectListPresenter.ts";

interface Props {
  children: (params: { presenter: ProjectListPresenter.Interface }) => React.ReactNode;
}

export function ProjectListProvider({ children }: Props) {
  const { presenter } = useFeature(ProjectListFeature);
  return children({ presenter });
}

Anti-Patterns

Feature Registration

UI features use createFeature from @webiny/stdlib with dependencies support for auto-registration.

import { createFeature } from "@webiny/stdlib";

export const ProjectsFeature = createFeature({
  name: "Ui/ProjectsFeature",
  register(container) {
    container.register(ProjectsGateway).inSingletonScope();
    container.register(ProjectsRepository).inSingletonScope();
  },
});