nuxt-auto-crud 1.4.0 → 1.6.0

package/README.md

@@ -1,16 +1,24 @@
 # Nuxt Auto CRUD
 
-
-
 > **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.
 
+**Core Philosophy:**
+The main objective of this module is to **expose CRUD APIs without the need for writing code**. You define your database schema, and `nuxt-auto-crud` handles the rest.
+
+You don't need to setup an extra server or database to create an MVP of an application. The Nuxt (Nitro) server and SQLite can save you time and money.
+And you don't need a separate Strapi or Supabase setup to automate your CRUD process. `nuxt-auto-crud` will help you with that and accelerate your development exponentially.
+
+While we provide a playground with a CMS-like interface, this is primarily to demonstrate the capabilities. You are expected to build your own frontend application to consume these APIs.
+
 - [✨ Release Notes](/CHANGELOG.md)
 - [🎮 Try the Playground](/playground)
 
 ## 🚀 CRUD APIs are ready to use without code
 
+Once installed, your database tables automatically become API endpoints:
+
 - `GET /api/:model` - List all records
 - `POST /api/:model` - Create a new record
 - `GET /api/:model/:id` - Get record by ID
@@ -19,7 +27,7 @@ Auto-generate RESTful CRUD APIs for your **Nuxt** application based solely on yo
 
 ## 📦 How to install
 
-### New Project (Recommended)
+### 1. Fullstack Template (Recommended)
 
 Start a new project with everything pre-configured using our template:
 
@@ -31,24 +39,20 @@ 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`).
+**Template Usage Modes:**
 
-That's it! You can now access the APIs:
+1.  **Fullstack App**: The template includes the `nuxt-auto-crud` module, providing both the backend APIs and the frontend UI.
+2.  **Frontend Only**: You can use the template just for the frontend. In this case, you don't need to install the module in the frontend app. Instead, you would install `nuxt-auto-crud` in a separate backend setup (e.g., another Nuxt project acting as the API).
 
-### Test API
-Visit [http://localhost:3000/api/users](http://localhost:3000/api/users).
+Detailed instructions can be found in [https://auto-crud.clifland.in/](https://auto-crud.clifland.in/)
 
-### Existing Project
+### 2. Manual Setup (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
+#### Install dependencies
 
 ```bash
 # Install module and required dependencies
@@ -60,7 +64,7 @@ bun add nuxt-auto-crud @nuxthub/core@latest drizzle-orm
 bun add --dev wrangler drizzle-kit
 ```
 
-### 2. Configure Nuxt
+#### Configure Nuxt
 
 Add the modules to your `nuxt.config.ts`:
 
@@ -75,11 +79,12 @@ export default defineNuxtConfig({
 
   autoCrud: {
     schemaPath: 'server/database/schema', // default value
+    auth: false, // Disable auth by default for easy testing
   },
 })
 ```
 
-### 3. Configure Drizzle
+#### Configure Drizzle
 
 Add the generation script to your `package.json`:
 
@@ -88,6 +93,7 @@ Add the generation script to your `package.json`:
   "scripts": {
     "db:generate": "drizzle-kit generate"
   }
+  // ...
 }
 ```
 
@@ -99,12 +105,12 @@ import { defineConfig } from 'drizzle-kit'
 
 export default defineConfig({
   dialect: 'sqlite',
-  schema: './server/database/schema.ts',
+  schema: './server/database/schema/index.ts', // Point to your schema index file
   out: './server/database/migrations'
 })
 ```
 
-### 4. Setup Database Connection
+#### Setup Database Connection
 
 Create `server/utils/drizzle.ts` to export the database instance:
 
