Choose your path

Two decisions define how you build on Acquia: who runs the backend, Acquia (SaaS, with Source CMS) or you (PaaS, with self-managed Drupal on Cloud Platform), and who renders the pages (the default mode, in-platform rendering, where the CMS renders them itself; or headless, a frontend you build). Answer two questions and you have your path:

Do you need code-level control of Drupal: custom modules, a content model in code? No → Source CMS. Yes → Cloud Platform.
Do you need a separate frontend? The default mode is in-platform rendering: editors compose pages in the CMS, and it serves them. Stay with the default unless one of these is true: you already have a frontend app or framework investment to integrate with, you’re delivering to a non-web channel Canvas can’t render (a mobile app, digital signage, a third-party site), or your frontend team needs to ship independently of the content/component team. Any of those → headless.

The first answer picks your sidebar menu: Source CMS or Cloud Platform, switchable at the top of the sidebar. The second picks your reading order inside it; the four combinations below each tell you where to start, in-platform rendering on Source CMS first since it’s the simplest path to a running site. Without a site to build against, a self-serve Cloud Platform free trial gives you a Drupal 11 application the same day, so the Cloud Platform paths need no wait; for a Source CMS site, request a Source demo.

Acquia runs the backend · Source CMSIn-platform on Source CMS →The simplest path to a running site: the platform renders, nothing to host.Headless on Source CMS →Your app renders; the managed backend serves content from day one.You run the backend · Cloud PlatformIn-platform on Cloud Platform →The classic Drupal setup: your application renders its own pages.Headless on Cloud Platform →Full control of both halves: your Drupal serving an app you build.

What each rendering mode gives you

With in-platform rendering you still write React components with npm packages. They live in your git repository, editors compose pages from them visually, and there is nothing for you to host. Two limits to know:

Components cannot share React context: each one renders on its own island.
Components cannot hold secrets: their inputs end up in the page every visitor gets. The site’s own cookie-authenticated APIs and public client-side keys work fine; a confidential call needs your own Drupal code on Cloud Platform, or headless on Source CMS, where custom PHP is not available.

For the mechanics behind both, see component development.

Headless gives you your own app: the whole React tree (context, providers), server code that keeps credentials off the browser, and your framework’s caching and revalidation. Choose it when you need any of those.

A site renders one way at a time: going headless turns in-platform rendering off. The visual editing stays, though: with Canvas Headless, editors keep composing pages from your components while your app does the rendering (quickstart).

In-platform rendering on Source CMS

The default path if none of the headless-required situations above apply to you. No frontend to build or host: editors compose pages visually in Drupal Canvas from components you write as React/JSX. Your development work is the component library; the site serves the pages itself.

Start with your first component, then the rest of the Canvas components section.

Headless on Source CMS

Choose this over the default when one of the situations above applies: an existing frontend to integrate with, a non-web delivery channel, or a frontend team that ships independently. You build the frontend (Next.js, Astro, Nuxt); a Source CMS site serves your content over JSON:API at /api from day one, with per-site API clients and webhooks built in: no backend to install, update, or operate.

The recommended route is Canvas Headless: scaffold the app with the Canvas-provided starter kit (npx @drupal-canvas/create@latest, with Next.js, Astro, and Nuxt templates), and editors keep composing pages from your components while your app renders them; the Canvas Headless quickstart walks the path from the scaffold to a component an editor can place (an app you already have is wired in with the same SDK). For the content as data (listings, custom queries), the advanced path talks JSON:API directly: querying alongside authentication (reads need credentials too unless the site opts into public access; writes always do), then your first fetch. Deploying the frontend is the same for every app. Skip the starter kit when you are delivering to a channel with no pages to compose (a mobile app, digital signage): that direct path stands on its own, with your own scaffold.

Headless on Cloud Platform

Full control of both halves: your own Drupal application (custom modules, contributed modules, a content model in code) serving JSON:API to a frontend you build. Scaffold the backend with the Headless starter kit (./vendor/bin/acms acms:install, documented at docs.acquia.com), which preconfigures JSON:API, OAuth, and Next.js integration. Your site’s API is Drupal core JSON:API, the same specification the Source CMS Content API speaks: it serves /jsonapi by default where Source serves /api, the base path is configurable in your application, and the Drupal API Client’s apiPrefix option absorbs either, so the querying guides apply to both backends. Endpoints and auth are defined by your own application, so for their reference, see Drupal’s JSON:API documentation.

Start with local development, the Cloud Platform code workflow for the backend, then Drupal’s JSON:API documentation for the content layer and frontend deploy.

In-platform rendering on Cloud Platform

The classic Drupal-on-Acquia setup: a full Drupal application rendering its own pages, deployed to Cloud Platform environments through git. Page building can be classic Drupal theming or Drupal Canvas: Canvas is an open-source Drupal module you can add to your own codebase, and the same components and push workflow from the Canvas components section work against any Canvas-enabled site (to install the module, see drupal.org/docs). Set up a codebase covers both a first codebase and a site coming from another host.

Start by setting up a codebase if you need one, then ship one change, local development, the code-workflow guide, and CI/CD.

Where each kind of work happens

Three kinds of work, split the same way on every path:

Writing Drupal application code (modules, hooks, theming) is open-source Drupal work; for the API and module reference, see drupal.org/docs and api.drupal.org.
Working within Acquia (environments, local development, deploys, CI/CD, the CLI, Cloud IDE) is the same on every path.
Configuring or administering a subscription happens in the product, not in code. To manage users, teams, roles, and permissions, see managing users, teams, roles, and permissions in the Cloud Platform documentation; to configure site settings, workflows, and editorial permissions on Source CMS, see the Source CMS documentation. Multisite fleets are administered through Site Factory and digital assets through Acquia DAM. Provisioning a Cloud IDE, its limits, and its cost are subscription settings too; for those, see docs.acquia.com.

Was this page helpful?