@api-envelope/fastify

Fastify plugin that decorates reply with ok() and fail() helpers for sending standardized API Envelope responses.

Table of contents

• Why use this
• Install
• Quick start
• Configuration — custom codes
• Type-safe custom codes
• Things to know
• API reference
• FAQ
• License

Why use this

Fastify already encourages structured schemas and consistent responses — apiEnvelopePlugin extends that discipline to the response body itself, so every route returns the same { success, code, status, message, data } shape without repeating reply.code(...).send(...) boilerplate everywhere.

Install

npm install @api-envelope/fastify

Requires fastify in your project (peer dependency). @api-envelope/core and fastify-plugin are installed automatically.

Quick start

import Fastify from "fastify";
import { apiEnvelopePlugin } from "@api-envelope/fastify";

const fastify = Fastify();

await fastify.register(apiEnvelopePlugin);

fastify.get("/users/:id", async (request, reply) => {
  const user = { id: request.params.id, name: "Ada" };
  return reply.ok({ code: "OK", data: user });
});

fastify.get("/users/:id/missing", async (request, reply) => {
  return reply.fail({ code: "NOT_FOUND", message: "User does not exist" });
});

reply.ok() sends 200 { success: true, code: "OK", status: 200, message: "...", data: {...} }. reply.fail() sends 404 { success: false, code: "NOT_FOUND", status: 404, message: "User does not exist" }.

Configuration — custom codes

await fastify.register(apiEnvelopePlugin, {
  codes: [
    { code: "USER_NOT_FOUND", status: 404 },
    { code: "INVALID_TOKEN", status: 401 },
  ],
});

fastify.get("/users/:id", async (request, reply) => {
  if (!userExists) {
    return reply.fail({ code: "USER_NOT_FOUND" });
  }
  return reply.ok({ code: "OK", data: user });
});

Each register() call creates its own isolated code registry — custom codes registered on one Fastify instance never leak into another. Built-in codes (OK, SUCCESS, CREATED, NOT_FOUND, ...) are always available; see @api-envelope/core for the full default list.

Type-safe custom codes

import type { DefaultCode } from "@api-envelope/fastify";

type AppCode = DefaultCode | "USER_NOT_FOUND";

fastify.get("/users/:id", async (request, reply) => {
  return reply.fail<AppCode>({ code: "USER_NOT_FOUND" }); // autocompleted & checked
});

Things to know

• Register with await. fastify.register() is asynchronous; reply.ok/reply.fail won't exist on routes defined before the registration resolves.
• Decorators are per-Fastify-instance. Encapsulated plugins with their own fastify instance need their own register(apiEnvelopePlugin, ...) call if they want reply.ok/reply.fail too.
• reply.code().send() under the hood. The helpers are thin wrappers — you can still call Fastify's own reply methods directly in the same handler if needed.
• Custom codes can override defaults, the same as every other adapter.

API reference

apiEnvelopePlugin (register with fastify.register)

Accepts { codes?: { code: string; status: number }[] }. Decorates reply with ok and fail.

reply.ok({ code, data, message? })

Sends the success envelope with the matching HTTP status already set.

reply.fail({ code, message? })

Sends the failure envelope with the matching HTTP status already set.

Both throw if code hasn't been registered — check for typos in custom codes, or make sure options.codes was passed at register() time.

FAQ

Why is this fastify-plugin-wrapped? So the decorators are visible outside the plugin's own encapsulation context, on the Fastify instance you actually registered it on.

Can I use this alongside Fastify's JSON schema validation? Yes — schema validation happens on the request/reply as usual; reply.ok/ reply.fail only control how you send the final response body.

What if two plugins both register apiEnvelopePlugin with different codes? Each registration is isolated, so that's safe — but if they're on the same Fastify instance, the second registration's decorators simply overwrite the first's.

Does reply.ok/reply.fail return a Promise? Yes, matching Fastify's own reply.send() — await or return it from an async handler.

License

MIT © 2026 ltimsina

Copyright (c) [2026] [ltimsina]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See also

• @api-envelope/core — shared types and the code registry these helpers build on.