avvio

library9.2.0jsnpmunverified

Avvio is a robust, reentrant, and graph-based library designed for managing the asynchronous bootstrapping of Node.js applications. It simplifies complex application startup sequences by handling plugin loading order, inter-plugin dependencies, and comprehensive error management automatically. Unlike simpler sequential loaders, Avvio allows plugins to register other plugins, ensuring correct execution flow within deeply nested structures. The current stable version is 9.2.0, with a release cadence of minor and patch updates every few weeks or months, often driven by dependency updates or minor feature enhancements. Its key differentiator is its emphasis on reentrancy and a dependency graph, which guarantees that even deeply nested plugins are initialized in the precise order required, coupled with sophisticated error handling capabilities.

web-framework workflow

npm install avvio

github ↗package ↗

INSTALL

IMPORT

SIG · AVVIO

avvio

web-frameworkjavascriptv9.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

avvio

✓ import avvio from 'avvio'

✗ const avvio = require('avvio')

While CommonJS `require('avvio')` is still prevalent in older Node.js projects and some examples, modern projects should prefer ESM `import avvio from 'avvio'`. The library ships with TypeScript types for both.

Avvio

✓ import { Avvio } from 'avvio'; const app: Avvio<MyApplicationInstance> = avvio(myAppInstance);

The `Avvio` type can be imported from the package for TypeScript users to correctly type the application instance managed by Avvio, allowing for type-safe plugin registration and usage.

use

✓ app.use(myPlugin, options)

✗ app.register(myPlugin, options)

Users familiar with Fastify might mistakenly use `app.register` for Avvio plugins. Avvio's method for registering plugins is `app.use`.

This example demonstrates how to initialize Avvio, register a series of asynchronous plugins including nested ones and those leveraging async/await syntax, and then wait for the application to be fully booted before gracefully closing it.

'use strict' const avvio = require('avvio') const app = avvio() app .use(first, { hello: 'world' }) .after((err, cb) => { if (err) { console.error('Error in after hook:', err); return cb(err); } console.log('after first and second') cb() }) app.use(third) app.ready(function (err) { // the error must be handled somehow if (err) { throw err } console.log('application booted!') // In a real app, you might start listening for requests here // For demonstration, we'll close the app immediately app.close().then(() => console.log('application closed.')).catch(e => console.error('Error closing:', e)); }) function first (instance, opts, cb) { console.log('first loaded', opts) instance.use(second) cb() } function second (instance, opts, cb) { console.log('second loaded') process.nextTick(cb) } // async/await or Promise support async function third (instance, opts) { console.log('third loaded') // Simulating async work await new Promise(resolve => setTimeout(resolve, 50)); }

Debug

Known issues

breakingAvvio v9.0.0 introduced breaking changes by dropping support for several End-of-Life Node.js versions. Applications running on older or unsupported Node.js runtimes will need to upgrade their Node.js environment to use Avvio v9.x or later.

fix

Upgrade your Node.js runtime to a currently supported Long Term Support (LTS) version, typically Node.js 18 or newer, to be compatible with Avvio v9.x and benefit from its latest features and security patches.

affects: >=9.0.0

gotchaPlugins can time out if they take longer than the configured `timeout` option to complete their initialization, leading to an `AVV_ERR_READY_TIMEOUT` error. While the default `timeout` is `0` (disabled), setting it to a non-zero value without careful consideration can cause unexpected startup failures if plugins exceed the configured duration.

fix

Ensure all plugins complete their asynchronous operations promptly. For long-running initialization tasks, consider increasing the `timeout` option during Avvio initialization (e.g., `avvio({}, { timeout: 10000 })`) or refactor plugins to optimize their initialization speed.

affects: >=1.0.0

gotchaWhile Avvio supports both callback-style and Promise-returning (async/await) plugins, mixing them in a way where an `async` function still calls `cb()` can lead to unexpected behavior, double-done situations, or hung applications. It's crucial to be consistent.

fix

Standardize on either callback-based plugins (always invoke `cb()`) or Promise-based plugins (always return a Promise, implicitly or explicitly). If an `async` function is used, ensure it *only* returns a Promise and does not also call `cb()`.

affects: >=7.0.0

breakingPrior to v9.1.0, even synchronous plugins were expected to call a callback to signal completion. Avvio v9.1.0 introduced support for synchronous plugins that *do not* call a callback, meaning older versions would hang indefinitely if a synchronous plugin omitted the callback.

fix

For Avvio versions older than 9.1.0, always call the callback (`cb()`) even for synchronous plugins. For Avvio v9.1.0 and newer, synchronous plugins can simply omit the callback call if they perform no asynchronous operations.

affects: <9.1.0

Errors

Common errors & fixes

AVV_ERR_READY_TIMEOUT: Plugin timed out after Xms

A plugin's initialization function (either its callback or its returned Promise) did not resolve within the `timeout` duration configured during Avvio instantiation.

fix

Increase the `timeout` option when initializing Avvio (e.g., `avvio({}, { timeout: 15000 })`) or, preferably, debug the plugin to identify and resolve performance bottlenecks that are causing the delay.

TypeError: app.register is not a function

Attempting to use `app.register` to add plugins, a method commonly found in the Fastify framework, instead of Avvio's `app.use` method.

fix

Replace `app.register(myPlugin, options)` with `app.use(myPlugin, options)` as Avvio's plugin registration method is named `use`.

TypeError: (0 , avvio_1.default) is not a function

This error typically occurs when using TypeScript or transpiled JavaScript, indicating an incorrect default import from a CommonJS module or an attempt to call the `default` export incorrectly.

fix

Ensure correct ESM import syntax: `import avvio from 'avvio'; const app = avvio();`. If using CommonJS, ensure `const avvio = require('avvio'); const app = avvio();`.

Error: AVV_ERR_HOOK_TIMEOUT: Hook 'after' timed out after Xms

An `after` hook, which runs after a set of plugins, failed to complete its execution (call its callback or resolve its Promise) within the configured timeout duration.

fix

Examine the `after` hook function to identify any long-running or blocking operations. Either optimize the hook's performance, or increase the global `timeout` option if the delay is expected and acceptable.

Upgrade

Version history

9.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fastify/avvio ↗

packagehttps://www.npmjs.com/package/avvio ↗