docs: add detailed Nuxt 3 Adminizer integration guide and working fixture

docs/frameworks/nuxt3.md

@@ -0,0 +1,290 @@
+> ⚠️ **AI-DRAFT**
+>
+> This document was generated by a neural network and may contain inaccuracies or mistakes.
+
+# Nuxt 3 + Adminizer (minimal Sequelize fixture)
+
+This page is a **detailed, copy-paste friendly integration guide** for connecting Adminizer to Nuxt 3 with Sequelize + SQLite.
+
+Reference working fixture: `fixture-nuxt3/`.
+
+---
+
+## 1) Install dependencies
+
+```bash
+npm install adminizer nuxt sequelize sqlite3
+npm install -D tsx typescript
+```
+
+Quick environment check (required by this repository workflow):
+
+```bash
+npx tsx --version
+```
+
+---
+
+## 2) Create project files
+
+### `package.json`
+
+```json
+{
+  "name": "fixture-nuxt3",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "nuxi dev",
+    "build": "nuxi build",
+    "preview": "nuxi preview"
+  },
+  "dependencies": {
+    "adminizer": "^4.4.0",
+    "nuxt": "^3.13.2",
+    "sequelize": "^6.37.7",
+    "sqlite3": "^5.1.7"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.2"
+  }
+}
+```
+
+### `nuxt.config.ts`
+
+```ts
+export default defineNuxtConfig({
+  compatibilityDate: "2025-01-01",
+  devtools: { enabled: true }
+});
+```
+
+### `tsconfig.json`
+
+```json
+{
+  "extends": "./.nuxt/tsconfig.json"
+}
+```
+
+### `app.vue`
+
+```vue
+<template>
+  <main style="font-family: sans-serif; padding: 24px;">
+    <h1>Adminizer + Nuxt 3 fixture</h1>
+    <p>Open the admin panel at <a href="/adminizer">/adminizer</a>.</p>
+  </main>
+</template>
+```
+
+---
+
+## 3) Create a minimal Sequelize model
+
+### `server/models/Post.ts`
+
+```ts
+import { DataTypes, Model, type InferAttributes, type InferCreationAttributes, type Sequelize } from "sequelize";
+
+export class Post extends Model<InferAttributes<Post>, InferCreationAttributes<Post>> {
+  declare id: number;
+  declare title: string;
+  declare content: string | null;
+  declare createdAt: Date;
+  declare updatedAt: Date;
+}
+
+export function initPostModel(sequelize: Sequelize) {
+  Post.init(
+    {
+      id: {
+        type: DataTypes.INTEGER.UNSIGNED,
+        primaryKey: true,
+        autoIncrement: true
+      },
+      title: {
+        type: DataTypes.STRING(180),
+        allowNull: false
+      },
+      content: {
+        type: DataTypes.TEXT,
+        allowNull: true
+      },
+      createdAt: DataTypes.DATE,
+      updatedAt: DataTypes.DATE
+    },
+    {
+      sequelize,
+      tableName: "posts",
+      modelName: "Post"
+    }
+  );
+
+  return Post;
+}
+```
+
+---
+
+## 4) Bootstrap Sequelize (singleton)
+
+### `server/utils/sequelize.ts`
+
+```ts
+import { Sequelize } from "sequelize";
+import { SequelizeAdapter } from "adminizer";
+import { initPostModel } from "../models/Post";
+
+let sequelizeInstance: Sequelize | null = null;
+
+export async function getSequelizeInstance() {
+  if (sequelizeInstance) {
+    return sequelizeInstance;
+  }
+
+  sequelizeInstance = new Sequelize({
+    dialect: "sqlite",
+    storage: ".tmp/adminizer-nuxt3.sqlite",
+    logging: false
+  });
+
+  await SequelizeAdapter.registerSystemModels(sequelizeInstance as any);
+  initPostModel(sequelizeInstance);
+  await sequelizeInstance.sync();
+
+  return sequelizeInstance;
+}
+```
+
+What this does:
+- creates one DB connection for the app,
+- registers Adminizer system tables,
+- registers your `Post` model,
+- creates tables automatically via `sync()`.
+
+---
+
+## 5) Bootstrap Adminizer middleware (singleton)
+
+### `server/utils/adminizer.ts`
+
+```ts
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Adminizer, SequelizeAdapter } from "adminizer";
+import { getSequelizeInstance } from "./sequelize";
+
+const adminizerConfig = {
+  routePrefix: "/adminizer",
+  auth: {
+    enable: false
+  },
+  models: {
+    Post: {
+      title: "Posts",
+      model: "post",
+      displayName: "title",
+      fields: {
+        title: { type: "string", required: true },
+        content: { type: "text" },
+        createdAt: false,
+        updatedAt: false
+      }
+    }
+  }
+};
+
+let middlewareInstance:
+  | ((req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void)
+  | null = null;
+
+export async function getAdminizerMiddleware() {
+  if (middlewareInstance) {
+    return middlewareInstance;
+  }
+
+  const sequelize = await getSequelizeInstance();
+  const adapter = new SequelizeAdapter(sequelize as any);
+  const adminizer = new Adminizer([adapter]);
+
+  await adminizer.init(adminizerConfig as any);
+  middlewareInstance = adminizer.getMiddleware();
+
+  return middlewareInstance;
+}
+```
+
+---
+
+## 6) Connect Adminizer to Nuxt server middleware
+
+### `server/middleware/adminizer.ts`
+
+```ts
+import { fromNodeMiddleware } from "h3";
+import { getAdminizerMiddleware } from "../utils/adminizer";
+
+export default fromNodeMiddleware(async (req, res, next) => {
+  const url = req.url ?? "";
+
+  if (!url.startsWith("/adminizer")) {
+    return next();
+  }
+
+  const middleware = await getAdminizerMiddleware();
+  middleware(req, res, next);
+});
+```
+
+This keeps Nuxt routes intact and sends only `/adminizer*` requests to Adminizer.
+
+---
+
+## 7) Run and validate
+
+```bash
+npm install
+npx tsx --version
+npm run dev
+```
+
+Open:
+- `http://localhost:3000/`
+- `http://localhost:3000/adminizer`
+
+Expected result: `/adminizer` should return HTTP 200 and Adminizer HTML.
+
+---
+
+## 8) Build and preview
+
+```bash
+npm run build
+npm run preview
+```
+
+---
+
+## Agent checklist (recommended)
+
+When an AI agent integrates Adminizer into Nuxt 3, follow this sequence:
+
+1. Install dependencies (`adminizer`, `nuxt`, `sequelize`, `sqlite3`, `tsx`, `typescript`).
+2. Verify TSX availability (`npx tsx --version`).
+3. Implement model(s) with `Model.init` (avoid decorator-only setup to reduce Nitro transform issues).
+4. Create Sequelize singleton and call `SequelizeAdapter.registerSystemModels`.
+5. Create Adminizer singleton and `await adminizer.init(config)`.
+6. Mount Adminizer via Nuxt server middleware for `/adminizer*`.
+7. Run dev server and verify `200` on `/adminizer`.
+8. Run production build and preview.
+
+---
+
+## Notes
+
+- This fixture is intentionally minimal and focused on wiring.
+- It uses `Adminizer` and `SequelizeAdapter` from the `adminizer` package root export.
+- For production use, enable Adminizer auth and move secrets to environment variables.
+- Add more Sequelize models in `server/models` and extend `models` config in `server/utils/adminizer.ts`.

