Before writing a line of code, decide where the pages are composed: on the platform, in an application of your own, or mostly on the platform with some pieces filled in by the browser. The decision shapes everything that follows and is expensive to reverse, so make it on purpose.

Who this guide is for

Whoever decides how a site is built: the technical lead at a kickoff, the developer arriving from another platform, the team weighing a headless front end. It assumes no more than Core dna for site builders. Template examples are given in both Smarty and Twig.

The decision in ten seconds

  • Does the interface behave like an application, with continuous state across screens, or must the same front end also serve a native app? Then consider headless.
  • Otherwise render on the server, in Smarty or Twig.
  • Do some parts of a page differ per visitor, such as a cart count or a signed-in state? Then it is hybrid: a cached, server-rendered page with those pieces filled in afterwards. Almost every production site ends up here.
  • Several brands, regions or languages? That is an overlay on any of the above, not a fourth shape.

The units, in order

  1. The build-shape decision: the decision tree, the three shapes and the overlay, and what the choice does not change.
  2. Headless, over the three API surfaces: REST, GraphQL and custom endpoints, credentials, what a headless build gives up and rebuilds, drafts and invalidation, and when headless is right.
  3. Server-side templating, what you get: what the platform does that you do not write, in-context editing, what server rendering costs, and the signals that point elsewhere.
  4. Hybrid, the common case: handing state to the browser, one client module, dynamic fragments, a personalisation bundle, what must work without JavaScript, and splitting bundles.
  5. Multi-brand and multi-language: hostnames or sites, per-brand templates and tokens, shared components, languages, and content by region.
  6. Making the choice: a decision table for the kickoff, five case studies, and migration paths.

Jobs, under Customization › Orchestration in the admin, were called hooks before the module was renamed.