---
title: Deploying Composable Frontends | Shopware Community Hub
description: >-
  Learn how Composable Frontends run on Native PaaS as their own application
  kind, which runtime contract they must meet, and how builds, deployments, and
  CDN…
canonical_url: 'https://hub.shopware.com/learn/unit/deploying-composable-frontends'
---

<LearningObjectives>

- Explain what a Composable Frontend is and how it relates to the Shopware shop on Native PaaS.
- Configure a frontend application with `kind: cfe` in `application.yaml`, including a monorepo setup.
- Check that a frontend meets the runtime contract for port, health endpoint, and filesystem.
- Deploy a frontend and control its CDN caching with response headers.
- Diagnose typical frontend rollout failures by identifying the phase first.

</LearningObjectives>

# Deploying Composable Frontends

So far, this course has focused on the Shopware shop itself. Some projects, however, replace the Twig-based Storefront with a custom, headless frontend.

Native PaaS can host such a frontend as its own application. It uses the same projects, builds, deployments, environment variables, and Vault secrets that you already know. A few rules are specific to frontends, and they decide whether a rollout succeeds.

In this learning unit, you learn what a Composable Frontend is, how it fits into the platform model, how to configure and deploy it, and how to control its caching.

<Scenario title="A Headless Storefront Next to the Shop">

Your team already runs a Shopware shop on Native PaaS. For a new brand, the merchant wants a custom storefront built with Nuxt. It should talk to the existing shop through the Store API and run on the same platform, so that the team keeps one deployment workflow and one place for secrets.

</Scenario>

## What a Composable Frontend Is

Before you configure anything, it helps to be clear about what you are deploying.

Shopware Composable Frontends are a toolkit for building custom, headless storefronts, typically with Vue 3 and Nuxt 3. The frontend runs as a separate Node.js application and talks to Shopware only through its HTTP APIs, mainly the Store API.

To avoid a common confusion:

- A Composable Frontend **is** a separate application with its own code, its own builds, and its own deployments.
- A Composable Frontend **is not** a Storefront theme. Twig templates, Storefront themes, and the Storefront parts of plugins do not apply to it.
- A Composable Frontend **is not** a slot for any Node.js service. General custom applications are not supported on Native PaaS. Frontends are supported as a dedicated application kind.

**Key terms:**

- **`kind: cfe`**: The application kind that tells Native PaaS to build and run a frontend instead of a Shopware shop.
- **Store API**: The Shopware API that a headless frontend uses for products, cart, checkout, and customer data.
- **Health endpoint**: A URL that the platform calls to decide whether the application is alive and ready for traffic.
- **ISR (Incremental Static Regeneration)**: Caching rendered pages at the edge and refreshing them in the background.

