Webiny JS Documentation

The Form Model is a declarative form system used in the Webiny Admin UI. It allows developers to define complex forms using a fluent builder API.

Key capabilities include:

• Field Definition: Use a fields registry to create various field types (text, number, boolean, etc.).
• Layout Management: Arrange fields using a layout builder (e.g., layout.row(), layout.tabs()).
• Validation: Implement validation using Zod schemas or imperative rules.
• Advanced Logic: Support for conditional visibility, conditional disabling, computed fields, and reactive context.
• Complex Structures: Handle deeply nested objects, lists, and dynamic zones (templates).

The @webiny/api-websockets-server package provides a Docker/self-hosted WebSocket server transport for the platform-agnostic @webiny/api-websockets base package. It is designed for single-server deployments, replacing the AWS Lambda + API Gateway pattern with a persistent Node.js WebSocket server. It supports two modes:

1. Standalone: The package owns both the HTTP and WebSocket servers.
2. Attach: The user provides an existing HTTP server to the package.

By default, it uses the Node ws library, but it is built with abstractions that allow users to plug in alternative WebSocket libraries like uWebSockets.

The Webiny AI content generation process uses a structured prompt to transform user requests into page content. The system relies on three core pillars:

1. Component Catalog: A registry of available UI components (e.g., Webiny/Hero, Webiny/Grid, Webiny/Lexical) and their valid input types (text, lexical, image, product, etc.).
2. Available Tools: Specialized functions used to process specific input types. For inputs requiring post-processing, values must be wrapped in a tool envelope: { "tool": "<toolName>", "params": { ... } }.
3. Page Schema: The structural format used to define the page. It uses CreateElement actions to handle nested components within slots.

A UseCase is a single-method orchestrator that encapsulates a single business operation (e.g., CreateTenantUseCase). It is a Dependency Injection (DI) abstraction that uses an execute method returning a Result<T, E> type from @webiny/feature/api.

Interface Shape:

interface SomeUseCase.Interface {
    execute(input: Input): Promise<Result<ReturnType, ErrorType>>;
}

• Input: A typed object specific to the use case.
• Result: Always returns Result<T, E>.
• Error: Extends BaseError with a unique code.

The api-websockets package is being split into a platform-agnostic base package and platform-specific providers (e.g., api-websockets-aws).

Base api-websockets package

Contains platform-agnostic abstractions and DI (Dependency Injection) tokens. Key files include:

• src/features/Transport/abstractions.ts: Provides the DI abstraction token for transport.
• src/features/Transport/index.ts: Re-exports abstractions.

Platform-specific providers

• api-websockets-aws: Contains AWS-specific implementations and handlers.
• api-websockets-ddb: DynamoDB-backed connection registry.
• api-websockets-sql: SQL-backed connection registry.

The CMS content entries module follows a layered Dependency Injection (DI) architecture to ensure testability and decoupling. The data flow follows this pattern:

View Layer (React observer) → Presenter (MobX) → UseCase → Repository → Gateway → WebinySdk

• Views: React components that observe Presenters.
• Presenters: MobX-based classes that manage state and compose child presenters and use cases.
• UseCases: Orchestrate repositories to perform specific business logic.
• Repositories: Manage data caching (e.g., ContentEntriesListCache).
• Gateways: Interface with the WebinySdk.
• WebinySdk: The underlying communication layer.

A standard Webiny project follows this structure:

• extensions/: Contains all custom code (API, Admin, Infrastructure, CLI).
• public/: Contains static assets for the Admin application.
• webiny.config.tsx: The central, type-safe configuration file where extensions and React components are registered.
• package.json: Project dependencies and scripts.
• tsconfig.json: TypeScript configuration.

Access control in the Headless CMS is hierarchical. To perform an action on a content entry, permissions must be validated across three related levels:

1. cms.contentModelGroup: Permissions for the group containing the content model.
2. cms.contentModel: Permissions for the specific content model.
3. cms.contentEntry: Permissions for the specific content entry.

An action is only permitted if the user has the necessary permissions at every level of this hierarchy.

The Webiny repository is a monorepo. Key directories and package types include:

• /packages: Contains the core logic and utilities.
  • app-*: Packages used exclusively in React applications.
  • api-*: Packages used for building API services.
  • handler-*: Utility packages for creating serverless function handlers.
  • cli-*: Packages used by the Webiny CLI.
  • mcp/: Contains the Webiny MCP server (packages/mcp/bin.js).
• /apps: Contains the main application implementations (e.g., core, api, admin, website).
• /api and /apps (Root): These folders mirror the structure created by create-webiny-project.

The api-headless-cms-sql package uses a single-table design for storing CMS entries. Instead of mapping every CMS field to a unique SQL column, the entire entry is stored as a JSON blob in a single data column. This eliminates the need for dynamic schema management (ALTER TABLE) and complex field-to-column mappers.

Key characteristics:

• One row per revision: Every row in the webiny_cms_entries table represents a specific revision of an entry.
• Boolean flags for state: Instead of duplicating records for different states (like 'latest' or 'published'), the design uses isLatest and isPublished boolean flags on the revision row.
• In-memory filtering: Since fields are stored in a JSON blob, filtering and sorting on specific CMS fields are performed in-memory after loading the rows.