AEM Edge Functions aem-edge-functions

AEM Edge Functions lets you execute JavaScript at the CDN layer, bringing data processing closer to the end user. This reduces latency and enables responsive, dynamic experiences without a round trip to your origin.

Common use cases include:

AEM Edge Functions is compatible with both Edge Delivery Services and AEM as a Cloud Service Java-stack, for AEM Sites customers.

Follow this tutorial for a concrete walk-through for both Edge Delivery Services and AEM as a Cloud Service Java-stack variations.

Key Benefits key-benefits

Prerequisites prerequisites

Setup setup

Install the Adobe CLI install-adobe-cli

Install the Adobe Developer CLI (aio):

npm install -g @adobe/aio-cli

Install the AEM Edge Functions plugin:

aio plugins install @adobe/aio-cli-plugin-aem-edge-functions

Authenticate and configure the plugin for your environment:

aio login
aio aem edge-functions setup

The setup command prompts you to sign in and then select the AEM environment on which you want to use AEM Edge Functions.

Clone the Boilerplate boilerplate

Copy the aem-edge-functions-boilerplate to your own repository, then install dependencies:

npm install

Register Your AEM Edge Function register-your-function

AEM Edge Functions are declared in a YAML configuration file and deployed through the Cloud Manager configuration pipeline.

1. Set Up a Configuration Pipeline configuration-pipeline

Before creating an edge function, ensure that in Cloud Manager, a configuration pipeline exists for your environment (if using the AEM Java-stack), or an Edge Delivery Services pipeline exists if your project is implemented with Edge Delivery Services. See Use Config Pipelines for information about configuring the pipelines.

2. Declare Your Edge Function declare-functions

Create a file named edgeFunctions.yaml in your configuration directory:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
    # add advanced configuration under here

Java-stack environments have 1 edge function and Edge Delivery Services implementations have 3 edge functions. The optional top-level keys are:

See advanced configuration such as configs, secrets, and kvs in the advanced configuration section below.

3. Deploy the Edge Function via Cloud Manager deploy-functions-via-cm

Using Cloud Manager, deploy the pipeline so the edge function is registered at the CDN.

Author, Build and Deploy AEM Edge Function Code build-deploy

Author author

Write your edge function code business logic, using the boilerplate’s src folder as a starting point.

Build build

Package your edge function code for deployment:

aio aem edge-functions build

Deploy deploy

Deploy the packaged edge function code to the named edge function. The function-name argument must match the name value in edgeFunctions.yaml:

aio aem edge-functions deploy <function-name>

Test test

Make sure the edge function works as expected. You can test it at:

edgefunction-pXXXXX-eYYYYY-<function name>.adobeaemcloud.com/<path>

For example, for the AEM Java-stack:

edgefunction-pXXXXX-eYYYYY-my-edge-function.adobeaemcloud.com/weather

or for Edge Delivery Services:

edgefunction-pXXXXX-dYYYYY-my-edge-function.adobeaemcloud.com/weather

This domain prefixed with edgefunction is only for debugging, but must not be referenced for live traffic as it is not guaranteed to be a stable name. To determine the value of dYYYYY, see the output of the deploy command.

Wire into the Content Delivery Flow wiring

Edge function traffic should be sent to the website’s domain, which is typically a custom domain for AEM Java-stack, and must be a custom domain for Edge Delivery Services Sites.

1. Define Origin Selectors origin-selectors

Edge functions are invoked by routing CDN traffic to them via origin selector rules. Add the following to your cdn.yaml configuration file (or create one if it does not exist):

kind: 'CDN'
version: '1'
data:
  originSelectors:
    rules:
      - name: route-weather-to-edge-function
        when: { reqProperty: path, equals: "/weather" }
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function
      - name: route-hello-world-to-edge-function
        when: { reqProperty: path, equals: "/hello-world" }
        action:
          type: selectAemOrigin
          originName: edgefunction-my-edge-function

The origin selector rules let you route traffic to your edge functions based on any condition available in the CDN rules engine, such as a specific path, domain, or request header. Multiple rules can route different paths to the same edge function. See Origin Selectors for the full rule syntax.

2. Deploy the Configuration deploy-to-cdn

Commit cdn.yaml to your Cloud Manager Git repository and trigger the configuration pipeline. Once the pipeline completes successfully, your edge function endpoints are available at:

For debugging, you can reference the edge function at the domain publish-pXXXXX-eYYYYY.adobeaemcloud.com (for the AEM Java-stack) or publish-pXXXXX-dYYYYY.adobeaemcloud.com (for Edge Delivery Services sites). Do not use this domain for production usage as it is not guaranteed to be a stable name. To determine the value of dYYYYY, see the output of the deploy command.

