Azion Library - The Edge Developer's Toolkit

⚠️ Deprecation Notice - Package Migration

This package (azion) has been migrated to scoped packages under @aziontech/* (e.g., @aziontech/sql, @aziontech/storage, @aziontech/config, and more).

• This package will only receive bug fixes — no new features will be added.
• Maintenance will be discontinued at the end of December 2026.
• We strongly recommend migrating to the new scoped packages to continue receiving updates and new features.

For documentation, see the https://www.azion.com/en/blog/why-azion-is-migrating-to-individual-npm-packages-distributed-monorepo directory.

The Azion Libraries provide a suite of tools to interact with various Azion services, including Products (Purge, SQL, Storage) and Utilities (WASM Image Processor, Cookies). Each library is configurable and supports debug mode and environment variable-based configuration.

These libraries are designed to be versatile and can be used both within and outside of the Azion Runtime environment. When used outside of the Azion Runtime, the libraries will interact with Azion services via REST APIs. However, when used within the Azion Runtime, the libraries will leverage internal runtime capabilities for enhanced performance and efficiency.

Table of Contents

• Installation
• Usage
  • Client
  • Storage
  • SQL
  • Purge
  • Domains
  • Applications
• Utilities
  • Cookies
  • Jwt
  • WASM Image Processor
  • Utils
• AI
• Types
• AzionConfig
• Contributing

Installation

Install the package using npm or yarn:

npm install azion

or

yarn add azion

Usage

Using the Client vs. Independent Package Functions

The Azion client provides a unified interface to interact with all products and services. You can use the client to access and manage all functionalities across Storage, SQL, Purge, and more. When using the client, you can pass configurations (e.g., token, debug) explicitly as parameters.

import { createClient } from 'azion';

const client = createClient({ token: 'your-api-token', debug: true });

// Example: Creating a database via the client
const { data: newDatabase, error } = await client.sql.createDatabase('my-new-database');
if (data) {
  console.log(`Database created with ID: ${newDatabase.id}`);
} else {
  console.error('Failed to create database', error);
}

Alternatively, if you prefer to use individual functions directly from each package, you need to configure tokens and settings via environment variables (e.g., using a .env file). Each module has its own internal client that manages the interaction.

Example with explicit client for a specific module:

import { createClient, StorageClient } from 'azion/storage';

const client: StorageClient = createClient({ token: 'your-api-token', debug: true });

const { data, error }: AzionStorageResponse<AzionBucket> = await client.createBucket({
  name: 'my-new-bucket',
  workloads_access: 'read_only',
});

if (data) {
  console.log(`Bucket created with name: ${data.name}`);
} else {
  console.error('Failed to create bucket', error);
}

You can also use individual functions without any client by importing them directly from the package. This approach requires environment variables for configuration:

import { createDatabase } from 'azion/sql';

const { data, error } = await createDatabase('my-new-database', { debug: true });
if (data) {
  console.log(`Database created with ID: ${data.id}`);
} else {
  console.error('Failed to create database', error);
}

More information on specific functionalities and usage can be found in the README file of each package (e.g., Storage README, SQL README, etc.).

This flexibility allows you to either manage everything through the client for simplicity or call specific functions from each package with more control over environment configurations.

Client

The Azion Client provides a unified interface to interact with all Azion services.

Examples

JavaScript:

import { createClient } from 'azion';

const client = createClient({ token: 'your-api-token', debug: true });

// Storage
const { data: newBucket, error } = await client.storage.createBucket({
  name: 'my-new-bucket',
  workloads_access: 'read_only',
});
console.log(`Bucket created with name: ${newBucket.name}`);

const { data: allBuckets, error } = await client.storage.getBuckets();
console.log(`Retrieved ${allBuckets.count} buckets`);

// SQL
const { data: newDatabase, error } = await client.sql.createDatabase('my-new-db');
console.log(`Database created with ID: ${newDatabase.id}`);

const { data: allDatabases, error } = await client.sql.getDatabases();
console.log(`Retrieved ${allDatabases.count} databases`);

// Purge
const { data: purgeResult, error } = await client.purge.purgeURL(['http://example.com/image.jpg']);
console.log(`Purge successful: ${purgeResult.items}`);

TypeScript:

import { createClient } from 'azion';
import type { AzionClient } from 'azion/client';
import type { AzionDatabaseResponse, AzionDatabaseQueryResponse, AzionDatabaseCollection } from 'azion/sql';
import type { AzionStorageResponse, AzionBucket, AzionBucketCollection } from 'azion/storage';
import type { AzionPurgeResponse, AzionPurge } from 'azion/purge';

const client: AzionClient = createClient({ token: 'your-api-token', debug: true });

// Storage
const { data: newBucket, error }: AzionStorageResponse<AzionBucket> = await client.createBucket({
  name: 'my-new-bucket',
  workloads_access: 'read_only',
});
console.log(`Bucket created with name: ${newBucket.name}`);

const { data: allBuckets, error }: AzionStorageResponse<AzionBucketCollection> = await client.getBuckets();
console.log(`Retrieved ${allBuckets.count} buckets`);

// SQL
const { data: newDatabase, error }: AzionDatabaseResponse<AzionDatabase> = await client.sql.createDatabase('my-new-db');
console.log(`Database created with ID: ${newDatabase.id}`);

const { data: allDatabases, error }: AzionDatabaseResponse<AzionDatabaseCollections> = await client.sql.getDatabases();
console.log(`Retrieved ${allDatabases.count} databases`);

// Purge
const { data: purgeResult, error }: AzionPurgeResponse<AzionPurge> = await client.purge.purgeURL([
  'http://example.com/image.jpg',
]);
console.log(`Purge successful: ${purgeResult.items}`);

Types

The Types package provides global TypeScript types that are used across Azion platform, ensuring consistency and reducing redundancy throughout the codebase.

⚠️ These types are specifically tailored for Azion Runtime environments.

Available Types

• Metadata
  Represents metadata information for requests, including GeoIP data, remote address, server protocol, and TLS information.

• FetchEvent
  Represents the FetchEvent interface, which includes the request object and methods to handle fetch events within the Azion Runtime.

• FirewallEvent
  Represents the FirewallEvent interface, including methods to manage firewall events such as denying, dropping, or continuing a request.

Read more in the Types README.

Config

The Config library provides methods to configure and validate options for the Azion platform.

Examples

JavaScript:

This is the first example using JSDoc to provide type information:

/** @type {import('azion').AzionConfig} */
const config = {
  build: {
    // Build configuration
    bundler: 'esbuild',
    entry: './src/index.js',
    preset: 'react',
    polyfills: true,
  },
  workloads: [
    {
      name: 'my-production-workload',
      active: true,
      infrastructure: 1,
      domains: ['example.com'],
      workloadDomainAllowAccess: false,
      protocols: {
        http: {
          versions: ['http1', 'http2'],
          httpPorts: [80],
          httpsPorts: [443],
        },
      },
    },
  ],
  connectors: [
    {
      name: 'My Origin',
      type: 'http',
      active: true,
      attributes: {
        addresses: [
          {
            address: 'origin.example.com',
            weight: 100,
          },
        ],
        connectionOptions: {
          protocolPolicy: 'https',
        },
      },
    },
  ],
  applications: [
    {
      name: 'My App',
      active: true,
      cache: [
        {
          name: 'Default Cache',
          browser: { maxAgeSeconds: 3600 },
          edge: { maxAgeSeconds: 7200 },
        },
      ],
      rules: [
        {
          name: 'Example Rule',
          phase: 'request',
          criteria: [
            {
              variable: 'request_uri',
              operator: 'matches',
              conditional: 'if',
              input_value: '/api/*',
            },
          ],
          behaviors: [
            {
              type: 'set_origin',
              attributes: {
                name: 'My Origin',
              },
            },
          ],
        },
      ],
    },
  ],
  purge: [
    {
      type: 'url',
      urls: ['https://example.com/path/to/purge'],
    },
  ],
  networkList: [
    {
      id: 12345,
      listType: 'ip_cidr',
      listContent: ['10.0.0.1'],
    },
  ],
  firewall: {
    name: 'My Firewall',
    active: true,
    rules: [
      {
        name: 'Block Suspicious IPs',
        behaviors: [
          {
            type: 'deny',
          },
        ],
      },
    ],
  },
  waf: [
    {
      name: 'My WAF',
      active: true,
      engineSettings: {
        useGeolocation: true,
        useReputation: true,
        thresholds: {
          sql_injection: 'high',
          cross_site_scripting: 'medium',
        },
      },
    },
  ],
  // Other configurations...
};

