Configurapi HTTP Handler

1.4.2 verified Sat Apr 25 auth: no javascript

Configurapi request handlers for HTTP, version 1.4.2. Provides middleware and utilities to validate and process HTTP requests against Configurapi configuration schemas. Designed for Node.js HTTP servers (Express, Fastify, etc.). Enables seamless integration of configuration validation in HTTP request pipelines. Released as needed; no active update cadence. Differentiators: lightweight, focused solely on HTTP handling for Configurapi.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported. ↓

cause Using CommonJS require() to import an ES module package.

fix

Use import statement or set type: 'module' in package.json.

error TypeError: handler is not a function ↓

cause Incorrect import of default export instead of named export.

fix

Use import { createHandler } from 'configurapi-handler-http' (named import).

error ConfigurapiSchemaError: Invalid schema at path '/' ↓

cause Provided schema does not conform to Configurapi schema specification.

fix

Ensure schema is constructed using configurapi's schema builder.

error Cannot read properties of undefined (reading 'name') ↓

cause Request body not parsed before handler, or validated body accessed incorrectly.

fix

Add body-parsing middleware and use req.validatedBody instead of req.body.

Warnings

breaking ESM-only: CommonJS require() will throw an error. Use import syntax. ↓

fix Use ES module import or enable ESM in your project (type: 'module' in package.json).

gotcha Schema must be a valid Configurapi schema object; plain JSON Schema may not work if incompatibilities exist. ↓

fix Ensure schema is created using configurapi's schema builder or is strictly compliant.

deprecated `createHandler` second argument should be an async function to properly handle errors. ↓

fix Wrap your handler logic in async/await or return a promise.

gotcha Request body must be parsed before middleware (e.g., using express.json()). ↓

fix Add body-parsing middleware before the Configurapi handler.

breaking Version 1.x uses Configurapi v2 API; incompatible with v1 schemas. ↓

fix Upgrade to configurapi v2 and update schema definitions accordingly.

Install

npm install configurapi-handler-http

yarn add configurapi-handler-http

pnpm add configurapi-handler-http

Imports

default

wrong

const configurapiHttp = require('configurapi-handler-http')

correct

import configurapiHttp from 'configurapi-handler-http'

ESM-only package; CommonJS require is not supported.

createHandler

wrong

import createHandler from 'configurapi-handler-http'

correct

import { createHandler } from 'configurapi-handler-http'

Named export; default export is the entire module object.

validateRequest

wrong

const { validateRequest } = require('configurapi-handler-http')

correct

import { validateRequest } from 'configurapi-handler-http'

ESM only; named export.

ConfigurapiHttpError

wrong

import ConfigurapiHttpError from 'configurapi-handler-http'

correct

import { ConfigurapiHttpError } from 'configurapi-handler-http'

Named export for error class.

RequestValidator

import { RequestValidator } from 'configurapi-handler-http'

Named export for custom validator class.

Quickstart

Creates an Express handler that validates request body against a Configurapi schema and responds with a greeting.

import { createHandler } from 'configurapi-handler-http';
import express from 'express';

const app = express();
app.use(express.json());

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  },
  required: ['name']
};

const handler = createHandler(schema, (req, res) => {
  res.json({ message: `Hello, ${req.validatedBody.name}!` });
});

app.post('/greet', handler);
app.listen(3000);
console.log('Server running on port 3000');