Netlify Edge Adaptor

Qwik City Netlify Edge adaptor allows you to connect Qwik City to Netlify Edge Functions.

Installation

To integrate the netlify-edge adaptor, use the add command:

npm run qwik add netlify-edge

It will automatically install the required dependencies, including the Netlify CLI.

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

└── adaptors/
    └── netlify-edge/
        └── vite.config.ts
└── src/
    └── entry.netlify-edge.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

Dev deploy

To deploy the application for development:

npm run deploy

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

Production deploy

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

Please refer to the Netlify docs for more information on how to deploy your site: Netlify docs

Advanced

Netlify Edge Entry Middleware

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

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

export default createQwikCity({ render, qwikCityPlan });

The compiled middleware will be built in the .netlify/edge-functions directory.

Netlify Edge Functions Declarations

Netlify Edge Functions declarations can be configured to run on specific URL patterns. Each edge function declaration associates one site path pattern with one function to execute on requests that match the path. A single request can execute a chain of edge functions from a series of declarations. A single edge function can be associated with multiple paths across various declarations.

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 Netlify Edge adaptor will generate a .netlify/edge-middleware/manifest.json file, which is used by the Netlify deployment to determine which paths should, and should not, use edge functions.

To override the generated manifest, you can add a declaration to the netlify.toml using the [[edge_functions]] config. For example:

[[edge_functions]]
  path = "/admin"
  function = "auth"

Netlify Request Context

Netlify context is available in endpoint method's platform param:

export const onRequest = async ({ platform }) => {
  platform.log('requested ip:', platform.ip);
};

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

import { type RequestHandlerNetlify } from '@builder.io/qwik-city/middleware/netlify-edge';

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

Environment variables

export const onRequest = async ({ platform }) => {
  platform.log('Vite env read from .dev file', import.meta.env.VITE_DEV);
  platform.log('netlify serverless env read from Netlify UI or CLI', Deno.env.toObject());
  return {};
};

Migration

Previous versions of Qwik City used the @netlify/vite-plugin-netlify-edge plugin. This plugin still works great, but uses a "catch-all" approach, which means all requests will go through the edge functions, to include static files.

The updated adaptor, using the npm run qwik add netlify-edge command, will instead generate a .netlify/edge-functions/manifest.json config at build-time. If you would like to use the new adaptor, you can remove the @netlify/vite-plugin-netlify-edge plugin from the root vite.config.ts file, and the root netlify.toml file.

import { defineConfig } from "vite";
import { qwikVite } from "@builder.io/qwik/optimizer";
import { qwikCity } from "@builder.io/qwik-city/vite";
import tsconfigPaths from "vite-tsconfig-paths";
-import netlifyEdge from "@netlify/vite-plugin-netlify-edge";

export default defineConfig(() => {
  return {
    plugins: [
      qwikCity(),
      qwikVite({
-        ssr: {
-          outDir: "netlify/edge-functions",
-        },
      }),
      tsconfigPaths(),
-      netlifyEdge({
-        functionName: "entry.netlify-edge",
-      }),
    ],
  };
});

Remove the catch-all edge_functions config from netlify.toml

-[[edge_functions]]
-path = "/*"
-function = "entry.netlify-edge"