Config

Azion Lib functions of the @aziontech/config package that type an azion.config.js configuration, turn it into a manifest, and read a manifest back.

Last updated

View as Markdown Agent setup

The @aziontech/config package is the Azion Lib library for the project configuration that the Azion CLI reads from azion.config.js. Its functions type a configuration object, turn it into a manifest, and turn a manifest back into a configuration object. The functions are synchronous, take no token, and run in Node.js.

For every key and property of the configuration object, with its type, refer to Configuration reference.

Install the package:

npm install @aziontech/config

The samples on this page are ES modules that run in Node.js, and the TypeScript samples import types with import type. Each sample logs part of its result, and the output under it shows what the sample prints.

defineConfig

Returns the configuration object you pass, unchanged and typed as AzionConfig. defineConfig does not check the values: a configuration with an invalid value, such as an application with name: '', passes through without an error. To find where the Azion CLI checks the values, refer to defineConfig on the azion.config.js page.

function defineConfig(config: AzionConfig): AzionConfig;
ParameterTypeRequiredDescription
configAzionConfigYesThe configuration object.

Returns the same config object.

This sample declares a JavaScript build:

JavaScript
01import { defineConfig } from '@aziontech/config';
02
03const config = defineConfig({
04 build: {
05 entry: './src/index.js',
06 preset: 'javascript',
07 },
08});
09
10export default config;
11console.log(JSON.stringify(config));

Output:

{"build":{"entry":"./src/index.js","preset":"javascript"}}

This sample declares a build, an application with a cache setting, and an Object Storage bucket filled from a local folder:

JavaScript
01import { defineConfig } from '@aziontech/config';
02
03const config = defineConfig({
04 build: {
05 entry: './src/index.js',
06 preset: 'javascript',
07 bundler: 'esbuild',
08 },
09 applications: [
10 {
11 name: 'my-app',
12 active: true,
13 cache: [
14 {
15 name: 'my-cache',
16 browser: { maxAgeSeconds: 3600 },
17 edge: { maxAgeSeconds: 7200 },
18 },
19 ],
20 },
21 ],
22 storage: [
23 {
24 name: 'my-storage',
25 workloadsAccess: 'read_write',
26 dir: './storage',
27 prefix: 'app-data',
28 },
29 ],
30});
31
32export default config;
33console.log(Object.keys(config));

Output:

[ 'build', 'applications', 'storage' ]

A JavaScript file can also declare the type with a JSDoc annotation instead of calling defineConfig:

JavaScript
01/** @type {import('@aziontech/config').AzionConfig} */
02const config = {
03 build: {
04 entry: './src/index.js',
05 preset: 'javascript',
06 },
07};
08
09export default config;
10console.log(JSON.stringify(config));

Output:

{"build":{"entry":"./src/index.js","preset":"javascript"}}

processConfig

Turns a configuration object into a manifest, an object whose keys use snake_case names. In a cache setting, for example, browser.maxAgeSeconds becomes browser_cache.max_age, and edge.maxAgeSeconds becomes modules.cache.max_age.

function processConfig(inputConfig: AzionConfig): any;
ParameterTypeRequiredDescription
inputConfigAzionConfigYesThe configuration object to turn into a manifest.

Returns the manifest, typed any. The manifest holds 13 top-level keys, including the ones the configuration leaves out: build, purge, network_list, waf, storage, firewall, functions, applications, connectors, workloads, workload_deployments, custom_pages, and kv.

The manifest also carries settings that the configuration does not declare. In the sample below, the application declares a cache setting and no applicationAcceleratorEnabled, and the manifest sets application_accelerator.enabled to true.

This sample turns a configuration with one application into a manifest, then prints the manifest keys and the application:

TypeScript
01import { processConfig } from '@aziontech/config';
02import type { AzionConfig } from '@aziontech/config';
03
04const config: AzionConfig = {
05 build: { entry: './src/index.js', preset: 'javascript' },
06 applications: [{ name: 'my-app', cache: [{ name: 'my-cache', browser: { maxAgeSeconds: 3600 }, edge: { maxAgeSeconds: 7200 } }] }],
07};
08
09const manifest = processConfig(config);
10console.log(Object.keys(manifest));
11console.log(JSON.stringify(manifest.applications, null, 1));

Output:

Text
01[
02 'build',
03 'purge',
04 'network_list',
05 'waf',
06 'storage',
07 'firewall',
08 'functions',
09 'applications',
10 'connectors',
11 'workloads',
12 'workload_deployments',
13 'custom_pages',
14 'kv'
15]
16[
17 {
18 "name": "my-app",
19 "active": true,
20 "debug": false,
21 "modules": {
22 "cache": {
23 "enabled": true
24 },
25 "functions": {
26 "enabled": false
27 },
28 "application_accelerator": {
29 "enabled": true
30 },
31 "image_processor": {
32 "enabled": false
33 }
34 },
35 "cache_settings": [
36 {
37 "name": "my-cache",
38 "browser_cache": {
39 "behavior": "override",
40 "max_age": 3600
41 },
42 "modules": {
43 "cache": {
44 "behavior": "override",
45 "max_age": 7200,
46 "stale_cache": {
47 "enabled": false
48 },
49 "large_file_cache": {
50 "enabled": false,
51 "offset": 1024
52 },
53 "tiered_cache": {
54 "enabled": false
55 }
56 },
57 "application_accelerator": {
58 "cache_vary_by_method": [],
59 "cache_vary_by_querystring": {
60 "behavior": "ignore",
61 "fields": [],
62 "sort_enabled": false
63 },
64 "cache_vary_by_cookies": {
65 "behavior": "ignore",
66 "cookie_names": []
67 },
68 "cache_vary_by_devices": {
69 "behavior": "ignore",
70 "device_group": []
71 }
72 }
73 }
74 }
75 ]
76 }
77]