export default config;

This is the second example using the defineConfig function to enforce types and provide configuration:

import { defineConfig } from 'azion';

const config = defineConfig({
  build: {
    // Advanced build configuration options
    bundler: 'esbuild',
    entry: './src/index.js',
    preset: {
      config: {
        /* custom configuration */
      },
      metadata: {
        name: 'custom-preset',
        registry: 'my-registry',
      },
      handler: async (event) => {
        // Custom handler
        return new Response('Hello World');
      },
    },
    polyfills: true,
    extend: (config) => {
      // Customize bundler configuration
      return {
        ...config,
        // Specific configurations
      };
    },
    memoryFS: {
      injectionDirs: ['./src/inject'],
      removePathPrefix: './src',
    },
  },
  // Other configurations...
});

export default config;

Here's a more advanced example using preset customization with TypeScript:

import { defineConfig } from 'azion';
import type { AzionBuildPreset, AzionPrebuildResult, BuildContext, BuildConfiguration } from 'azion/config';
import { Next } from 'azion/presets';

export default defineConfig({
  build: {
    preset: {
      ...Next,
      config: {
        ...Next.config,
        bundler: 'esbuild',
        extend: (config) => {
          config.define = {
            ...config.define,
            'global.customFeature': 'JSON.stringify(true)',
            'process.env.CUSTOM_VAR': 'JSON.stringify("value")',
          };
          return config;
        },
      },
      prebuild: async (config: BuildConfiguration, ctx: BuildContext): Promise<AzionPrebuildResult> => {
        // Your custom prebuild logic here
        console.log('Running custom prebuild with context:', ctx);

        // Return prebuild result with custom configurations
        return {
          filesToInject: ['./src/custom-file.js'],
          injection: {
            globals: {
              _ENTRIES: 'window._ENTRIES = {}',
              AsyncLocalStorage: 'globalThis.AsyncLocalStorage = class {}',
            },
            entry: '// Custom entry code\nconsole.log("Custom initialization");',
            banner: '/* Custom banner comment */',
          },
          bundler: {
            defineVars: {
              __CONFIG__: JSON.stringify({ customSetting: true }),
              __BUILD_METADATA__: JSON.stringify({ version: '1.0.0', buildTime: Date.now() }),
            },
            plugins: [],
          },
        };
      },
      postbuild: async (config: BuildConfiguration, ctx: BuildContext): Promise<void> => {
        // Your custom postbuild logic here
        console.log('Build completed with output:', config.baseOutputDir);
      },
    },
    // Other build configurations
    entry: './src/index.ts',
    polyfills: true,
    memoryFS: {
      injectionDirs: ['./src/inject'],
      removePathPrefix: './src',
    },
  },
  // Workloads,  connectors, and other configurations...
});

Read more in the AzionConfig README.

Presets

The Presets package provides pre-configured presets for different frameworks and libraries to simplify the development process.

Read more in the Presets README.

Contributing

Feel free to submit issues or pull requests to improve the functionality or documentation.