Azion Bundler - Built for Builders of the Edge

Azion Bundler is a powerful tool designed to build and adapt projects for edge computing. It handles module resolution and applies necessary polyfills through unjs/unenv while providing an abstraction layer over popular bundlers like esbuild and webpack. The tool includes a local development environment for testing and debugging, and processes Infrastructure as Code (IaC) through its manifest system.

Table of Contents

• Azion Bundler - Built for Builders of the Edge
  • Table of Contents
  • Quick Installation
  • Getting Started for Development
  • Using
  • Commands
    • build
    • dev
    • store
    • presets
    • manifest
  • Configuration
  • Build Process Flow
  • Documentation
  • Supported Features
  • Contributing
  • License

Quick Installation

For those who just want to use Azion Bundler in their project without contributing to the development, you can install it directly from npm.

npm install edge-functions

or if you prefer yarn:

yarn add edge-functions

Getting Started for Development

Follow these steps to start using Azion Bundler:

1. Clone the repository: Clone the Azion Bundler repository from GitHub to your local machine.

   git clone https://github.com/aziontech/bundler.git

2. Installation: Navigate to the cloned Azion Bundler directory and install the required dependencies.

   cd bundler
   npm yarn install

3. Install the Azion Bundler CLI globally, which allows you to use it as a command-line tool from anywhere in your system.

   npm install -g

   This command sets up the necessary project structure and configuration files for Azion Bundler.

4. Start developing: Once the project is set up, you can start developing your JavaScript applications or frameworks using the power of Bundler.

Using

See some examples below:

• Build a JavaScript/Node project (back-end)

  ef build

• Build a TypeScript/Node (back-end)

  ef build --preset typescript

• Build a Next.js project

  ef build --preset next

• Build Astro.js project

  ef build --preset astro

• Test your project locally (after build)

  ef dev

Commands

The Azion Bundler CLI provides several commands to help you manage your edge applications:

build

Builds your project for edge deployment.

ef build [options]

Options:
  --entry <string>     Code entrypoint (default: ./main.js or ./main.ts)
  --preset <type>      Preset of build target (e.g., vue, next, javascript)
  --polyfills          Use node polyfills in build (default: true)
  --worker            Enable worker mode with addEventListener signature (default: false)
  --development       Build in development mode (default: false)

dev

Starts a local development environment.

ef dev [entry] [options]

Arguments:
  entry               Specify the entry file (default: .edge/worker.dev.js)

Options:
  -p, --port <port>  Specify the port (default: "3333")

store

Manages store configuration.

ef store <command> [options]

Commands:
  init                Initialize store configuration
  destroy             Remove store configuration

Options:
  --scope <scope>     Project scope (default: "global")
  --preset <string>   Preset name
  --entry <string>    Code entrypoint
  --bundler <type>    Bundler type (webpack/esbuild)
  --polyfills        Use node polyfills in build
  --worker           Enable worker mode

presets

Lists available project presets.

ef presets <command>

Commands:
  ls                  List all available presets

manifest

Manages manifest files for Azion.

ef manifest [action] [options]

Arguments:
  action             Action to perform: "transform" (JSON to JS) or "generate" (config to manifest)
                    (default: "generate")

Options:
  --entry <path>     Path to the input file or configuration file
  --output <path>    Output file/directory path

Examples:
  $ ef manifest transform --entry=manifest.json --output=azion.config.js
  $ ef manifest generate --entry=azion.config.js --output=.edge
  $ ef manifest --entry=azion.config.js --output=.edge

Configuration

The configuration file (azion.config.js or azion.config.ts) offers a robust configuration system for Bundler. With Azion Bundler, you can extend configurations and leverage pre-configured framework presets for immediate use. The tool empowers users to create their own automations and extensions, making it highly customizable for specific project needs.

As the JavaScript engine powering the Azion CLI, it seamlessly integrates with Azion Libraries to read presets and pre-configured bundler settings from azion/bundler and framework presets from azion/presets. The bundler follows a modular architecture with specialized modules like @build, @prebuild, and @postbuild through the build command.

The configuration is divided into two main areas:

• The build property manages all bundler-related settings, including entry points, presets, and build configurations
• Other properties (like domain, origin, cache, rules) are related to Azion CDN and Edge Computing platform settings

While these hooks are pre-configured in framework presets, you can customize them in your azion.config.ts to fit your specific needs. You can either create your own configuration from scratch or extend existing presets. Here's an example of extending the Next.js preset:

import { defineConfig } from 'azion';
import type { AzionPrebuildResult, AzionConfig } 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: AzionConfig, ctx: BuildContext): Promise<AzionPrebuildResult> => {
        // Your custom prebuild logic here
        const result = await doSomething();
        return {
          ...result,
          // Additional prebuild configurations
        }
      }
    }
  }
});

Build Process Flow

1. Preset Resolution (@modules/preset)

   • Resolves preset from string name or custom module
   • Loads built-in presets from azion/presets
   • Validates preset interface

2. Build Config Setup (@modules/config)

   • Resolves configuration priorities in the following order:
     1. CLI arguments (highest priority)
     2. User config file (azion.config.js)
     3. Local store settings
     4. Preset defaults (lowest priority)
   • Sets up bundler configuration
   • Configures build options and extensions

3. Entry Resolution (@modules/entrypoint)

   • Resolves entry point from CLI args, preset, or user config (azion.config.js)
   • Validates file existence

4. Worker Setup (@modules/worker)

   • Converts ESM exports to worker format
   • Injects worker runtime and globals
   • Sets up event listeners

5. Prebuild Phase (@modules/prebuild)

   • Executes preset's prebuild hooks

6. Core Build (@modules/core)

   • Processes bundler configuration (esbuild/webpack)
   • Handles file imports and dependencies
   • Applies polyfills and transformations

7. Postbuild Phase (@modules/postbuild)

   • Executes preset's postbuild hooks

8. Environment Setup (@modules/environment)

   • Creates initial azion.config.js from preset if none exists
   • Merges configurations (user config takes precedence over preset defaults)
   • Stores build settings locally for development and subsequent builds

Documentation

• Nextjs
• Rust/Wasm example
• Emscripten/Wasm example
• Env vars example
• Storage example
• Firewall example

Supported Features

E2E tests run daily in the Bundler Examples to ensure that the presets and frameworks continue to work correctly.

Table:

Test	Status
Next 14 2 15 Middleware	✅
Next 13 5 6 I18n	✅
Next 12 3 4 I18n	✅
Hexo Static	✅
Next 13 5 6 Middleware	✅
Next 12 3 4 Middleware	✅
Next Node Pages 12 3 1	✅
Next 13 5 6 Config	✅
Next 12 3 4 Config	✅
Next Static	✅
Gatsby Static	✅
Next Node Pages 12 3 1 Fs	⚠️
Vue Vite Static	✅
Next 12 Static	⚠️
Astro Static	✅
Qwik Static	✅
Eleventy Static	✅
Simple Js Env Vars	⚠️
React Static	✅
Angular Static	✅
Svelte Static	✅
Preact Static	✅
Stencil Static	✅
Simple Js Network List	⚠️
Vitepress Static	⚠️
Nuxt Static	✅
Vuepress Static	✅
Docusaurus Static	✅
Simple Js Firewall Event	⚠️
Jekyll Static	✅
Simple Js Network List With Firewall	⚠️
Simple Js Esm Worker	⚠️
Simple Js Esm Node	⚠️
Simple Ts Esm	⚠️
Simple Js Esm	⚠️

Last test run date: 03/14/25 03:35:17 AM

Contributing

Check the Contributing doc.

License

MIT