# 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](/start-here/glossary/#in-platform-rendering), where the CMS renders them itself; or [headless](/start-here/glossary/#headless), a frontend you build). Answer two questions and you have your path:

1. **Do you need code-level control of Drupal**: custom modules, a content model in code? *No* → Source CMS. *Yes* → Cloud Platform.
2. **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 <a href="https://www.acquia.com/products/acquia-cloud-platform/trial" target="_blank" rel="noopener">Cloud Platform free trial</a> gives you a Drupal 11 application the same day, so the Cloud Platform paths need no wait; for a Source CMS site, <a href="https://www.acquia.com/request-a-demo/acquia-source" target="_blank" rel="noopener">request a Source demo</a>.

<PathQuadrant />

## What each rendering mode gives you

With in-platform rendering you still write React [components](/start-here/glossary/#component) 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](/start-here/glossary/#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](/source-cms/canvas-components/guide/#style-with-tailwind-and-know-how-the-css-travels).

Headless gives you your own app: the whole React tree (context, providers), server code that [keeps credentials off the browser](/source-cms/content-api/fetch-content/#put-the-fetch-where-it-belongs), and your framework's [caching and revalidation](/source-cms/content-api/fetch-content/#cache-what-you-fetch-and-revalidate-it). 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](/start-here/glossary/#canvas-headless), editors keep composing pages from your components while your app does the rendering ([quickstart](/source-cms/get-content/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](/start-here/glossary/#pages-canvas) visually in [Drupal Canvas](/start-here/glossary/#drupal-canvas) from [components](/start-here/glossary/#component) you write as React/JSX. Your development work is the component library; the site serves the pages itself.

Start with [your first component](/source-cms/canvas-components/quickstart/), then the rest of the [Canvas components section](/source-cms/canvas-components/).

## 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](/start-here/glossary/#site) serves your content over [JSON:API](/start-here/glossary/#jsonapi) at `/api` from day one, with per-site [API clients](/start-here/glossary/#api-client) and [webhooks](/start-here/glossary/#webhook) 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](/source-cms/get-content/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](/source-cms/content-api/quickstart/) alongside [authentication](/source-cms/authenticate/quickstart/) (reads need credentials too unless the site opts into public access; writes always do), then [your first fetch](/source-cms/content-api/first-fetch/). [Deploying the frontend](/source-cms/deploy/) 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](/start-here/glossary/#application-cloud-platform) (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](https://docs.acquia.com/drupal-starter-kits/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](/start-here/glossary/#drupal-api-client)'s `apiPrefix` option absorbs either, so the [querying guides](/source-cms/content-api/guide/) apply to both backends. Endpoints and auth are defined by your own application, so for their reference, see [Drupal's JSON:API documentation](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module).

Start with [local development](/cloud-platform/local-dev/quickstart/), the [Cloud Platform code workflow](/cloud-platform/code-workflow/quickstart/) for the backend, then [Drupal's JSON:API documentation](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module) for the content layer and [frontend deploy](/source-cms/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](/start-here/glossary/#environment) 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](/source-cms/canvas-components/) work against any Canvas-enabled site (to install the module, see [drupal.org/docs](https://www.drupal.org/docs)). [Set up a codebase](/cloud-platform/code-workflow/set-up-a-codebase/) covers both a first codebase and a site coming from another host.

Start by [setting up a codebase](/cloud-platform/code-workflow/set-up-a-codebase/) if you need one, then [ship one change](/cloud-platform/code-workflow/quickstart/), [local development](/cloud-platform/local-dev/quickstart/), the [code-workflow guide](/cloud-platform/code-workflow/guide/), and [CI/CD](/cloud-platform/ci-cd/quickstart/).

## 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](https://www.drupal.org/docs) and [api.drupal.org](https://api.drupal.org).
- **Working within Acquia** (environments, local development, deploys, CI/CD, [the CLI](/cloud-platform/cli/quickstart/), [Cloud IDE](/start-here/glossary/#cloud-ide)) is the same on every path.
- **Configuring or administering a [subscription](/start-here/glossary/#subscription)** happens in the product, not in code. To manage users, teams, roles, and permissions, see [managing users, teams, roles, and permissions](https://docs.acquia.com/acquia-cloud-platform/managing-users-teams-roles-and-permissions) in the [Cloud Platform documentation](https://docs.acquia.com/acquia-cloud-platform/overview); to configure site settings, workflows, and editorial permissions on Source CMS, see the [Source CMS documentation](https://docs.acquia.com/acquia-source/overview). Multisite fleets are administered through [Site Factory](https://docs.acquia.com/site-factory/overview) and digital assets through [Acquia DAM](https://docs.acquia.com/acquia-dam/overview). Provisioning a Cloud IDE, its limits, and its cost are subscription settings too; for those, see [docs.acquia.com](https://docs.acquia.com).