@@ -124,12 +130,12 @@ export function useDrizzle() {
 export type User = typeof schema.users.$inferSelect
 ```
 
-### 5. Define your database schema
+#### Define your database schema
 
-Create `server/database/schema.ts`:
+Create your schema files in `server/database/schema/`. For example, `server/database/schema/users.ts`:
 
 ```typescript
-// server/database/schema.ts
+// server/database/schema/users.ts
 import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
 
 export const users = sqliteTable('users', {
@@ -142,7 +148,9 @@ export const users = sqliteTable('users', {
 })
 ```
 
-### 6. Run the project
+> **Note:** The `organization.ts` and `cms.ts` files you might see in the playground are just examples and are commented out by default. You should implement a robust schema tailored to your production needs.
+
+#### Run the project
 
 ```bash
 cd <project-name>
@@ -150,15 +158,86 @@ bun db:generate
 bun run dev
 ```
 
-That's it! 🎉 Your CRUD APIs are now available:
+That's it! 🎉 Your CRUD APIs are now available at `/api/users`.
+
+### 3. 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: false // APIs are public (or handled by your own middleware)
+  }
+})
+```
+
+## 🔐 Authentication Configuration
 
-- `GET /api/users` - List all users
-- `POST /api/users` - Create a new user
-- `GET /api/users/:id` - Get user by ID
-- `PATCH /api/users/:id` - Update user
-- `DELETE /api/users/:id` - Delete user
+The module supports `auth: false` by default, which exposes all LCRUD APIs. You can enable authentication and authorization as needed.
+
+### Session Auth (Default)
+
+Requires `nuxt-auth-utils` and `nuxt-authorization`.
+
+```typescript
+export default defineNuxtConfig({
+  autoCrud: {
+    auth: {
+      type: 'session',
+      authentication: true, // Enables requireUserSession() check
+      authorization: true // Enables authorize(model, action) check
+    }
+  }
+})
+```
+
+### JWT Auth
+
+Useful for backend-only apps.
+
+```typescript
+export default defineNuxtConfig({
+  autoCrud: {
+    auth: {
+      type: 'jwt',
+      authentication: true,
+      jwtSecret: process.env.JWT_SECRET,
+      authorization: true
+    }
+  }
+})
+```
 
-_(Same endpoints for all your tables!)_
+## 🛡️ Resource Configuration (RBAC)
+
+You can define fine-grained access control and resource policies using `autocrud.config.ts` in your project root. This file is optional and useful when you need specific rules per resource.
+
+```typescript
+// autocrud.config.ts
+export default {
+  resources: {
+    users: {
+      // Access Control
+      auth: {
+        // Admin has full access
+        admin: true,
+        // Public (unauthenticated) users can only list and read
+        public: ['list', 'read'],
+      },
+      // Field Visibility
+      publicColumns: ['id', 'name', 'avatar'], // Only these columns are returned to public users
+    },
+  }
+}
+```
+
+## ⚠️ Known Issues
+
+- **Foreign Key Naming:** Currently, if you have multiple foreign keys referring to the same table (e.g., `customer_id` and `author_id` both referring to the `users` table), the automatic relation handling might assume `user_id` for both. This is a known limitation in the current alpha version.
 
 ## 🎮 Try the Playground
 
@@ -172,15 +251,13 @@ cd nuxt-auto-crud
 # Install dependencies (parent folder)
 bun install
 
-# Run the playground (fullstack with auth)
-cd playground-fullstack
+# Run the playground (Fullstack)
+cd playground
 bun install
 bun db:generate
 bun run dev
 ```
 
-The playground includes a sample schema with users, posts, and comments tables, plus an interactive UI to explore all the features.
-
 ## 📖 Usage Examples
 
 ### Create a Record
@@ -224,57 +301,11 @@ const updated = await $fetch("/api/users/1", {
 ```typescript
 await $fetch("/api/users/1", {
   method: "DELETE",
-});
-```
-
-## 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
-    }
+  headers: {
+    // If auth is enabled
+    Authorization: 'Bearer ...' 
   }
-})
-```
-
-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
@@ -327,5 +358,3 @@ Contributions are welcome! Please check out the [contribution guide](/CONTRIBUTI
 ## 👨‍💻 Author
 
 Made with ❤️ by [Cliford Pereira](https://github.com/clifordpereira)
-
-

package/dist/module.d.mts

@@ -14,27 +14,7 @@ interface ModuleOptions {
     /**
      * 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;
-    };
+    auth?: boolean | AuthOptions;
     /**
      * Resource-specific configuration
      * Define public access and column visibility
@@ -55,10 +35,34 @@ interface ModuleOptions {
         };
     };
 }
+interface AuthOptions {
+    /**
+     * 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
+     */
+    authentication: boolean;
+    /**
+     * Enable authorization checks (requires nuxt-authorization)
+     * @default false
+     */
+    authorization?: boolean;
+}
+interface RuntimeModuleOptions extends Omit<ModuleOptions, 'auth'> {
+    auth: AuthOptions;
+}
 
 declare module '@nuxt/schema' {
     interface RuntimeConfig {
-        autoCrud: ModuleOptions;
+        autoCrud: RuntimeModuleOptions;
     }
 }
 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.4.0",
+  "version": "1.6.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { defineNuxtModule, createResolver, addServerHandler, addServerImportsDir } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addServerHandler, addServerImportsDir, addImportsDir, addServerPlugin } from '@nuxt/kit';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -7,7 +7,8 @@ const module$1 = defineNuxtModule({
   },
   defaults: {
     schemaPath: "server/database/schema",
-    drizzlePath: "server/utils/drizzle"
+    drizzlePath: "server/utils/drizzle",
+    auth: false
   },
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
@@ -27,17 +28,45 @@ const module$1 = defineNuxtModule({
       name: "autocrud",
       cwd: nuxt.options.rootDir
     });
-    const mergedAuth = {
-      ...externalConfig?.auth,
-      ...options.auth
+    let mergedAuth = {
+      authentication: false,
+      authorization: false,
+      type: "session"
     };
+    if (options.auth === true) {
+      mergedAuth = {
+        authentication: true,
+        authorization: true,
+        type: "session",
+        ...typeof externalConfig?.auth === "object" ? externalConfig.auth : {}
+      };
+    } else if (options.auth === false) {
+      mergedAuth = {
+        authentication: false,
+        authorization: false,
+        type: "session"
+      };
+    } else {
+      mergedAuth = {
+        authentication: true,
+        // Default to true if object provided? Or undefined?
+        // If options.auth is undefined, we might want defaults.
+        // But if defaults say auth: false, then options.auth might be undefined.
+        // Let's stick to the plan: default is false.
+        ...typeof externalConfig?.auth === "object" ? externalConfig.auth : {},
+        ...typeof options.auth === "object" ? options.auth : {}
+      };
+      if (mergedAuth.authentication === void 0) {
+        mergedAuth.authentication = false;
+      }
+    }
     const mergedResources = {
       ...externalConfig?.resources,
       ...options.resources
     };
     nuxt.options.runtimeConfig.autoCrud = {
       auth: {
-        enabled: mergedAuth.enabled ?? false,
+        authentication: mergedAuth.authentication ?? false,
         authorization: mergedAuth.authorization ?? false,
         type: mergedAuth.type ?? "session",
         jwtSecret: mergedAuth.jwtSecret
@@ -45,6 +74,21 @@ const module$1 = defineNuxtModule({
       resources: mergedResources || {}
     };
     const apiDir = resolver.resolve("./runtime/server/api");
+    addServerHandler({
+      route: "/api/_schema",
+      method: "get",
+      handler: resolver.resolve(apiDir, "_schema/index.get")
+    });
+    addServerHandler({
+      route: "/api/_schema/:table",
+      method: "get",
+      handler: resolver.resolve(apiDir, "_schema/[table].get")
+    });
+    addServerHandler({
+      route: "/api/_relations",
+      method: "get",
+      handler: resolver.resolve(apiDir, "_relations.get")
+    });
     addServerHandler({
       route: "/api/:model",
       method: "get",
@@ -71,9 +115,8 @@ const module$1 = defineNuxtModule({
       handler: resolver.resolve(apiDir, "[model]/[id].delete")
     });
     addServerImportsDir(resolver.resolve("./runtime/server/utils"));
-    console.log("\u{1F680} Auto CRUD module loaded!");
-    console.log(`   - Schema: ${options.schemaPath}`);
-    console.log(`   - API: /api/[model]`);
+    addImportsDir(resolver.resolve("./runtime/composables"));
+    addServerPlugin(resolver.resolve("./runtime/server/plugins/seed"));
   }
 });
 

package/dist/runtime/composables/useRelationDisplay.d.ts

@@ -0,0 +1,12 @@
+export declare const useRelationDisplay: (schema: {
+    resource: string;
+    fields: {
+        name: string;
+        type: string;
+        required?: boolean;
+    }[];
+}) => {
+    fetchRelations: () => Promise<void>;
+    getDisplayValue: (key: string, value: unknown) => unknown;
+    relationsMap: import("vue").Ref<Record<string, Record<string, string>>, Record<string, Record<string, string>>>;
+};

package/dist/runtime/composables/useRelationDisplay.js

@@ -0,0 +1,48 @@
+import { ref, useFetch, useRequestHeaders } from "#imports";
+export const useRelationDisplay = (schema) => {
+  const resourceName = schema.resource;
+  const relationsMap = ref({});
+  const displayValues = ref({});
+  const headers = useRequestHeaders(["cookie"]);
+  const fetchRelations = async () => {
+    const { data: relations } = await useFetch("/api/_relations");
+    if (relations.value) {
+      relationsMap.value = relations.value;
+    }
+    const resourceRelations = relationsMap.value[resourceName] || {};
+    const relationFields = Object.keys(resourceRelations);
+    if (relationFields.length === 0) return;
+    await Promise.all(
+      relationFields.map(async (fieldName) => {
+        const targetTable = resourceRelations[fieldName];
+        try {
+          const relatedData = await $fetch(`/api/${targetTable}`, { headers });
+          if (relatedData) {
+            displayValues.value[fieldName] = relatedData.reduce(
+              (acc, item) => {
+                const id = item.id;
+                const label = item.name || item.title || item.email || item.username || `#${item.id}`;
+                acc[id] = label;
+                return acc;
+              },
+              {}
+            );
+          }
+        } catch (error) {
+          console.error(`Failed to fetch relation data for ${targetTable}:`, error);
+        }
+      })
+    );
+  };
+  const getDisplayValue = (key, value) => {
+    if (displayValues.value[key] && (typeof value === "number" || typeof value === "string")) {
+      return displayValues.value[key][value] || value;
+    }
+    return value;
+  };
+  return {
+    fetchRelations,
+    getDisplayValue,
+    relationsMap
+  };
+};

package/dist/runtime/composables/useResourceSchemas.d.ts

@@ -0,0 +1,19 @@
+import type { Ref } from 'vue';
+export interface ResourceField {
+    name: string;
+    type: string;
+    required?: boolean;
+    selectOptions?: string[];
+}
+export interface ResourceSchema {
+    resource: string;
+    fields: ResourceField[];
+}
+export type ResourceSchemas = Record<string, ResourceSchema>;
+export declare const useResourceSchemas: () => Promise<{
+    schemas: Ref<ResourceSchemas | null | undefined>;
+    getSchema: (resource: string) => ResourceSchema | undefined;
+    status: Ref<"idle" | "pending" | "success" | "error">;
+    error: Ref<any>;
+    refresh: () => Promise<void>;
+}>;

package/dist/runtime/composables/useResourceSchemas.js

@@ -0,0 +1,17 @@
+import { useAsyncData, useRequestHeaders } from "#imports";
+export const useResourceSchemas = async () => {
+  const { data: schemas, status, error, refresh } = await useAsyncData("resource-schemas", () => $fetch("/api/_schema", {
+    headers: useRequestHeaders(["cookie"])
+  }));
+  const getSchema = (resource) => {
+    if (!schemas.value) return void 0;
+    return schemas.value[resource];
+  };
+  return {
+    schemas,
+    getSchema,
+    status,
+    error,
+    refresh
+  };
+};

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

@@ -21,6 +21,9 @@ export default eventHandler(async (event) => {
   const table = getTableForModel(model);
   const body = await readBody(event);
   const payload = filterUpdatableFields(model, body);
+  if ("updatedAt" in table) {
+    payload.updatedAt = /* @__PURE__ */ new Date();
+  }
   const updatedRecord = await useDrizzle().update(table).set(payload).where(eq(table.id, Number(id))).returning().get();
   if (!updatedRecord) {
     throw createError({

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

@@ -3,6 +3,7 @@ import { getTableForModel, filterHiddenFields, filterPublicColumns } from "../..
 import { useDrizzle } from "#site/drizzle";
 import { useAutoCrudConfig } from "../../utils/config.js";
 import { checkAdminAccess } from "../../utils/auth.js";
+import { desc } from "drizzle-orm";
 export default eventHandler(async (event) => {
   console.log("[GET] Request received", event.path);
   const { resources } = useAutoCrudConfig();
@@ -19,7 +20,7 @@ export default eventHandler(async (event) => {
     }
   }
   const table = getTableForModel(model);
-  const results = await useDrizzle().select().from(table).all();
+  const results = await useDrizzle().select().from(table).orderBy(desc(table.id)).all();
   return results.map((item) => {
     if (isAdmin) {
       return filterHiddenFields(model, item);

package/dist/runtime/server/api/_relations.get.d.ts

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

package/dist/runtime/server/api/_relations.get.js

@@ -0,0 +1,24 @@
+import { eventHandler, createError } from "h3";
+import { getRelations } from "../utils/schema.js";
+import { useAutoCrudConfig } from "../utils/config.js";
+import { verifyJwtToken } from "../utils/jwt.js";
+export default eventHandler(async (event) => {
+  const { auth } = useAutoCrudConfig();
+  if (auth?.authentication) {
+    let isAuthenticated = false;
+    if (auth.type === "jwt" && auth.jwtSecret) {
+      isAuthenticated = await verifyJwtToken(event, auth.jwtSecret);
+    } else {
+      try {
+        await requireUserSession(event);
+        isAuthenticated = true;
+      } catch {
+        isAuthenticated = false;
+      }
+    }
+    if (!isAuthenticated) {
+      throw createError({ statusCode: 401, message: "Unauthorized" });
+    }
+  }
+  return getRelations();
+});

package/dist/runtime/server/api/_schema/[table].get.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+    resource: string;
+    fields: {
+        name: string;
+        type: string;
+        required: any;
+        selectOptions: undefined;
+    }[];
+}>>;
+export default _default;