docs/index.md

@@ -26,6 +26,7 @@
 * [Form Error Management](FormError.md)
 * [Appearance](Appearance.md)
 * [Next.js Framework Guide](frameworks/nextjs.md)
+* [Nuxt 3 Framework Guide](frameworks/nuxt3.md)
 
 ## 4. Admin Panel Features
 

fixture-nuxt3/README.md

@@ -0,0 +1,20 @@
+# fixture-nuxt3
+
+Minimal Nuxt 3 + Adminizer example with Sequelize and SQLite.
+
+## Run
+
+```bash
+npm install
+npx tsx --version
+npm run dev
+```
+
+Open http://localhost:3000/adminizer.
+
+## Build
+
+```bash
+npm run build
+npm run preview
+```

fixture-nuxt3/app.vue

@@ -0,0 +1,6 @@
+<template>
+  <main style="font-family: sans-serif; padding: 24px;">
+    <h1>Adminizer + Nuxt 3 fixture</h1>
+    <p>Open the admin panel at <a href="/adminizer">/adminizer</a>.</p>
+  </main>
+</template>

fixture-nuxt3/nuxt.config.ts

@@ -0,0 +1,4 @@
+export default defineNuxtConfig({
+  compatibilityDate: "2025-01-01",
+  devtools: { enabled: true }
+});

fixture-nuxt3/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "fixture-nuxt3",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "nuxi dev",
+    "build": "nuxi build",
+    "preview": "nuxi preview"
+  },
+  "dependencies": {
+    "adminizer": "^4.4.0",
+    "nuxt": "^3.13.2",
+    "sequelize": "^6.37.7",
+    "sqlite3": "^5.1.7"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.2"
+  }
+}

fixture-nuxt3/server/middleware/adminizer.ts

@@ -0,0 +1,12 @@
+import { fromNodeMiddleware } from "h3";
+import { getAdminizerMiddleware } from "../utils/adminizer";
+
+export default fromNodeMiddleware(async (req, res, next) => {
+  const url = req.url ?? "";
+  if (!url.startsWith("/adminizer")) {
+    return next();
+  }
+
+  const middleware = await getAdminizerMiddleware();
+  middleware(req, res, next);
+});