# Development Guide

Rules and workflow for UI-only changes, repo setup, and what you are allowed to edit.


Deliver a complete presentation change while keeping the template's data and routing intact.

Template paths and editor controls depend on the separate template repository. Confirm them in your checkout; see [what the product defines](https://erxes.io/docs/content-plug-template-developers-introduction).

## Map the assignment

Identify the template revision, design handoff, affected page or section, data source, and expected states. Confirm whether the assignment is presentation-only or includes new behavior.

> [!WARNING]
> **UI-only scope**
>
> For a UI-only change, preserve the existing routes, GraphQL operations, authentication, section registry, and configuration schema. Do not touch the data layer. A presentation change never requires editing a query document, a portal token, or the `pageItems` shape.

Work in the relevant template: product screens in an `ecommerce` template, tour screens in a `tour` template, or room screens in a `hotel` template. The product seeds page slugs per `templateType`: `ecommerce`, `restaurant`, and `hotel` sites get `products`, `product`, `checkout`, `profile`, `confirmation`, `login`, `register`, and `booking` on top of the default `home`, `about`, `contact`, `privacy`, `terms`, `blogs`, `blog`, and `legal` pages; `tour` sites get `tours`, `tour`, `inquiry`, and the shared commerce-style pages `checkout`, `confirmation`, `profile`, `login`, `register`, and `booking`. See [`createWeb`](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/content_api/src/modules/webbuilder/graphql/resolvers/mutations/web.ts#L12-L67). Shared layout changes affect every page using that layout, so make them deliberately.

## Follow content into the component

Trace a representative record through the fixture or CMS query, the template's adapter, its section mapping, and the rendered component. Compare the empty and populated versions before changing layout.

A live page request returns the same shape a deploy writes to `data/pages/<slug>.json`. Fetch a page with its sections:

```graphql
query CpCmsPageDetail($slug: String, $language: String) {
  cpCmsPageDetail(slug: $slug, language: $language) {
    _id
    name
    slug
    description
    coverImage
    status
    pageItems {
      _id
      name
      type
      content
      order
      objectType
      objectId
      config
    }
  }
}
```

Pass either `slug` or `_id`; with neither, `cpCmsPageDetail` returns `null`. The portal comes from your token, so a slug from another site cannot be read. See [`cpCmsPageDetail`](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/content_api/src/modules/cms/graphql/queries/page.ts#L121-L138). For the other operations, see [Queries](https://erxes.io/docs/content-plug-cms-next-developers-queries).

Use the [structure guide](https://erxes.io/docs/content-plug-template-developers-template-structure) to locate responsibilities. Preserve existing helpers for links, assets, localization, and formatting. Validate unknown JSON configuration before reading section-specific properties.

## Implement the design

Reuse the template's own UI components and design tokens. Match the requested spacing, typography, imagery, and responsive behavior while supporting long text, missing images, and varying collection sizes.

Keep controls functional: links need valid destinations, buttons need their intended action, and forms need labels, validation, errors, and submission feedback. For API-backed content, preserve loading, empty, and error states. Do not render unpublished content as a fallback when a public request returns no results.

The [section catalog](https://erxes.io/docs/content-plug-template-designers-template-sections) describes design requirements for common sections. Not every boilerplate implements every section or field.

## Review with realistic content

Test a narrow mobile screen, a wider layout, keyboard navigation, visible focus, and long or translated content. Exercise client-side navigation, direct page loads, reloads, and the enabled themes.

Use fixture mode for predictable layout checks and the configured live integration for data checks. Check the same section in every supported rendering mode. Run the repository's available quality and build scripts from its documented workspace root. The [deployer](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/plugins/content_api/src/modules/webbuilder/utils/utils.ts) builds with `yarn install` and `next build`, so a template that cannot pass `next build` cannot deploy.

## Prepare the handoff

Describe the affected pages/components, visible change, fields kept or intentionally changed, and checks performed. Include images of the meaningful states when useful to reviewers. Call out any requirement that could not be implemented within the agreed scope.

If creating a new template repository, first confirm its owner, license obligations, base revision, and destination. Keep the boilerplate remote as an upstream reference and check the destination before pushing. Do not redirect an existing project's remote as part of an ordinary UI update.