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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
hapiApiVersion
✓ const hapiApiVersion = require('hapi-api-version');
✗ import hapiApiVersion from 'hapi-api-version';
This plugin is CJS-only and primarily intended for direct registration with a Hapi server. It does not export named members. Modern Hapi versions (v20+) support ESM, but this plugin does not.
Plugin Registration
✓ await server.register({ plugin: require('hapi-api-version'), options: { validVersions: [1, 2], defaultVersion: 2, vendorName: 'mysuperapi' } });
✗ await server.register(hapiApiVersion, { options: { validVersions: [1, 2] } });
The plugin is registered as an object with a `plugin` key referencing the required module, and an `options` object for configuration.
This quickstart demonstrates setting up a Hapi server, registering the hapi-api-version plugin with basic options, and defining both versioned and unversioned routes. It shows how to access the detected API version from `request.pre.apiVersion` to serve different data based on the client's requested version.
'use strict';
const Hapi = require('@hapi/hapi');
const hapiApiVersion = require('hapi-api-version');
const init = async function () {
try {
const server = new Hapi.server({ port: 3000 });
await server.register({
plugin: hapiApiVersion,
options: {
validVersions: [1, 2],
defaultVersion: 2,
vendorName: 'mysuperapi'
}
})
server.route({
method: 'GET',
path: '/users',
handler: function (request, h) {
const version = request.pre.apiVersion;
if (version === 1) {
return [{ name: 'Peter Miller' }];
}
return [{ firtname: 'Peter', lastname: 'Miller' }];
}
});
server.route({
method: 'GET',
path: '/loginStatus',
handler: function (request, h) {
return { loggedIn: true };
}
});
await server.start();
console.log('Server running at:', server.info.uri);
}
catch (err) {
console.error('Server startup error:', err);
process.exit(1);
}
};
init();
Debug
Known issues
breakingThis plugin is strictly compatible with Hapi.js versions 17.x.x. It is not maintained for or compatible with newer Hapi versions (e.g., v20, v21+), which have introduced significant breaking changes and ESM support.fixFor modern Hapi.js (v20+), consider alternative API versioning strategies or a different plugin. Migrating to a newer Hapi version will require finding a new versioning solution or implementing custom logic.
affects: >=3.0.0 (with Hapi >= v18), current version (for Hapi >= v20)
gotchaThe plugin relies on `accept` headers (with `vendorName`) or a custom header (default `api-version`) to determine the requested API version. If neither is present, it defaults to the `defaultVersion` specified in the options. Clients must correctly provide one of these headers.fixEnsure client applications send either an `Accept` header in the format `application/vnd.<vendorName>.v<version>+json` or a custom header like `api-version: <version>`. For example, `Accept: application/vnd.mysuperapi.v1+json` or `Api-Version: 1`.
affects: >=1.0.0
gotchaThe `hapi-api-version` plugin achieves versioning by internally rewriting requested URLs (e.g., `/users` to `/v1/users`). Developers defining versioned routes must ensure their route paths match this rewritten format (e.g., `/v1/users` and `/v2/users`) for the plugin to function correctly.fixWhen defining version-specific routes, structure your `path` options to include the version (e.g., `/v{version}/resource`). The plugin will then map the unversioned incoming request to the correct internal versioned path. affects: >=1.0.0
deprecatedThe package `hapi-api-version` has not been updated in 7 years. Its last stable version (2.3.1) targets Hapi.js v17.x. This indicates the package is effectively abandoned and not maintained for contemporary Node.js or Hapi.js versions.fixAvoid using this package in new Hapi.js projects. For existing projects, consider migrating to a newer, actively maintained Hapi.js version and finding an alternative API versioning solution that is compatible with Hapi v20+ or v21+.
affects: All versions
Errors
Common errors & fixes
Cannot read properties of undefined (reading 'register') or server.register is not a function
Attempting to use a Hapi.js version incompatible with the plugin's API, or incorrect plugin registration syntax.
fixEnsure you are using `@hapi/hapi` version `17.x.x` as a peer dependency, and that `server.register` is called with an object containing a `plugin` key set to the required module and an `options` key. Check Hapi's migration guide if moving between major versions.
Error: Plugin options validation failed
Missing or invalid required options during plugin registration, such as `validVersions`, `defaultVersion`, or `vendorName`.
fixProvide all required options (`validVersions` as an array of integers, `defaultVersion` as an integer within `validVersions`, and `vendorName` as a string) during plugin registration. Refer to the plugin's documentation for option specifics.
UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: X)
Hapi server startup or plugin registration failed silently due to an unhandled promise rejection, often related to port conflicts or other initialization errors.
fixWrap your `init` function call or the `server.start()` and `server.register()` calls in a `try...catch` block to properly log and handle errors during server initialization. Ensure the port is not already in use.
Audit
Dependencies
@hapi/hapirequiredPeer dependency, required for the plugin to function within a Hapi.js server. Specifically targets Hapi v17.x.x.