@bernierllc/nevar-nextjs

Next.js middleware, route handler wrapper, API routes, and discovery endpoints for the Nevar rules engine.

Installation

npm install @bernierllc/nevar-nextjs

Usage

Middleware

Auto-emit Nevar triggers on matching routes:

import { createNevarMiddleware } from '@bernierllc/nevar-nextjs';

const middleware = createNevarMiddleware(nevar, {
  routes: {
    '/api/checkout': { triggerKey: 'checkout.started' },
    '/api/signup': {
      triggerKey: 'user.signup',
      payloadExtractor: (req) => ({ url: req.url }),
    },
  },
});

withNevar

Wrap a route handler with Nevar context:

import { withNevar } from '@bernierllc/nevar-nextjs';

export const POST = withNevar(nevar, async (req, { emit, preview }) => {
  const body = await req.json();
  const result = await emit('order.placed', body);
  return new Response(JSON.stringify(result));
});

API Routes

Create CRUD endpoints for rules:

import { createNevarApiRoutes } from '@bernierllc/nevar-nextjs';

const { GET, POST, PATCH, DELETE } = createNevarApiRoutes(nevar, {
  auth: async (req) => checkApiKey(req.headers),
});

export { GET, POST, PATCH, DELETE };

Discovery Routes

Expose operators, triggers, and actions for UI consumption:

import { createDiscoveryRoutes } from '@bernierllc/nevar-nextjs';

const discovery = createDiscoveryRoutes(nevar);

// Mount at /api/nevar/operators, /api/nevar/triggers, /api/nevar/actions
export const operators = discovery.operators;
export const triggers = discovery.triggers;
export const actions = discovery.actions;

API

createNevarMiddleware(engine, config)

Creates Next.js middleware that auto-emits Nevar triggers on matching routes. Configure route-to-trigger mappings and optional payload extractors.

withNevar(engine, handler)

Wraps a Next.js route handler with Nevar context, injecting emit and preview helpers into the handler's second argument.

createNevarApiRoutes(engine, options?)

Creates CRUD route handlers (GET, POST, PATCH, DELETE) for managing rules via REST. Supports an optional auth callback for request authentication.

createDiscoveryRoutes(engine)

Creates route handlers that expose registered operators, triggers, and actions for UI consumption. Returns { operators, triggers, actions } handlers.

Utilities

• extractPathname(req) - Extract the pathname from a request URL
• extractIdFromUrl(req) - Extract a resource ID from a request URL
• jsonResponse(data, status?) - Create a JSON Response object

Error Classes

• NevarNextjsError - Base error for the package
• NevarMiddlewareError - Thrown during middleware execution failures
• NevarApiRouteError - Thrown during API route handler failures
• NevarAuthError - Thrown when authentication fails

Integration Documentation

Logger Integration

This package integrates with @bernierllc/logger for structured logging. Middleware and route handlers log request processing, trigger emissions, and error conditions. Use logger for observability into request-level rule evaluation.

NeverHub Integration

This package supports optional integration with @bernierllc/neverhub-adapter. When NeverHub is available, the Next.js integration can register its middleware and API routes for discovery and monitoring. Graceful degradation is supported when NeverHub is not present.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.