@websideproject/nuxt-auto-api

@websideproject/nuxt-auto-api

Schema-driven REST APIs for Nuxt. Register a Drizzle table, declare who may do what, and get list / get / create / update / delete, bulk, aggregations, many-to-many and permission endpoints — plus TanStack Query composables for the client.

• Secure by default — every operation is denied until you declare who may perform it
• Row visibility everywhere — tenant scoping, listFilter, soft delete and objectLevel apply to every route: list, get, update, delete, restore, bulk, aggregate, M2M and ?include=
• Server-owned columns — tenant, soft-delete and audit columns (and the primary key on update, or on create when the database generates it) can never be written by a request body
• Filtering, sorting, keyset pagination, nested includes, aggregations — restricted to columns the caller may read
• Soft delete, cascade and restore, field-level permissions, lifecycle hooks, a plugin system
• SQLite, D1, Turso, Postgres, MySQL, PlanetScale
• Nuxt 4 (and Nuxt 5 nightly)

Install

npx nuxt module add @websideproject/nuxt-auto-api
npm install drizzle-orm better-sqlite3   # Drizzle + your database's driver; auto-api uses this same Drizzle

Quick start

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@websideproject/nuxt-auto-api', './modules/blog'],
})

// server/plugins/database.ts — hand auto-api your Drizzle instance and name the engine
import Database from 'better-sqlite3'
import { drizzle } from 'drizzle-orm/better-sqlite3'
import { initializeDatabase } from '@websideproject/nuxt-auto-api/database'
import * as schema from '../../modules/blog/schema'

export default defineNitroPlugin(() => {
  initializeDatabase(drizzle(new Database('sqlite.db'), { schema }), 'better-sqlite3') // or 'postgres', 'mysql', 'd1', 'turso', 'planetscale'
})

// modules/blog/schema.ts — a Drizzle table, as you'd write it anyway
import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'

export const posts = sqliteTable('posts', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  title: text('title').notNull(),
  published: integer('published', { mode: 'boolean' }).notNull().default(false),
  authorId: text('author_id'),
  createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(() => new Date()),
})

// modules/blog/index.ts — register resources from a module
import { defineNuxtModule, createResolver } from '@nuxt/kit'
import { createModuleImport } from '@websideproject/nuxt-auto-api'

export default defineNuxtModule({
  // Nuxt also loads modules/*/index.ts by itself; the name lets it see the entry in nuxt.config is the same module
  meta: { name: 'blog' },
  setup(_, nuxt) {
    const { resolve } = createResolver(import.meta.url)
    nuxt.hook('autoApi:registerSchema', (registry) => {
      registry.register('posts', {
        schema: createModuleImport(resolve('./schema'), 'posts'),
        authorization: createModuleImport(resolve('./auth'), 'postsAuth'),
      })
    })
  },
})

// modules/blog/auth.ts
import { eq, or } from 'drizzle-orm'
import type { ResourceAuthConfig } from '@websideproject/nuxt-auto-api'

export const postsAuth: ResourceAuthConfig = {
  permissions: {
    read: true, // anyone
    create: ctx => !!ctx.user, // signed-in users
    update: ctx => !!ctx.user,
    delete: 'posts:delete', // callers holding this permission
  },
  // Which rows a caller may see — applied to EVERY route, not only lists.
  listFilter: (posts, ctx) => ctx.user ? or(eq(posts.published, true), eq(posts.authorId, ctx.user.id)) : eq(posts.published, true),
  // Per-row check: anyone may read a visible post; only its author may change or delete it.
  objectLevel: (post, ctx) => ctx.operation === 'list' || ctx.operation === 'get' || post.authorId === ctx.user?.id,
}

That's GET/POST /api/posts, GET/PATCH/DELETE /api/posts/:id, /api/posts/bulk, /api/posts/aggregate, /api/posts/:id/relations/:relation, /api/posts/permissions and /api/permissions.

<script setup lang="ts">
const { data } = useAutoApiList('posts', { sort: '-createdAt', limit: 20 })
const { mutate: createPost } = useAutoApiCreate('posts')
</script>

Security model

In the playground

The repo's playground runs these on a seeded database; the pictures are its CI screenshots.

Roles, rows and fields. A regular user's permissions, from GET /api/permissions:

Nested includes with field selection and a limit:

Aggregations grouped by a column:

Scoped API tokens: an editor token may read articles and nothing it holds no scope for:

Documentation

Full documentation: websideproject.com/docs/nuxt-auto

• Getting started
• Authentication & authorization · Permissions cookbook · better-auth
• Multi-tenancy · Soft deletes · Validation
• Pagination · Nested relationships · Bulk operations · Aggregations · M2M
• Frontend composables · Custom endpoints · Lifecycle hooks
• Plugin system · Plugin catalog · Rate limiting
• Database adapters · Cloudflare D1 · Testing
• Configuration · Upgrading

An admin panel for these resources: @websideproject/nuxt-auto-admin.

Links

• GitHub
• Issues · Discussions
• Releases

License

MIT