Netlify Edge Handlers: Personalize Content at the CDN Level

Use edge handlers when you want to change page content before it reaches the visitor, without rebuilding your main application. Confirm that your hosting platform supports the required request, response, cookie, and content-rewriting features before you begin.

Why Client-Side Personalization Can Cause Problems

Client-side personalization can show an initial page before replacing it with the intended content. This may create a visible change after the page loads and can make the experience slower on some devices or connections.

If you personalize content at the edge, you can return the revised page as the response. This approach can help avoid a later client-side replacement, but you still need to test caching, cookies, accessibility, and fallback behavior.

Plan the Personalization

Before writing code, define:

• What content you want to change
• Which audience signals you will use
• What the unchanged experience should show
• How you will assign and record each variant
• What should happen when personalization cannot run

Keep the first version small. For example, you could change one call to action for visitors assigned to an experiment group.

The Edge Handler Pipeline

A typical handler receives the incoming request, reads available request data, and obtains the original response. It can then inspect or rewrite the response body and return the revised response.

Your handler may need to work with cookies, headers, location data, or URL parameters. Use only the information you need, and avoid collecting or exposing personal data without a clear purpose.

After changing a response, check whether the page uses a cache. If the page is cached, make sure the cache rules do not return content intended for a different audience.

Build an A/B Testing Engine

Create a handler that assigns visitors to variants and remembers the assignment in a cookie. If no assignment exists, choose a variant, set a cookie, and replace a clearly marked placeholder in the page.

Keep the assignment consistent across page loads. Do not change a visitor’s group randomly after the cookie has been set, unless random reassignment is part of your experiment design.

Test both variants with real page views, but do not treat an early result as conclusive. Decide in advance how long to run the test, which outcome matters, and how you will handle bots, repeat visitors, and incomplete sessions.

Check Deployment and Caching

Place the handler where your hosting platform expects edge functions. Review the deployment documentation rather than assuming that a folder name, configuration entry, or command is correct.

After deployment, check the response directly. Confirm that:

• The assigned variant appears in the returned page
• The assignment cookie is set as intended
• The response has the correct content type
• Cached and uncached requests behave consistently
• The original page remains available if the handler fails

Do not assume that visiting the site from different locations proves the same assignment will be used everywhere. Test the behavior that matters for your audience.

Measure the Experiment

Add an analytics event when the handler serves a variant. Record the variant, page, and relevant session context without sending unnecessary personal information.

Compare the outcomes for the control and treatment groups. Check that assignment happens before the page is displayed and that analytics receives the same variant information that the visitor saw.

Use your analytics platform’s documentation to confirm how events, cookies, consent, and attribution are handled. Your hosting platform’s edge function does not automatically solve client-side tracking or attribution problems.

Plan for Limits and Fallbacks

Ask the vendor about invocation limits, execution limits, response-size limits, caching behavior, and the behavior of a failed handler. Compare those limits with your expected traffic and page size.

If the handler cannot run, return the original response or a deliberate fallback. Make sure the fallback is safe and that visitors are not left with a broken page.

Advanced Personalization

You can combine request headers, URL parameters, and coarse location information to create content segments. Use these signals only when they are necessary and appropriate for the experience.

For example, a site could show a localized call to action for a returning visitor. Avoid making assumptions about a person’s identity, preferences, or location. Provide a clear alternative when the relevant signal is unavailable.

Keep advanced rules separate from the basic experiment handler. This makes it easier to identify whether a problem comes from assignment, content replacement, caching, or analytics.

Questions to Ask the Vendor

• Where does the handler run?
• Can it read the incoming request and modify the response?
• How does the handler interact with the cache?
• What are the execution and response limits?
• What happens when the handler fails?
• Can you test a handler without changing production content?
• How can you inspect logs without exposing personal data?
• Which runtimes and APIs are supported?
• How are deployments versioned and rolled back?

Checklist

• Define the audience and content rules.
• Start with one small experiment.
• Keep assignment consistent.
• Check cache behavior before publishing.
• Provide a fallback page.
• Record the variant shown to each visitor.
• Review logs and analytics after deployment.
• Confirm limits and vendor support before expanding the setup.