nuxt-auto-crud 1.2.2 → 1.4.0

package/README.md

@@ -1,77 +1,153 @@
 # Nuxt Auto CRUD
 
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![License][license-src]][license-href]
-[![Nuxt][nuxt-src]][nuxt-href]
 
-Auto-generate RESTful CRUD APIs for your Nuxt app based solely on your database schema. No configuration needed!
+
+> **Note:** This module is currently in its alpha stage. However, you can use it to accelerate MVP development. It has not been tested thoroughly enough for production use; only happy-path testing is performed for each release.
+
+Auto-generate RESTful CRUD APIs for your **Nuxt** application based solely on your database schema. Minimal configuration required.
 
 - [✨ Release Notes](/CHANGELOG.md)
 - [🎮 Try the Playground](/playground)
 
-## ✨ Features
+## 🚀 CRUD APIs are ready to use without code
+
+- `GET /api/:model` - List all records
+- `POST /api/:model` - Create a new record
+- `GET /api/:model/:id` - Get record by ID
+- `PATCH /api/:model/:id` - Update record
+- `DELETE /api/:model/:id` - Delete record
 
-- 🔄 **Auto-Detection** - Automatically detects all tables from your Drizzle schema
-- 🚀 **Zero Configuration** - Just define your schema, APIs are generated automatically
-- 🛡️ **Protected Fields** - Automatically protects `id` and `createdAt` fields from updates
-- 📝 **Full CRUD** - Complete Create, Read, Update, Delete operations out of the box
-- 🎯 **Type-Safe** - Fully typed with TypeScript support
-- 🔌 **Works with NuxtHub** - Seamlessly integrates with NuxtHub database
+## 📦 How to install
 
-## 📦 Quick Setup
+### New Project (Recommended)
 
-### 1. Install the module
+Start a new project with everything pre-configured using our template:
 
 ```bash
-bun add nuxt-auto-crud
-# or
-npm install nuxt-auto-crud
+npx nuxi init -t gh:clifordpereira/nuxt-auto-crud_template <project-name>
+cd <project-name>
+bun install
+bun db:generate
+bun run dev
+```
+
+Detailed instructions can be found in [https://auto-crud.clifland.in/](https://auto-crud.clifland.in/)
+
+### Add User
+Open Nuxt DevTools (bottom-middle icon) > `...` menu > **Database** icon to add users.
+    > **Note:** If the users table doesn't appear, restart the server (`Ctrl + C` and `bun run dev`).
+
+That's it! You can now access the APIs:
+
+### Test API
+Visit [http://localhost:3000/api/users](http://localhost:3000/api/users).
+
+### Existing Project
+
+If you want to add `nuxt-auto-crud` to an existing project, follow these steps:
+
+> **Note:** These instructions assume you are using NuxtHub. If you are using a custom SQLite setup (e.g. better-sqlite3, Turso), please see [Custom Setup](./custom-setup.md).
+
+### 1. Install dependencies
+
+```bash
+# Install module and required dependencies
+npm install nuxt-auto-crud @nuxthub/core@latest drizzle-orm
+npm install --save-dev wrangler drizzle-kit
+
+# Or using bun
+bun add nuxt-auto-crud @nuxthub/core@latest drizzle-orm
+bun add --dev wrangler drizzle-kit
 ```
 
-### 2. Add to your Nuxt config
+### 2. Configure Nuxt
+
+Add the modules to your `nuxt.config.ts`:
 
 ```typescript
 // nuxt.config.ts
 export default defineNuxtConfig({
-  modules: ["@nuxthub/core", "nuxt-auto-crud"],
+  modules: ['@nuxthub/core', 'nuxt-auto-crud'],
 
   hub: {
     database: true,
   },
 
   autoCrud: {
-    schemaPath: "server/database/schema", // default value
+    schemaPath: 'server/database/schema', // default value
   },
-});
+})
+```
+
+### 3. Configure Drizzle
+
+Add the generation script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "db:generate": "drizzle-kit generate"
+  }
+}
+```
+
+Create `drizzle.config.ts` in your project root:
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './server/database/schema.ts',
+  out: './server/database/migrations'
+})
+```
+
+### 4. Setup Database Connection
+
+Create `server/utils/drizzle.ts` to export the database instance:
+
+```typescript
+// server/utils/drizzle.ts
+import { drizzle } from 'drizzle-orm/d1'
+export { sql, eq, and, or } from 'drizzle-orm'
+
+import * as schema from '../database/schema'
+
+export const tables = schema
+
+export function useDrizzle() {
+  return drizzle(hubDatabase(), { schema })
+}
+
+export type User = typeof schema.users.$inferSelect
 ```
 