Local Development local-development

Run Locally local-run

Start a local development server at http://127.0.0.1:7676:

aio aem edge-functions serve

See this Compute JavaScript documentation for details on what the local runtime supports.

Test test-localdev

Run the test suite with Mocha:

npm run test

Remote Debugging remote-debugging

Adobe Managed CDN does not expose a remote debugger, but does expose log streaming. Tail the logs for a deployed function to receive console.log output directly in your terminal:

aio aem edge-functions tail-logs <function-name>

Caching and Cache Purging caching

Edge Functions can significantly reduce origin load and improve response times by caching data at the edge. However, caching requires intentional design — particularly in Edge Functions where two independent cache layers are involved:

Browser → AEM CDN (CDN Cache) → AEM Edge Functions (Fetch Cache) → Backend (AEM, APIs, etc.)

Before configuring caching, consider how your content behaves:

Because the CDN and the Edge Function’s internal fetch cache operate independently, a change to underlying data requires deliberate invalidation of both layers. Understanding this architecture is essential for reliable cache management.

For the detailed technical guidance on configuring caching behavior, controlling cache lifetimes, using surrogate keys, and purging cached content, see Caching in AEM Edge Functions.

Limitations limitations

Maximum Outbound Fetch Calls per Invocation max-fetch-calls

AEM Edge Functions enforce a hard limit of 32 backend requests per execution (that is, per incoming request handled by your function). Once this limit is reached, any further fetch() calls fail with the following error:

Requested backend named '…' does not exist

When you see this error and your origin configuration is correct, the most likely cause is that the per-invocation backend request quota has been exhausted. See Fastly Compute resource limits for the full list of platform limits.

Advanced Edge Function Configuration advanced-function-configuration

Origins origins

By default, edge functions can fetch from any origin. To restrict a function to a defined set of origins, declare them under origins in edgeFunctions.yaml:

origins:
  - name: my-origin-name
    domain: example.com

Reference the named origin in your function code using the backend fetch option:

const request = new Request("https://example.com/test");
const response = await fetch(request, { backend: "my-origin-name" });

Edge Function Config Variables function-configuration

Expose environment variables to your functions using the configs key in edgeFunctions.yaml. Values are stored in a config store named config_default:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  configs:
    - key: LOG_LEVEL
      value: DEBUG

Read configuration values in your function code:

import { ConfigStore } from "fastly:config-store";

const config = new ConfigStore('config_default');
const logLevel = config.get('LOG_LEVEL') || 'info';

Edge Function Secret Variables function-secrets

Secrets are referenced, not stored, in edgeFunctions.yaml. The value field must point to a Cloud Manager secret using the ${{SECRET_REFERENCE}} syntax. Define the underlying secret in Cloud Manager first — see Cloud Manager Secret Variables.

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  secrets:
    - key: API_TOKEN
      value: ${{API_TOKEN_SECRET}}

Retrieve secrets in your function code using the SecretStoreManager helper from the boilerplate:

import { SecretStoreManager } from "./lib/config";

const apiToken = await SecretStoreManager.getSecret('API_TOKEN');

Edge Function KV Store function-kv-store

Edge functions can read and write arbitrary key-value data at runtime through a KV store. To enable it, set kvs: true in edgeFunctions.yaml:

kind: "EdgeFunctions"
version: "1"
data:
  functions:
    - name: my-edge-function
  kvs: true

This provisions an empty KV store named kv_default. Populate it at runtime from your edge function code using the Fastly KV Store API:

import { KVStore } from "fastly:kv-store";

const kv = new KVStore('kv_default');

// Read a value
const entry = await kv.get('visit-count');
const count = entry ? Number(await entry.text()) : 0;

// Write a value
await kv.put('visit-count', String(count + 1));

Logging logging

AEM Edge Functions integrates with the AEM Log Forwarding feature. Create a logForwarding.yaml file alongside your edgeFunctions.yaml:

kind: "LogForwarding"
version: "1"
metadata:
  envTypes: ["rde", "dev", "stage", "prod"]
data:
  splunk:
    default:
      enabled: true
      host: "splunk-host.example.com"
      token: "${{SPLUNK_TOKEN}}"
      index: "AEMaaCS"

Use the logger in your function code to write structured log entries:

import { Logger } from "fastly:logger";

const logger = new Logger("customerSplunk");
logger.log(JSON.stringify({
  method: event.request.method,
  url: event.request.url
}));