1. Home
2. Guides
3. Full-Site Delivery
4. Custom VCL

VCL Snippets are short blocks of VCL logic that can be included directly in your service configurations. They're ideal for adding small sections of code when you don't need more complex, specialized configurations that sometimes require custom VCL. Fastly supports two types of VCL Snippets:

Regular VCL Snippets

Regular VCL Snippets get created as you create versions of your Fastly configurations. They belong to a specific service and any modifications you make to the snippet are locked and deployed when you deploy a new version of that service. You can treat regular snippets like any other Fastly objects because we continue to clone them and deploy them with a service until you specifically delete them. You can create regular snippets using either the Fastly control panel or via the API.

Example use: location-based redirection. Say that you work at a large content publisher and you want to redirect users to different editions of your publication depending on which country their request comes from. Say also that you want the ability to override the edition you deliver to them based on a cookie.

Using regular VCL snippets, you could add a new object with the relevant VCL as follows:

if (req.http.Cookie:edition == "US" || client.geo.country_code == "US") {
  set req.http.Edition = "US";
  set req.backend = F_US;
} elseif (req.http.Cookie:edition == "Europe" || server.region ~ "^EU-" ) {
  set req.http.Edition = "EU";
  set req.backend = F_European;
} else {
  set req.http.Edition = "INT";
  set req.backend = F_International;
}

This would create an Edition header in VCL, but allow you to override it by setting a condition. You would add the Edition header into Vary and then add a false condition (e.g., !reg.url) to your other backends to ensure the correct edition of your publication gets delivered (Remember: VCL Snippets get added to VCL before backends are set.)

Dynamic VCL Snippets

Dynamic VCL Snippets can be modified and deployed any time they're changed. Because they are versionless objects (much like dictionaries or ACLs at the edge), dynamic snippets can be modified independently from service changes. This means you can modify snippet code rapidly without deploying a service version that may not be ready for production. Changes immediately impact all service versions, including the active one. You can only create dynamic snippets via the API.

Example use: blocking site scrapers. Say you wanted to implement some pattern matching against incoming requests to block someone trying to scrape your site. Say also that you've developed a system that looks at all incoming requests and generates a set of rules that can identify scrapers using a combination of the incoming IP address, the browser, and the URL they're trying to fetch. Finally, say that the system updates the rules every 20 minutes.

If, during system updates, your colleagues are also making changes to the rest of your Fastly configuration, you probably don't want the system to automatically deploy the latest version of the service since it might be untested. Instead you could generate the rules as a Dynamic VCL Snippet. Whenever the snippet is updated, all other logic remains the same as the currently deployed version and only your rules are modified.

Limitations of VCL Snippets

• Snippets are limited to 1MB in size by default. If you need to store snippets larger than the limit, contact support.
• Snippets don’t currently support conditions created through the Fastly control panel. You can, however, use if statements in snippet code.
• Snippets cannot currently be shared between services.
• Snippets cannot be nested (e.g., you can't include a snippet into another snippet).

Related content

• Guide to VCL
• Using VCL
• VCL Snippets API documentation