-### 3. Define your database schema
+### 5. Define your database schema
+
+Create `server/database/schema.ts`:
 
 ```typescript
 // server/database/schema.ts
-import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
-
-export const users = sqliteTable("users", {
-  id: integer("id").primaryKey({ autoIncrement: true }),
-  name: text("name").notNull(),
-  email: text("email").notNull().unique(),
-  bio: text("bio"),
-  createdAt: integer("created_at", { mode: "timestamp" }).$defaultFn(
-    () => new Date()
-  ),
-});
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
+
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  email: text('email').notNull().unique(),
+  password: text('password').notNull(),
+  avatar: text('avatar').notNull(),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
+})
+```
 
-export const posts = sqliteTable("posts", {
-  id: integer("id").primaryKey({ autoIncrement: true }),
-  title: text("title").notNull(),
-  content: text("content").notNull(),
-  published: integer("published", { mode: "boolean" }).default(false),
-  authorId: integer("author_id").references(() => users.id),
-  createdAt: integer("created_at", { mode: "timestamp" }).$defaultFn(
-    () => new Date()
-  ),
-});
+### 6. Run the project
+
+```bash
+cd <project-name>
+bun db:generate
+bun run dev
 ```
 
 That's it! 🎉 Your CRUD APIs are now available:
@@ -93,12 +169,13 @@ Want to see it in action? Clone this repo and try the playground:
 git clone https://github.com/clifordpereira/nuxt-auto-crud.git
 cd nuxt-auto-crud
 
-# Install dependencies
+# Install dependencies (parent folder)
 bun install
 
-# Run the playground
-cd playground
+# Run the playground (fullstack with auth)
+cd playground-fullstack
 bun install
+bun db:generate
 bun run dev
 ```
 
@@ -112,9 +189,9 @@ The playground includes a sample schema with users, posts, and comments tables,
 const user = await $fetch("/api/users", {
   method: "POST",
   body: {
-    name: "John Doe",
-    email: "john@example.com",
-    bio: "Software developer",
+    name: "Cliford Pereira",
+    email: "clifordpereira@gmail.com",
+    bio: "Full-Stack Developer",
   },
 });
 ```
