Cloudflare Pages Adaptor

Qwik City Cloudflare Pages adaptor allows you to connect Qwik City to Cloudflare Pages.

Installation

To integrate the cloudflare-pages adaptor, use the add command:

npm run qwik add cloudflare-pages

The adaptor will add a new vite.config.ts within the adaptors/ directory, and a new entry file will be created, such as:

└── adaptors/
    └── cloudflare-pages/
        └── vite.config.ts
└── src/
    └── entry.cloudflare-pages.tsx

Additionally, within the package.json, the build.server and deploy scripts will be updated.

Production build

To build the application for production, use the build command, this command will automatically run npm run build.server and npm run build.client:

npm run build

Read the full guide here

Deploy to Cloudflare Pages

After installing the integration using npm run qwik add cloudflare-pages, the project is ready to be deployed to Cloudflare Pages. However, you will need to create a git repository and push the code to it.

Please refer to the Cloudflare Pages docs for more information on how to deploy your site.

Notice that you might need a Cloudflare account in order to complete this step!

Advanced

Cloudflare Pages Entry Middleware

When the cloudflare-pages adaptor is added, a new entry file will be created at src/entry.cloudflare-pages.tsx. Below is an example of using the built-in middleware within the entry file.

// src/entry.cloudflare-pages.tsx
import { createQwikCity } from '@builder.io/qwik-city/middleware/cloudflare-pages';
import qwikCityPlan from '@qwik-city-plan';
import render from './entry.ssr';

const onRequest = createQwikCity({ render, qwikCityPlan });

export { onRequest };

The compiled middleware will be built in the server/ directory and can then be used anywhere in the cloudflare pages /functions directory.

// export the compiled middleware where cloudflare pages can find it.
// for example use /functions/[[path]].ts or /functions/_middleware.ts
// to have qwik city handle all requests.
export { onRequest } from '../server/entry.cloudflare-pages';

Cloudflare Pages Function Invocation Routes

Cloudflare Page's function-invocation-routes config can be used to include, or exclude, certain paths to be used by the worker functions. Having a _routes.json file gives developers more granular control over when your Function is invoked.

This is useful to determine if a page response should be Server-Side Rendered (SSR) or if the response should use a static-site generated (SSG) index.html file instead.

By default, the Cloudflare Pages adaptor does not include a public/_routes.json config, but rather it is auto-generated from the build by the Cloudflare adaptor. An example of an auto-generate dist/_routes.json would be:

{
  "include": ["/*"],
  "exclude": [
    "/_headers",
    "/_redirects",
    "/build/*",
    "/favicon.ico",
    "/manifest.json",
    "/service-worker.js",
    "/about"
  ],
  "version": 1
}

In the above example, it's saying all pages should be SSR'd. However, the root static files such as /favicon.ico and any static assets in /build/* should be excluded from the Functions, and instead treated as a static file.

In most cases the generated dist/_routes.json file is ideal. However, if you need more granular control over each path, you can instead provide you're own public/_routes.json file. When the project provides its own public/_routes.json file, then the Cloudflare adaptor will not auto-generate the routes config and instead use the committed one within the public directory.

Context

You may access Cloudflare Page's environment variables in the endpoint method's platform param:

export const onRequest = async ({ platform }) => {
  const secret = platform['SUPER_SECRET_TOKEN'];
};

Additionally, you may import the RequestHandlerCloudflarePages type to have have type completions in your editor.

import { type RequestHandlerCloudflarePages } from '@builder.io/qwik-city/middleware/cloudflare-pages';

export const onGet: RequestHandlerCloudflarePages = ({ platform }) => {
  //...
};