Choose the right rendering strategy for your ApostropheCMS project

Which ApostropheCMS rendering option should I choose?

Start with the ownership question:

Who should own the visitor-facing frontend?

If Apostrophe should own both content and presentation, traditional rendering is usually the simplest choice. If another application should fully own presentation, routing, deployment, and frontend behavior, headless is usually the cleanest boundary. If a separate frontend should render the site but editors still need Apostrophe's in-context editing experience, hybrid is usually the best fit.

This decision affects more than your template files. It shapes:

• how editors preview and manage pages
• whether content is edited visually or primarily through forms
• whether frontend developers work in the CMS codebase or a separate application
• how content is reused across websites, apps, feeds, or other channels
• how routing, deployment, authentication, and preview are coordinated
• how much integration work your team owns

• Choose traditional when you want the lowest architectural complexity and the strongest native editing experience.
• Choose headless when Apostrophe should be the content source, but not the website renderer.
• Choose hybrid when you want a modern frontend, especially Astro, without giving up in-context editing.

This is an architectural decision, not a permanent lock-in. Projects can move between models over time. The cost depends on the direction and how much frontend, preview, routing, and editor workflow code has already been built.

When should I use ApostropheCMS as a headless CMS?

Use ApostropheCMS headlessly when Apostrophe should manage content but another application should own the frontend completely.

In a headless architecture, Apostrophe provides the content model, admin UI, workflow, permissions, media management, and APIs. Your frontend application fetches content from Apostrophe and decides how that content becomes a visitor-facing experience.

That frontend might be a website, mobile app, kiosk, partner integration, internal dashboard, or another system entirely. Apostrophe is the source of truth for content, but it is not responsible for rendering the final page.

This model is a good fit when:

• the same content needs to power more than one frontend
• the frontend team has its own framework, deployment pipeline, and architecture standards
• the project is more application-like than page-builder-like
• content is structured and reusable rather than primarily composed visually on pages
• the team wants a clear API boundary between content management and presentation
• another system already owns routing, rendering, personalization, or application state

When should I use ApostropheCMS with Astro as a hybrid CMS?

Use a hybrid architecture when you want a separate frontend to render the website, but you still want Apostrophe's visual editing experience for editors.

In ApostropheCMS today, the first-class hybrid path is the Astro integration. Apostrophe remains the content and editing backend. Astro renders the public frontend. The integration connects the two through shared configuration, frontend component mappings, and Apostrophe-aware rendering helpers.

This gives frontend developers an Astro project for the visitor-facing site while preserving Apostrophe's in-context editing for mapped pages, areas, and widgets.

Hybrid is a good fit when:

• editors need to compose and preview pages visually
• frontend developers want Astro's component model and frontend tooling
• the team wants a decoupled frontend without reducing the CMS to a form-only editing experience
• an existing Apostrophe site is moving toward a more modern frontend architecture
• the project is still primarily a website, but the frontend team wants stronger control over components, assets, and rendering behavior
• the organization wants clearer separation between CMS backend work and frontend implementation

Hybrid is different from fully headless because the frontend is not just consuming content from an API. It is participating in Apostrophe's page and widget editing model. That bridge is what allows editors to work in context instead of only managing structured content through forms.

The main tradeoff is operational complexity. A hybrid project usually means two coordinated applications: an Apostrophe backend and an Astro frontend. Your team needs to manage environment variables, shared keys, component mappings, deployment order, preview behavior, and frontend/backend compatibility. That is more setup than a traditional Apostrophe project, but less editor-experience work than building your own headless preview and editing bridge.

When should I use traditional ApostropheCMS rendering?

Use traditional rendering when Apostrophe should manage both content and the visitor-facing website in one application.

In this architecture, Apostrophe owns the content model, admin UI, routing, page rendering, templates, areas, widgets, media, permissions, and publishing workflow. The site and CMS deploy together as one application.

Traditional rendering is Apostrophe's original architecture and remains the simplest option for many projects. Because the editing interface and rendering layer are part of the same application, in-context editing works natively. Editors can view the actual page, click into editable areas, rearrange widgets, and preview content in place without a separate frontend bridge.

Traditional rendering is a good fit when:

• the project is a single website or a multisite setup managed from one codebase
• one team owns the CMS and frontend together
• the editorial experience is a priority
• visual page composition matters more than frontend framework independence
• the team wants one codebase, one deployment, and fewer integration points
• the site does not need to serve the same content to many external consumers
• standard server-rendered web performance is sufficient

In most traditional Apostrophe projects, pages are rendered server-side through Apostrophe's template layer, now commonly using JSX as the default templating option, with modern asset tooling and client-side JavaScript available where needed. This does not prevent rich frontend behavior, but the primary page rendering model remains inside Apostrophe rather than in a separate frontend application.

The main tradeoff is frontend independence. If your team wants the public site to be owned by Astro or another frontend framework, traditional rendering may feel too coupled. If the same content needs to serve mobile apps, partner feeds, or multiple frontend surfaces, traditional rendering can still expose content through APIs, but it may not be the cleanest primary architecture.

Traditional is often the best default when the project is a website, the team values simplicity, and editors need a strong visual page-building workflow.

How should a lead developer choose between traditional, headless, and hybrid?

Choose based on ownership boundaries, not feature preference.

The most useful questions are:

• Who owns the frontend?
• How do editors need to work?
• How many channels need the content?
• How separate are the frontend and CMS teams?
• How much integration complexity is worth taking on?

Who owns the frontend?

If the CMS should own routing, templates, and page rendering, choose traditional.

If another application should own routing, rendering, frontend state, and deployment, choose headless.

If Astro should own the public frontend but Apostrophe should still provide visual editing, choose hybrid.

How do editors need to work?

If editors need to build and revise pages visually, traditional or hybrid is usually the better fit.

If editors are primarily managing structured content that appears in multiple places, headless may be a better fit.

If editors need to see the final page exactly as visitors will see it, do not choose fully headless unless your team is prepared to build or maintain preview behavior.

How many channels need the content?

For one website, traditional or hybrid is usually enough.

For multiple frontends, apps, feeds, or partner integrations, headless is usually the cleaner primary model.

For a website plus some secondary API consumers, traditional or hybrid can still work because Apostrophe content can still be exposed through APIs. The question is whether API delivery is the main architecture or just an additional use case.

How separate are the teams?

If one team owns the whole project, traditional reduces coordination cost.

If a frontend team or external vendor owns the public frontend independently, headless gives them the clearest boundary.

If the frontend team wants a separate Astro application but the content team still needs visual editing, hybrid gives both teams a workable contract.

What complexity are you willing to own?

Traditional has the fewest moving parts.

Headless gives the frontend team the most freedom, but your team owns preview, routing, and content-to-component integration.

Hybrid preserves visual editing with a modern frontend, but your team owns coordination between the Apostrophe backend and the Astro frontend.

What should I do after choosing a rendering model?

Once you know which model fits your project, move to the implementation guide for that path.

If you are going hybrid with Astro, start with the Astro integration guide. It covers how the Apostrophe backend and Astro frontend connect, how components are mapped, and which environment variables are required.

If you are starting a traditional Apostrophe project, use the quick start guide to create a project and begin modeling pages, pieces, areas, and widgets.

If you are planning a larger project, review architecture best practices before implementation. Module structure, content modeling, permissions, and deployment assumptions matter across all three rendering models.

For a broader view of why development teams choose ApostropheCMS, see ApostropheCMS for developers.