azion.config.js

azion.config.js is the project configuration file that the Azion CLI reads to build and deploy a project. It is a JavaScript module whose default export, optionally wrapped in defineConfig(...), declares the build settings and the resources the project needs on Azion, such as applications, workloads, connectors, functions, and firewalls. azion build builds the project with it, azion deploy deploys it, and azion dev runs it locally.

File names and where the CLI reads them

The CLI looks for the configuration file in the project folder under seven names, in this order, and reads the first one it finds: azion.config.ts, azion.config.mts, azion.config.cts, azion.config.js, azion.config.mjs, azion.config.cjs, and azion.config.json. The file can therefore be TypeScript, an ES module, a CommonJS module, or JSON.

The CLI commands that set up a project write the file for you, and the extension depends on the command and the preset:

When a project holds both azion.config.mjs and azion.config.cjs, azion deploy reads and updates azion.config.mjs.

azion deploy also writes into the file it reads. A generated file holds placeholders such as $APPLICATION_NAME and $WORKLOAD_NAME, and the first deploy replaces each one with the project name. On a static site, every deploy replaces the storage prefix with another value and prints the change:

defineConfig

defineConfig comes from the @aziontech/config package, which the generated files name: install it as a development dependency with npm install -D @aziontech/config. The function takes your configuration object and returns the same object unchanged. It gives your editor the configuration types for completion and type checking, and it does not check the values.

This file declares a JavaScript build through defineConfig:

The check happens in the build. Before it writes .edge/manifest.json, the build runs validateConfig, from the same package, on the configuration it read. The check names the property path of each value it refuses, such as /applications/0/rules/request/0/criteria/0.