For the framework itself, see the [Shopware Frontends documentation](https://developer.shopware.com/frontends/).

## How a Frontend Fits the Platform Model

A frontend uses the same hierarchy as a shop: an organization contains projects, a project maps to one Git repository, and the repository is deployed as one or more applications.

There are two common repository layouts:

| Layout | How it maps to Native PaaS |
|--------|----------------------------|
| Separate repository for the frontend | The frontend repository is its own project. Its `application.yaml` lives in the repository root. |
| Monorepo with shop and frontend | One project holds several applications. Each application points to its own `application.yaml`. |

In a monorepo, you pass the path of each `application.yaml` when you create the application:

```text
.
├── apps
│   ├── shopware
│   │   ├── application.yaml
│   │   └── composer.json
│   └── frontend
│       ├── application.yaml
│       └── package.json
└── packages
```

```bash
sw-paas application create --name shopware --application-yaml-path apps/shopware/application.yaml
sw-paas application create --name frontend --application-yaml-path apps/frontend/application.yaml
```

The path is stored on the application, so later runs of `sw-paas application update` reuse it. To move the `application.yaml` to another directory, you create a new application.

Whichever layout you choose, the shop and the frontend are separate applications. Each one has its own build and deployment history. Deploying the frontend does not deploy the shop, and the reverse is also true. This is why a release that changes both sides needs two deployments, and the order matters if the frontend depends on a new API behavior in the shop.

## Configure the Frontend in `application.yaml`

The main difference from a shop configuration is the application kind and the runtime. Instead of a PHP version, a frontend declares a Node.js version:

```yaml
kind: cfe

app:
  node:
    version: "24"
```

Choose a Node.js version that the platform supports and that matches your project. The supported versions are listed in the [Composable Frontends documentation](https://developer.shopware.com/docs/products/paas/shopware/composable-frontends/).

### Environment Variables and Secrets

Frontends use the same rules as shops:

- Non-sensitive values go into `app.environment_variables` with `scope: BUILD` or `scope: RUN`.
- Sensitive values go into Vault: `buildenv` for the build and `env` for runtime.

```yaml
kind: cfe

app:
  node:
    version: "24"
  environment_variables:
    - name: NUXT_PUBLIC_SHOPWARE_ENDPOINT
      value: "https://shop.example.com/store-api"
      scope: RUN
```

Pick the scope by asking when the value is read. If your framework reads it while the build runs, it needs `BUILD`. If the running server reads it, it needs `RUN`.

### Custom Dockerfile and Build Context

By default, the managed build system creates the container image for you. If that does not fit your project, you can provide your own Dockerfile:

```yaml
apiVersion: v1
kind: cfe

app:
  build:
    dockerfile_path: Dockerfile
  node:
    version: "24"
```

The `dockerfile_path` is relative to the directory that contains the `application.yaml`. A custom image must run as a non-root user with user ID and group ID `1000`, keep its packages up to date, and use an entrypoint that starts the server directly.

In a monorepo, a frontend sometimes needs files from outside its own directory, for example a shared workspace package. In that case, widen the build context with `app.build.context: ".."`. Keep the context as small as possible, because everything in it is sent to every build.

## Meet the Runtime Contract

A frontend must follow three rules so that the platform can start, monitor, and protect it:

| Requirement | Why it exists |
|-------------|---------------|
| Listen on port `3000` | The platform routes traffic to this port. |
| Expose `/api/healthz` and return success when ready | The platform uses this endpoint for liveness and readiness checks. |
| Write temporary files only to `/app/tmp` | The container filesystem is read-only for security reasons. |

In a Nuxt project, a small server route is enough for the health endpoint. The file `server/api/healthz.get.ts` answers on `/api/healthz`:

```ts
export default defineEventHandler(() => ({ status: "ok" }));
```

The most important detail is **when** these rules are checked. None of them is checked during the build. If the port or the health endpoint is missing, the build succeeds, but the deployment fails its readiness checks and the frontend never serves traffic. A write outside `/app/tmp` fails even later, only when real requests reach that code path.

This connects directly to the build-versus-deploy model from earlier in this course: a green build only proves that the image could be created, not that the frontend can run.

## Deploy and Observe the Frontend

Because a frontend uses the same lifecycle as a shop, the commands are the same:

| Task | Command |
|------|---------|
| Create the application, including its first build and deployment | `sw-paas application create` |
| Build and deploy the current commit | `sw-paas application update` |
| Deploy a specific successful build | `sw-paas application deploy create` |
| Follow the rollout live | `sw-paas watch` |
| Read the build output | `sw-paas application build logs` |
| Read the runtime output | `sw-paas application logs` |

Rollback also works the same way: you deploy an older successful build again.

## Control Caching With Fastly and ISR

Fastly is configured automatically for a frontend, including the redirect from HTTP to HTTPS. After each deployment, the platform performs a full cache purge.

If you only want to purge the CDN cache without a code change, create a new deployment of the same build:

```bash
sw-paas application deploy create
```

This purge-by-redeploy pattern is specific to frontends. For a Shopware shop, cache invalidation is handled automatically by the platform.

The frontend itself decides which pages Fastly may cache. You control this with response headers. To cache a page at the edge and refresh it in the background, send:

```http
Surrogate-Control: max-age=86400, stale-while-revalidate=86400
```

For pages with personal data, such as the customer account, cart, or checkout, prevent caching:

```http
Cache-Control: no-cache, no-store, must-revalidate
Surrogate-Control: no-store
```

In a Nuxt project, you can set these headers per route with `routeRules` in `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  routeRules: {
    "/": {
      isr: 60 * 60 * 24,
      headers: {
        "Surrogate-Control": "max-age=86400, stale-while-revalidate=86400",
      },
    },
    "/account/**": {
      headers: {
        "Cache-Control": "no-cache, no-store, must-revalidate",
        "Surrogate-Control": "no-store",
      },
    },
  },
});
```

**Rule of thumb:** Cache public pages deliberately, and mark every route with personal data as not cacheable.

## Common Pitfalls and First Checks

When a frontend rollout goes wrong, start with the same question as for a shop: in which phase did the problem appear?

| Symptom | First check | Likely cause |
|---------|-------------|--------------|
| The build succeeds, but the deployment never becomes ready | `sw-paas watch` and `sw-paas application deploy get` | The server listens on another port, or `/api/healthz` is missing or fails. |
| Errors about a read-only filesystem appear under traffic | `sw-paas application logs` | The application writes outside `/app/tmp`. |
| A frontend with a custom Dockerfile does not start | `sw-paas application build logs` and the Dockerfile | The image breaks one of the Dockerfile rules, for example it runs as root. |
| A value is empty in the running frontend | `application.yaml` and Vault | The variable has the wrong scope or the wrong secret type. |
| Customers see another customer's account data | The response headers of account routes | A personal route was cached at the edge. |
| Content changes do not appear | The `Surrogate-Control` values | Pages are cached longer than intended. A redeploy purges the cache. |

## Check Your Understanding

Use these questions to check the two core ideas from this learning unit: a frontend is a separate application with the same lifecycle, and its runtime contract is only tested at deployment.

<ArticleMultipleQuestionnaire>
  <ArticleQuestionnaire>
    <ArticleQuestionnaireQuestion>Which statement about Composable Frontends on Native PaaS is correct?</ArticleQuestionnaireQuestion>
    <ArticleQuestionnaireAnswer>They use a separate deployment process that has no builds</ArticleQuestionnaireAnswer>
    <ArticleQuestionnaireAnswer correct>They follow the same build and deployment lifecycle as a shop and run as their own application with `kind: cfe`</ArticleQuestionnaireAnswer>
    <ArticleQuestionnaireAnswer>They are always deployed together with the Shopware shop in one deployment</ArticleQuestionnaireAnswer>
  </ArticleQuestionnaire>
  <ArticleQuestionnaire>
    <ArticleQuestionnaireQuestion>A frontend build succeeds, but the deployment never becomes ready. The Nuxt server listens on port 4000. What is the most likely explanation?</ArticleQuestionnaireQuestion>
    <ArticleQuestionnaireAnswer>The build failed silently, so the image is empty</ArticleQuestionnaireAnswer>
    <ArticleQuestionnaireAnswer correct>The runtime contract is not checked during the build, and the readiness checks fail because the platform expects port 3000</ArticleQuestionnaireAnswer>
    <ArticleQuestionnaireAnswer>The Shopware shop must be redeployed first so that the frontend can start</ArticleQuestionnaireAnswer>
  </ArticleQuestionnaire>
</ArticleMultipleQuestionnaire>

## Summary

In this learning unit, you learned:

- A Composable Frontend is a separate, headless Node.js application that talks to Shopware through its APIs.
- On Native PaaS, a frontend runs as its own application with `kind: cfe`, in its own repository or in a monorepo next to the shop.
- The frontend must listen on port `3000`, expose `/api/healthz`, and write temporary files only to `/app/tmp`.
- These requirements are checked at deployment, not during the build.
- Fastly purges the frontend cache after each deployment, and response headers decide which pages are cached.

After this learning unit, you can:

- Write an `application.yaml` for a frontend and create the application with the right path.
- Verify before the first rollout that the frontend answers on port `3000` and on `/api/healthz`.
- Read a failed frontend rollout by phase and name the most likely cause.