@@ -150,7 +227,57 @@ await $fetch("/api/users/1", {
 });
 ```
 
-## ⚙️ Configuration
+## Use Cases
+
+### 1. Full-stack App (with Auth)
+
+If you are building a full-stack Nuxt application, you can easily integrate `nuxt-auth-utils` and `nuxt-authorization` to secure your auto-generated APIs.
+
+First, install the modules:
+
+```bash
+npx nuxi@latest module add auth-utils
+npm install nuxt-authorization
+```
+
+Then, configure `nuxt-auto-crud` in your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: [
+    'nuxt-auto-crud',
+    'nuxt-auth-utils'
+  ],
+  autoCrud: {
+    auth: {
+      enabled: true, // Enables requireUserSession() check
+      authorization: true // Enables authorize(model, action) check
+    }
+  }
+})
+```
+
+When `authorization` is enabled, the module will call `authorize(model, action)` where action is one of: `create`, `read`, `update`, `delete`.
+
+### 2. Backend-only App (API Mode)
+
+If you are using Nuxt as a backend for a separate client application (e.g., mobile app, SPA), you can use this module to quickly generate REST APIs.
+
+In this case, you might handle authentication differently (e.g., validating tokens in middleware) or disable the built-in auth checks if you have a global auth middleware.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-auto-crud'],
+  autoCrud: {
+    auth: {
+      enabled: false, // Default
+      authorization: false // Default
+    }
+  }
+})
+```
+
+## Configuration
 
 ### Module Options
 
@@ -173,45 +300,26 @@ By default, the following fields are protected from updates:
 
 You can customize updatable fields in your schema by modifying the `modelMapper.ts` utility.
 
+### Hidden Fields
+
+By default, the following fields are hidden from API responses for security:
+
+- `password`
+- `secret`
+- `token`
+
+You can customize hidden fields by modifying the `modelMapper.ts` utility.
+
 ## 🔧 Requirements
 
 - Nuxt 3 or 4
-- NuxtHub (for database functionality)
-- Drizzle ORM
+- Drizzle ORM (SQLite)
+- NuxtHub (Recommended) or [Custom SQLite Setup](./custom-setup.md)
 
 ## 🤝 Contributing
 
 Contributions are welcome! Please check out the [contribution guide](/CONTRIBUTING.md).
 
-<details>
-  <summary>Local development</summary>
-  
-  ```bash
-  # Install dependencies
-  bun install
-  
-  # Generate type stubs
-  bun run dev:prepare
-  
-  # Develop with the playground
-  bun run dev
-  
-  # Build the playground
-  bun run dev:build
-  
-  # Run ESLint
-  bun run lint
-  
-  # Run Vitest
-  bun run test
-  bun run test:watch
-  
-  # Release new version
-  bun run release
-  ```
-
-</details>
-
 ## 📝 License
 
 [MIT License](./LICENSE)
@@ -220,13 +328,4 @@ Contributions are welcome! Please check out the [contribution guide](/CONTRIBUTI
 
 Made with ❤️ by [Cliford Pereira](https://github.com/clifordpereira)
 
-<!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/nuxt-auto-crud/latest.svg?style=flat&colorA=020420&colorB=00DC82
-[npm-version-href]: https://npmjs.com/package/nuxt-auto-crud
-[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-auto-crud.svg?style=flat&colorA=020420&colorB=00DC82
-[npm-downloads-href]: https://npm.chart.dev/nuxt-auto-crud
-[license-src]: https://img.shields.io/npm/l/nuxt-auto-crud.svg?style=flat&colorA=020420&colorB=00DC82
-[license-href]: https://npmjs.com/package/nuxt-auto-crud
-[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
-[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -1,7 +1,6 @@
 import * as _nuxt_schema from '@nuxt/schema';
 
 interface ModuleOptions {
-    /**
     /**
      * Path to the database schema file
      * @default 'server/database/schema'
@@ -12,6 +11,55 @@ interface ModuleOptions {
      * @default 'server/utils/drizzle'
      */
     drizzlePath?: string;
+    /**
+     * Authentication configuration
+     */
+    auth?: {
+        /**
+         * Authentication type
+         * @default 'session'
+         */
+        type?: 'session' | 'jwt';
+        /**
+         * JWT Secret (required if type is 'jwt')
+         */
+        jwtSecret?: string;
+        /**
+         * Enable authentication checks (requires nuxt-auth-utils for session)
+         * @default false
+         */
+        enabled: boolean;
+        /**
+         * Enable authorization checks (requires nuxt-authorization)
+         * @default false
+         */
+        authorization?: boolean;
+    };
+    /**
+     * Resource-specific configuration
+     * Define public access and column visibility
+     */
+    resources?: {
+        [modelName: string]: {
+            /**
+             * Actions allowed without authentication
+             * true = all actions
+             * array = specific actions ('list', 'create', 'read', 'update', 'delete')
+             */
+            public?: boolean | ('list' | 'create' | 'read' | 'update' | 'delete')[];
+            /**
+             * Columns to return for unauthenticated requests
+             * If not specified, all columns (except hidden ones) are returned
+             */
+            publicColumns?: string[];
+        };
+    };
+}
+
+declare module '@nuxt/schema' {
+    interface RuntimeConfig {
+        autoCrud: ModuleOptions;
+    }
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-auto-crud",
   "configKey": "autoCrud",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -9,7 +9,7 @@ const module$1 = defineNuxtModule({
     schemaPath: "server/database/schema",
     drizzlePath: "server/utils/drizzle"
   },
-  setup(options, nuxt) {
+  async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
     const schemaPath = resolver.resolve(
       nuxt.options.rootDir,
@@ -21,6 +21,29 @@ const module$1 = defineNuxtModule({
       options.drizzlePath
     );
     nuxt.options.alias["#site/drizzle"] = drizzlePath;
+    nuxt.options.alias["#authorization"] = nuxt.options.alias["#authorization"] || "nuxt-authorization/utils";
+    const { loadConfig } = await import('c12');
+    const { config: externalConfig } = await loadConfig({
+      name: "autocrud",
+      cwd: nuxt.options.rootDir
+    });
+    const mergedAuth = {
+      ...externalConfig?.auth,
+      ...options.auth
+    };
+    const mergedResources = {
+      ...externalConfig?.resources,
+      ...options.resources
+    };
+    nuxt.options.runtimeConfig.autoCrud = {
+      auth: {
+        enabled: mergedAuth.enabled ?? false,
+        authorization: mergedAuth.authorization ?? false,
+        type: mergedAuth.type ?? "session",
+        jwtSecret: mergedAuth.jwtSecret
+      },
+      resources: mergedResources || {}
+    };
     const apiDir = resolver.resolve("./runtime/server/api");
     addServerHandler({
       route: "/api/:model",

package/dist/runtime/server/api/[model]/[id].delete.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Record<string, unknown>>>;
 export default _default;

package/dist/runtime/server/api/[model]/[id].delete.js

@@ -1,9 +1,23 @@
 import { eventHandler, getRouterParams, createError } from "h3";
 import { eq } from "drizzle-orm";
-import { getTableForModel, getModelSingularName } from "../../utils/modelMapper.js";
+import { getTableForModel, getModelSingularName, filterHiddenFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  const { resources } = useAutoCrudConfig();
   const { model, id } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "delete");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("delete");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
   const singularName = getModelSingularName(model);
   const deletedRecord = await useDrizzle().delete(table).where(eq(table.id, Number(id))).returning().get();
@@ -13,5 +27,9 @@ export default eventHandler(async (event) => {
       message: `${singularName} not found`
     });
   }
-  return deletedRecord;
+  if (isAdmin) {
+    return filterHiddenFields(model, deletedRecord);
+  } else {
+    return filterPublicColumns(model, deletedRecord);
+  }
 });

package/dist/runtime/server/api/[model]/[id].get.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Record<string, unknown>>>;
 export default _default;

package/dist/runtime/server/api/[model]/[id].get.js

@@ -1,17 +1,34 @@
 import { eventHandler, getRouterParams, createError } from "h3";
 import { eq } from "drizzle-orm";
-import { getTableForModel, getModelSingularName } from "../../utils/modelMapper.js";
+import { getTableForModel, filterHiddenFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  const { resources } = useAutoCrudConfig();
   const { model, id } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "read");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("read");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
-  const singularName = getModelSingularName(model);
   const record = await useDrizzle().select().from(table).where(eq(table.id, Number(id))).get();
   if (!record) {
     throw createError({
       statusCode: 404,
-      message: `${singularName} not found`
+      message: "Record not found"
     });
   }
-  return record;
+  if (isAdmin) {
+    return filterHiddenFields(model, record);
+  } else {
+    return filterPublicColumns(model, record);
+  }
 });

package/dist/runtime/server/api/[model]/[id].patch.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Record<string, unknown>>>;
 export default _default;

package/dist/runtime/server/api/[model]/[id].patch.js

@@ -1,12 +1,36 @@
-import { eventHandler, getRouterParams, readBody } from "h3";
+import { eventHandler, getRouterParams, readBody, createError } from "h3";
 import { eq } from "drizzle-orm";
-import { getTableForModel, filterUpdatableFields } from "../../utils/modelMapper.js";
+import { getTableForModel, filterUpdatableFields, filterHiddenFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  const { resources } = useAutoCrudConfig();
   const { model, id } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "update");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("update");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
   const body = await readBody(event);
-  const updateData = filterUpdatableFields(model, body);
-  const record = await useDrizzle().update(table).set(updateData).where(eq(table.id, Number(id))).returning().get();
-  return record;
+  const payload = filterUpdatableFields(model, body);
+  const updatedRecord = await useDrizzle().update(table).set(payload).where(eq(table.id, Number(id))).returning().get();
+  if (!updatedRecord) {
+    throw createError({
+      statusCode: 404,
+      message: "Record not found"
+    });
+  }
+  if (isAdmin) {
+    return filterHiddenFields(model, updatedRecord);
+  } else {
+    return filterPublicColumns(model, updatedRecord);
+  }
 });

package/dist/runtime/server/api/[model]/index.get.js

@@ -1,9 +1,30 @@
-import { eventHandler, getRouterParams } from "h3";
-import { getTableForModel } from "../../utils/modelMapper.js";
+import { eventHandler, getRouterParams, createError } from "h3";
+import { getTableForModel, filterHiddenFields, filterPublicColumns } from "../../utils/modelMapper.js";
 import { useDrizzle } from "#site/drizzle";
+import { useAutoCrudConfig } from "../../utils/config.js";
+import { checkAdminAccess } from "../../utils/auth.js";
 export default eventHandler(async (event) => {
+  console.log("[GET] Request received", event.path);
+  const { resources } = useAutoCrudConfig();
   const { model } = getRouterParams(event);
+  const isAdmin = await checkAdminAccess(event, model, "list");
+  if (!isAdmin) {
+    const resourceConfig = resources?.[model];
+    const isPublic = resourceConfig?.public === true || Array.isArray(resourceConfig?.public) && resourceConfig.public.includes("list");
+    if (!isPublic) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  }
   const table = getTableForModel(model);
-  const records = await useDrizzle().select().from(table).all();
-  return records;
+  const results = await useDrizzle().select().from(table).all();
+  return results.map((item) => {
+    if (isAdmin) {
+      return filterHiddenFields(model, item);
+    } else {
+      return filterPublicColumns(model, item);
+    }
+  });
 });

package/dist/runtime/server/api/[model]/index.post.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Record<string, unknown>>>;
 export default _default;