The azion package also exports defineConfig (import { defineConfig } from 'azion'). That package is deprecated in favor of the @aziontech/* packages, and its firewall behavior types differ from the ones the build accepts, so type your file with @aziontech/config.

Configuration reference

The configuration object takes twelve top-level keys, each optional. Every table below lists the properties of one key, with the type the @aziontech/config type declarations give it. A dotted name such as browser.maxAgeSeconds is a property of a nested object; Yes in the Required column then means required whenever the parent object is present.

build

The build object sets how the project is bundled before it is deployed.

Custom preset

A custom preset is an AzionBuildPreset object passed in build.preset. It carries its own configuration and the functions that run around the build.

applications

Each entry of applications declares one application, the resource that holds the delivery settings of a site or an API.

Application cache settings

Each entry of an application’s cache declares one cache setting, which a rule applies with the set_cache_policy behavior.

Application rules

Each entry of rules.request or rules.response declares one rule of the application’s Rules Engine. A rule runs its behaviors when its criteria match.

Rule criteria

Each criterion of an application rule compares a variable with a value. The variables an application rule accepts are in Rule variables, and the operators in Comparison operators.

Rule behaviors

Each behavior of an application rule is an object with a type and, for most types, an attributes object. A value that takes a name or an ID refers to a resource declared in the same file by its name, or to an existing resource by its ID.

Device groups

Each entry of an application’s deviceGroups declares one device group.

Function instances

Each entry of an application’s functionsInstances attaches a function to the application, so that a run_function behavior can run it.

functions

Each entry of functions declares one function and the file that holds its code.

connectors

Each entry of connectors declares one connector. The type selects the shape of attributes: http and live_ingest take addresses and connection options, and storage takes a bucket.

HTTP and Live Ingest connector attributes

An http or live_ingest connector takes the same attributes object.

Connector addresses

Each entry of attributes.addresses is one address of an http or live_ingest connector.

Connection options

The attributes.connectionOptions object of an http or live_ingest connector sets how it connects to its addresses.

Connector modules

The attributes.modules object of an http or live_ingest connector turns the load balancer and origin shield on or off.

Storage connector attributes

A storage connector reads from an Object Storage bucket.

storage

Each entry of storage declares one Object Storage bucket and the local folder whose files go into it.

firewall

Each entry of firewall declares one firewall.

Firewall rules

Each entry of a firewall’s rules declares one rule of the firewall’s Rules Engine. Unlike an application rule, a firewall rule takes a flat array of criteria.

Firewall rule criteria

Each criterion of a firewall rule compares a firewall variable with a value. The variables a firewall rule accepts are in Firewall rule variables.

Firewall rule behaviors

Each behavior of a firewall rule is an object with a type and, for most types, an attributes object.

Firewall function instances

Each entry of a firewall’s functionsInstances attaches a function to the firewall.

networkList

Each entry of networkList declares one network list.

purge

Each entry of purge declares one purge of cached content.

waf

Each entry of waf declares one Web Application Firewall (WAF) configuration, which a firewall rule applies with the set_waf behavior.

Threat thresholds

Each entry of engineSettings.attributes.thresholds sets how sensitive the WAF is to one threat type. For what the levels mean, refer to Scoring and modes.

workloads

Each entry of workloads declares one workload, which serves an application on its domains.

Workload deployments

Each entry of a workload’s deployments sets which application, firewall, and custom page the workload serves.

customPages

Each entry of customPages declares one set of custom pages, the pages Azion returns in place of an error response.

Custom page entries

Each entry of a custom page set’s pages maps one error code to a page that a connector serves.

kv

Each entry of kv declares one KV Store namespace.

Rule variables

Application rules and firewall rules evaluate different sets of variables in their criteria.

Application rule variables

An application rule criterion takes its variable wrapped in ${}, such as ${uri}; the build refuses a bare name. These variables are available in both phases:

These variables are available in the request phase only:

These variables are available in the response phase only:

A variable can also name one argument, cookie, or header with a prefix followed by the name:

Firewall rule variables

A firewall rule criterion accepts its own set of 15 variables, with or without ${}: client_certificate_validation, header_accept, header_accept_encoding, header_accept_language, header_cookie, header_origin, header_referer, header_user_agent, host, network, request_args, request_method, request_uri, scheme, and ssl_verification_status. The build refuses any other variable in a firewall rule, including remote_addr and the prefixed names.

Comparison operators

The operator of an application or firewall criterion takes one of these values. An operator that takes a value needs an argument:

Examples

The two files below are the file that azion init generates for a function project and a file written by hand for azion config apply.

Function project generated by azion init

azion init with the JavaScript preset writes this azion.config.mjs. It declares a function, an application whose rule runs the function on every request, and a workload that serves the application:

After the first azion deploy, every $ placeholder in the file holds the project name, such as my-function.

Configuration applied with azion config apply

This azion.config.mjs declares an application with one cache setting and a rule that applies it, and a workload that serves the application:

Run azion config apply in the project folder to create the resources the file declares:

The command creates each resource and prints its ID:

Running azion config apply again with the same file updates the same resources: each line then reads successfully updated and keeps the same ID.

Migrate from a v3 configuration

A configuration written for API v3 keeps its resources in flat top-level keys such as origin, cache, and rules. The v4 configuration moves cache settings and rules inside each application, replaces origins with connectors, and adds workloads to serve the applications. For the platform changes behind the v4 structure, refer to API v4 migration.

Renamed keys

This table maps each v3 key to its v4 place:

Origins to connectors

A v3 origin declared its addresses directly:

The v4 connector holds the addresses, connection options, and modules inside attributes:

Rules with criteria

A v3 rule matched one expression and ran one behavior object:

The v4 rule lives inside an application, matches with groups of criteria, and runs an array of behaviors:

Firewall behaviors

A v3 firewall rule ran one behavior object:

The v4 firewall rule takes an array, so one rule can run several behaviors:

WAF settings

A v3 WAF set a mode and one sensitivity object per threat:

The v4 WAF lists one threshold per threat in engineSettings, and the firewall rule that applies it sets the mode:

Related resources