hydro

Resource-oriented APIs for Nuxt and Nitro.

Define an API resource once with a Standard Schema-compatible schema, then let Hydro generate REST endpoints, validation, filtering, pagination, custom operations, RFC 7807 errors, and OpenAPI documentation.

Status: early MVP. Zod is the best-supported schema library for OpenAPI generation today; other Standard Schema libraries can validate requests but may produce generic OpenAPI schemas.

AI context

Use the AI context pack when asking an AI coding tool to add hydro to another Nuxt codebase:

• Full AI context: https://hydro-playground.vercel.app/llms-full.txt
• Short llms.txt: https://hydro-playground.vercel.app/llms.txt
• Repository copy: docs/ai-context.md

Suggested prompt:

I am working in a Nuxt codebase that uses hydro.
Use this context as the source of truth: https://hydro-playground.vercel.app/llms-full.txt
Read nuxt.config.ts, confirm hydro.prefix and hydro.resourcesDir, then match the existing resource style.

Features

• Declarative defineResource() API
• Generated CRUD routes:
  • GET /api/<resource>
  • GET /api/<resource>/:id
  • POST /api/<resource>
  • PATCH /api/<resource>/:id
  • DELETE /api/<resource>/:id
• Query parsing for filters, pagination, sorting, and sparse fieldsets
• Standard Schema validation with Zod-friendly partial updates
• RFC 7807 Problem Details responses with violations[]
• Custom collection and item operations
• Basic relationship resolution for reference and nested writes
• OpenAPI 3.1 JSON and Scalar docs UI

Installation

npm install @muffe/hydro zod

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@muffe/hydro'],
  hydro: {
    prefix: '/api',
    resourcesDir: 'server/resources',
    openapi: {
      enabled: true,
      info: { title: 'Library API', version: '1.0.0' },
    },
  },
})

Define a resource

// server/resources/book.ts
import { defineResource } from '#hydro'
import { z } from 'zod'

interface Book {
  id?: string
  title: string
  authorId?: string
  available: boolean
}

const books: Book[] = []

export default defineResource<Book>({
  name: 'Book',
  path: 'books',
  schema: z.object({
    id: z.string().optional(),
    title: z.string().min(1).max(200),
    authorId: z.string().optional(),
    available: z.boolean().default(true),
  }),
  filters: ['title', 'authorId'],
  provider: {
    async list(ctx) {
      const { offset, itemsPerPage } = ctx.query.pagination
      return {
        items: books.slice(offset, offset + itemsPerPage),
        total: books.length,
      }
    },
    async get(ctx) {
      return books.find(book => book.id === ctx.params.id) ?? null
    },
  },
  processor: {
    async create(ctx) {
      const book = { available: true, ...ctx.input, id: crypto.randomUUID() } as Book
      books.push(book)
      return book
    },
    async update(ctx) {
      const index = books.findIndex(book => book.id === ctx.params.id)
      const next = { ...books[index], ...ctx.input, id: ctx.params.id } as Book
      books[index] = next
      return next
    },
    async delete(ctx) {
      const index = books.findIndex(book => book.id === ctx.params.id)
      if (index >= 0) books.splice(index, 1)
    },
  },
})

Then visit:

• /api/books
• /api/books/123
• /api/_openapi.json
• /api/_docs

Module options

interface HydroOptions {
  prefix?: string // default: '/api'
  resourcesDir?: string // default: 'server/resources'
  auth?: HydroAuthOptions
  openapi?: {
    enabled?: boolean // default: true
    path?: string // default: '<prefix>/_openapi.json'
    docsPath?: string // default: '<prefix>/_docs'
    info?: { title?: string, version?: string, description?: string }
  }
  pagination?: { default?: number, max?: number }
}

Auth

Auth is explicit opt-in. Hydro does not auto-detect auth providers.

The first supported provider is nuxt-auth-utils, declared as an optional peer dependency.

export default defineNuxtConfig({
  modules: ['hydro', 'nuxt-auth-utils'],
  hydro: {
    auth: {
      enabled: true,
      provider: 'nuxt-auth-utils',
      defaultAccess: {
        development: 'public',
        test: 'public',
        production: 'deny',
      },
      session: {
        userId: 'user.id',
        roles: 'user.roles',
        permissions: 'user.permissions',
      },
      docs: {
        access: 'default',
      },
      policies: {
        ownsResource({ auth, entity }) {
          return auth?.userId === (entity as { ownerId?: string } | undefined)?.ownerId
        },
      },
    },
  },
})

Resource-level auth is resource-first, with a default plus operation overrides:

export default defineResource<Book>({
  name: 'Book',
  path: 'books',
  auth: {
    default: 'authenticated',
    operations: {
      list: 'public',
      get: 'public',
      create: { roles: ['editor', 'admin'] },
      update: { policy: 'ownsResource', needsEntity: true },
      delete: { roles: ['admin'] },
    },
  },
  // ...
})

Playground

The playground includes two in-memory demo resources:

• Book: basic CRUD, filters, and an item custom operation (checkout)
• Author: filters, sorting, computed bookCount, nested book creation, and custom operations (feature, spotlight)

Run it locally:

bun install
bun run dev

Open:

http://localhost:3000

Development

Requirements:

• Node.js 22+
• Bun

bun install
bun run dev:prepare
bun run lint
bun run test:types
bun run test
bun run prepack

License

MIT