convertJsonConfigToObject

Turns a manifest, passed as a JSON string, into a configuration object with camelCase keys. The function checks the manifest first, and it throws when the manifest lacks any of build, applications, workloads, and workload_deployments.

function convertJsonConfigToObject(config: string): AzionConfig;
ParameterTypeRequiredDescription
configstringYesThe manifest as a JSON string.

Returns an AzionConfig object. A manifest that fails the check throws an Error; the message is in Errors.

This sample reads the manifest that azion build writes to .edge/manifest.json in the project folder, and prints the keys and the workloads of the configuration:

TypeScript
01import { readFileSync } from 'node:fs';
02import { convertJsonConfigToObject } from '@aziontech/config';
03
04// .edge/manifest.json is the manifest that `azion build` writes
05const manifestJson: string = readFileSync('.edge/manifest.json', 'utf8');
06
07const config = convertJsonConfigToObject(manifestJson);
08console.log(Object.keys(config));
09console.log(JSON.stringify(config.workloads));

Output:

Text
01[ 'build', 'firewall', 'functions', 'applications', 'workloads' ]
02[{"name":"$WORKLOAD_NAME","active":true,"infrastructure":1,"workloadDomainAllowAccess":true,"domains":[],"tls":{"certificate":null,"ciphers":null,"minimumVersion":"tls_1_3"},"protocols":{"http":{"versions":["http1","http2","http3"],"httpPorts":[80],"httpsPorts":[443],"quicPorts":[443]}},"deployments":[{"name":"$DEPLOYMENT_NAME","current":true,"active":true,"strategy":{"type":"default","attributes":{"application":"$APPLICATION_NAME","firewall":null,"customPage":null}}}]}]

The output keeps the placeholders that the manifest holds, such as $WORKLOAD_NAME and $APPLICATION_NAME.

This sample passes a manifest that holds only workloads, and prints the message of the error the function throws:

JavaScript
01import { convertJsonConfigToObject } from '@aziontech/config';
02
03const manifestJson = { workloads: [{ name: 'my-workload', active: true, domains: ['example.com'] }] };
04try {
05 console.log(convertJsonConfigToObject(JSON.stringify(manifestJson)));
06} catch (err) {
07 console.log(err.message);
08}

Output:

Text
01⛔️ Azion Configuration Validation Failed
02--------------------------------------------------
03📍 Error #1:
04 Message: The 'build', 'applications', 'workloads', and 'workload_deployments' fields are required in the manifest.
05--------------------------------------------------

Errors

convertJsonConfigToObject throws an Error when the manifest fails its check. The message numbers each problem and gives its text after Message:.

MessageCauseWhat to do
The 'build', 'applications', 'workloads', and 'workload_deployments' fields are required in the manifest.The JSON string lacks at least one of the four keys.Pass a complete manifest, such as the .edge/manifest.json file that azion build writes.

defineConfig throws no error for an invalid value, because it does not check values.

Types

The package exports AzionConfig and the type of each of its keys, such as AzionBuild, AzionApplication, and AzionWorkload. Import them with import type.

AzionConfig

The configuration object that every function on this page takes or returns. Every key is optional. Each type links to its properties on the azion.config.js page.

PropertyTypeRequiredDescription
buildAzionBuildNoHow the project is built.
applicationsAzionApplication[]NoThe applications, with their cache settings, rules, and function instances.
functionsAzionFunction[]NoThe functions.
connectorsAzionConnector[]NoThe connectors, of type http, storage, or live_ingest.
storageAzionBucket[]NoThe Object Storage buckets and the local folders whose files go into them.
firewallAzionFirewall[]NoThe firewalls, with their rules.
networkListAzionNetworkList[]NoThe network lists, of type ip_cidr, asn, or countries.
purgeAzionPurge[]NoThe URLs, cache keys, or wildcards to purge.
wafAzionWaf[]NoThe Web Application Firewall (WAF) configurations.
workloadsAzionWorkload[]NoThe workloads that serve the applications on domains.
customPagesAzionCustomPage[]NoThe custom error pages.
kvAzionKV[]NoThe KV Store namespaces.
Azion Lib

The libraries Azion Lib ships and the package each one comes from.

azion.config.js

The file names the CLI reads, every configuration key, and the migration from a v3 configuration.

Azion CLI build

The command that builds a project and writes the manifest to the .edge folder.

Azion CLI config

The commands that create azion.json, apply the resources of an azion.config file, and delete the resources azion.json lists.