webspresso 0.0.75 → 0.0.77

package/README.md

@@ -2165,10 +2165,34 @@ const { app } = createApp({
 ```
 
 - **ORM:** `zdb.file({ maxLength: 2048, nullable: true })` — string column for the stored public URL or path; migrations use `table.string(..., maxLength)`.
-- **Admin:** the panel reads **`settings.uploadUrl`** from the registry (set automatically when `uploadPlugin` is registered **before** `adminPanelPlugin`, or pass **`adminPanelPlugin({ uploadUrl: '/api/upload' })`**). File fields (`type: 'file'` or `customFields` type `file-upload`) POST to that URL with credentials.
+- **Admin forms:** columns with `zdb.file()` automatically render a drag-and-drop upload widget (or a manual URL text field when `uploadUrl` is not configured). Image URLs show an inline thumbnail preview; use `ui.accept: 'image/*'` for image-only fields. Optional `ui: { label, hint, accept, maxBytes }` on the column customizes the widget. For existing `zdb.string()` columns you can use `admin.customFields: { columnName: { type: 'file-upload' } }` instead of changing the schema type.
+- **Admin:** the panel reads **`settings.uploadUrl`** from the registry (set automatically when `uploadPlugin` is registered **before** `adminPanelPlugin`, or pass **`adminPanelPlugin({ uploadUrl: '/api/upload' })`**). File fields (`type: 'file'` or `customFields` type `file-upload`) POST to that URL with credentials; the saved record stores the returned **`url`** / **`publicUrl`** string.
 - **Response:** `{ url, publicUrl, key? }` — clients typically persist **`url`** / **`publicUrl`** in the model.
 - **Custom storage:** `uploadPlugin({ provider: { async put({ buffer, originalName, mimeType, size, req }) { return { publicUrl: '...' }; } } })`.
 
+**Admin model example** (`zdb.file()` picks up the upload widget from schema; no extra `customFields` needed):
+
+```javascript
+const { defineModel, zdb } = require('webspresso');
+
+const Post = defineModel({
+  name: 'Post',
+  table: 'posts',
+  schema: zdb.schema({
+    id: zdb.id(),
+    title: zdb.string(),
+    cover_image: zdb.file({
+      maxLength: 2048,
+      nullable: true,
+      ui: { label: 'Cover', accept: 'image/*', hint: 'JPEG or PNG' },
+    }),
+  }),
+  admin: { enabled: true, label: 'Posts' },
+});
+```
+
+For a plain string column, use `admin.customFields: { attachment: { type: 'file-upload' } }` instead of `zdb.file()`.
+
 ### Health check plugin
 
 Exposes a lightweight **GET** endpoint for load balancers and orchestrators (Kubernetes, Docker healthcheck, etc.). **Enabled by default** in all environments; set `enabled: false` to turn it off.

package/bin/commands/admin-password.js

@@ -3,7 +3,8 @@
  * Reset admin user password via CLI
  */
 
-const readline = require('readline');
+const inquirer = require('inquirer');
+const { hash } = require('../../core/auth/hash');
 const { loadDbConfig, createDbInstance } = require('../utils/db');
 
 function registerCommand(program) {
@@ -32,17 +33,14 @@ function registerCommand(program) {
         // Get email (interactive if not provided)
         let email = options.email;
         if (!email) {
-          const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-          });
-          
-          email = await new Promise((resolve) => {
-            rl.question('Enter admin email: ', (answer) => {
-              rl.close();
-              resolve(answer.trim());
-            });
-          });
+          const answers = await inquirer.prompt([
+            {
+              type: 'input',
+              name: 'email',
+              message: 'Enter admin email:',
+            },
+          ]);
+          email = answers.email.trim();
         }
         
         if (!email) {
@@ -70,49 +68,15 @@ function registerCommand(program) {
         // Get new password (interactive if not provided)
         let password = options.password;
         if (!password) {
-          const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-          });
-          
-          // Disable echo for password input
-          if (process.stdin.isTTY) {
-            process.stdout.write('Enter new password: ');
-            password = await new Promise((resolve) => {
-              let pwd = '';
-              process.stdin.setRawMode(true);
-              process.stdin.resume();
-              process.stdin.on('data', (char) => {
-                char = char.toString();
-                if (char === '\n' || char === '\r') {
-                  process.stdin.setRawMode(false);
-                  process.stdin.pause();
-                  console.log(); // New line after password
-                  resolve(pwd);
-                } else if (char === '\u0003') {
-                  // Ctrl+C
-                  process.exit();
-                } else if (char === '\u007F') {
-                  // Backspace
-                  if (pwd.length > 0) {
-                    pwd = pwd.slice(0, -1);
-                    process.stdout.write('\b \b');
-                  }
-                } else {
-                  pwd += char;
-                  process.stdout.write('*');
-                }
-              });
-            });
-            rl.close();
-          } else {
-            password = await new Promise((resolve) => {
-              rl.question('Enter new password: ', (answer) => {
-                rl.close();
-                resolve(answer);
-              });
-            });
-          }
+          const answers = await inquirer.prompt([
+            {
+              type: 'password',
+              name: 'password',
+              message: 'Enter new password:',
+              mask: '*',
+            },
+          ]);
+          password = answers.password;
         }
         
         if (!password || password.length < 6) {
@@ -121,8 +85,8 @@ function registerCommand(program) {
           process.exit(1);
         }
         
-        // Hash the password
-        const hashedPassword = await bcrypt.hash(password, 10);
+        // Hash the password (same rounds as admin panel setup)
+        const hashedPassword = await hash(password, 10);
         
         // Update the password
         await db('admin_users')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.75",
+  "version": "0.0.77",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",

package/plugins/admin-panel/client/parts/05-rich-text-file-helpers.js

@@ -114,8 +114,76 @@ const RichTextField = {
   }
 };
 
+function isImageAccept(accept) {
+  return accept && accept !== '*/*' && String(accept).indexOf('image') !== -1;
+}
+
+function isImageUrl(url) {
+  if (!url || typeof url !== 'string') return false;
+  if (url.indexOf('blob:') === 0) return true;
+  return /\.(jpe?g|png|gif|webp|svg|avif|bmp|ico)(\?|#|$)/i.test(url.trim());
+}
+
+function shouldShowImagePreview(url, accept) {
+  return isImageAccept(accept) || isImageUrl(url);
+}
+
+function renderUploadedFilePreview(url, options) {
+  var accept = options.accept;
+  var readonly = options.readonly;
+  var onRemove = options.onRemove;
+  var label = options.label;
+  if (!url) return null;
+
+  if (shouldShowImagePreview(url, accept)) {
+    return m('.mt-3.flex.flex-col.items-start.gap-2', [
+      m('a.block', { href: url, target: '_blank', rel: 'noopener noreferrer' },
+        m('img.max-h-48.max-w-full.rounded-lg.border.border-gray-200.dark:border-slate-600.object-contain.bg-white.dark:bg-slate-900.shadow-sm', {
+          src: url,
+          alt: label || 'Preview',
+          loading: 'lazy',
+        })
+      ),
+      m('p.text-xs.text-gray-500.dark:text-slate-400.break-all', url),
+      !readonly && onRemove
+        ? m('button.text-red-600.dark:text-red-400.hover:text-red-800.dark:hover:text-red-300.text-sm', {
+            type: 'button',
+            onclick: onRemove,
+          }, 'Remove')
+        : null,
+    ]);
+  }
+
+  return m('.mt-3.flex.flex-col.items-start.gap-2', [
+    m('a.text-sm.text-indigo-600.dark:text-indigo-400.break-all', {
+      href: url,
+      target: '_blank',
+      rel: 'noopener noreferrer',
+    }, url),
+    !readonly && onRemove
+      ? m('button.text-red-600.dark:text-red-400.hover:text-red-800.dark:hover:text-red-300.text-sm', {
+          type: 'button',
+          onclick: onRemove,
+        }, 'Remove')
+      : null,
+  ]);
+}
+
+function revokeLocalPreview(state) {
+  if (state && state.localPreview) {
+    try { URL.revokeObjectURL(state.localPreview); } catch (e) {}
+    state.localPreview = null;
+  }
+}
+
 // File upload field (multipart POST to settings.uploadUrl; field name "file")
 const FileUploadField = {
+  oninit: function (vnode) {
+    vnode.state.localPreview = null;
+  },
+  onremove: function (vnode) {
+    revokeLocalPreview(vnode.state);
+  },
   oncreate: (vnode) => {
     const col = vnode.attrs.col;
     const readonly = vnode.attrs.readonly;
@@ -128,6 +196,7 @@ const FileUploadField = {
     if (!dropZone) return;
     const meta = col.ui || {};
     const onChange = vnode.attrs.onChange;
+    const state = vnode.state;
     ['dragenter', 'dragover', 'dragleave', 'drop'].forEach(function (eventName) {
       dropZone.addEventListener(eventName, function (e) {
         e.preventDefault();
@@ -147,14 +216,14 @@ const FileUploadField = {
     dropZone.addEventListener('drop', function (e) {
       var files = e.dataTransfer.files;
       if (files.length > 0) {
-        handleAdminFileUpload(files[0], onChange, meta);
+        handleAdminFileUpload(files[0], onChange, meta, state);
       }
     });
     var fileInput = dropZone.querySelector('input[type=file]');
     if (fileInput) {
       fileInput.addEventListener('change', function (e) {
         if (e.target.files.length > 0) {
-          handleAdminFileUpload(e.target.files[0], onChange, meta);
+          handleAdminFileUpload(e.target.files[0], onChange, meta, state);
         }
       });
     }
@@ -164,6 +233,7 @@ const FileUploadField = {
     const value = vnode.attrs.value || '';
     const onChange = vnode.attrs.onChange;
     const readonly = vnode.attrs.readonly || false;
+    const state = vnode.state;
     const meta = col.ui || {};
     const label = meta.label || formatColumnLabel(col.name);
     const hint = meta.hint || '';
@@ -176,10 +246,17 @@ const FileUploadField = {
     var maxSize = meta.maxSize || meta.maxBytes || (10 * 1024 * 1024);
     var accept = meta.accept || '*/*';
     var dropZoneId = 'drop-zone-' + col.name;
+    var displayUrl = state.localPreview || value;
+    var clearValue = function () {
+      revokeLocalPreview(state);
+      if (onChange) onChange('');
+    };
     if (readonly) {
       return m('.mb-4', [
         m('label.block.text-sm.font-medium.text-gray-700.dark:text-slate-300.mb-1', label, required ? m('span.text-red-500', ' *') : null),
-        value ? m('a.text-indigo-600.dark:text-indigo-400.break-all', { href: value, target: '_blank', rel: 'noopener noreferrer' }, value) : m('span.text-gray-400.dark:text-slate-500', '—'),
+        value
+          ? renderUploadedFilePreview(value, { accept: accept, readonly: true, label: label })
+          : m('span.text-gray-400.dark:text-slate-500', '—'),
         hint ? m('p.text-xs.text-gray-500.dark:text-slate-400.mt-1', hint) : null,
       ]);
     }
@@ -196,32 +273,29 @@ const FileUploadField = {
           required: required,
           oninput: function (e) { if (onChange) onChange(e.target.value); },
         }),
+        value ? renderUploadedFilePreview(value, { accept: accept, readonly: false, onRemove: clearValue, label: label }) : null,
         hint ? m('p.text-xs.text-gray-500.dark:text-slate-400.mt-1', hint) : null,
       ]);
     }
     return m('.mb-4', [
       m('label.block.text-sm.font-medium.text-gray-700.dark:text-slate-300.mb-1', label, required ? m('span.text-red-500', ' *') : null),
-      m('div#' + dropZoneId + '.border-2.border-dashed.border-gray-300.dark:border-slate-600.rounded-lg.p-8.text-center.bg-gray-50.dark:bg-slate-900/40', { style: 'cursor: pointer;' }, [
+      displayUrl
+        ? renderUploadedFilePreview(displayUrl, { accept: accept, readonly: false, onRemove: clearValue, label: label })
+        : null,
+      m('div#' + dropZoneId + '.border-2.border-dashed.border-gray-300.dark:border-slate-600.rounded-lg.p-6.text-center.bg-gray-50.dark:bg-slate-900/40', { style: 'cursor: pointer;' }, [
         m('input[type=file].hidden', {
           id: 'file-input-' + col.name,
           accept: accept,
           onchange: function (e) {
             if (e.target.files.length > 0) {
-              handleAdminFileUpload(e.target.files[0], onChange, meta);
+              handleAdminFileUpload(e.target.files[0], onChange, meta, state);
             }
           },
         }),
         m('div', [
-          m('p.text-gray-600.dark:text-slate-400.mb-2', 'Drag and drop a file here, or'),
-          m('label.text-blue-600.hover:text-blue-800.dark:text-blue-400.cursor-pointer', { for: 'file-input-' + col.name }, 'browse'),
+          m('p.text-gray-600.dark:text-slate-400.mb-2', displayUrl ? 'Drag and drop to replace, or' : 'Drag and drop a file here, or'),
+          m('label.text-blue-600.hover:text-blue-800.dark:text-blue-400.cursor-pointer', { for: 'file-input-' + col.name }, displayUrl ? 'choose another file' : 'browse'),
         ]),
-        value ? m('.mt-4.text-left', [
-          m('p.text-sm.text-gray-600.dark:text-slate-400.break-all', 'Current: ' + value),
-          m('button.text-red-600.dark:text-red-400.hover:text-red-800.dark:hover:text-red-300.text-sm.mt-2', {
-            type: 'button',
-            onclick: function () { if (onChange) onChange(''); },
-          }, 'Remove'),
-        ]) : null,
       ]),
       m('input[type=hidden]', { name: col.name, value: typeof value === 'string' ? value : '' }),
       m('p.text-xs.text-gray-500.dark:text-slate-400.mt-1', 'Max ' + Math.round(maxSize / 1024 / 1024) + ' MB (server enforces limits)'),
@@ -230,7 +304,7 @@ const FileUploadField = {
   },
 };
 
-async function handleAdminFileUpload(file, onChange, meta) {
+async function handleAdminFileUpload(file, onChange, meta, state) {
   var uploadUrl = '';
   try {
     var cfg = window.__ADMIN_CONFIG__;
@@ -245,6 +319,11 @@ async function handleAdminFileUpload(file, onChange, meta) {
     alert('File too large (max ' + Math.round(maxSize / 1024 / 1024) + ' MB).');
     return;
   }
+  if (state && file.type && file.type.indexOf('image/') === 0) {
+    revokeLocalPreview(state);
+    state.localPreview = URL.createObjectURL(file);
+    m.redraw();
+  }
   var fd = new FormData();
   fd.append('file', file);
   try {
@@ -252,13 +331,18 @@ async function handleAdminFileUpload(file, onChange, meta) {
     var data = {};
     try { data = await res.json(); } catch (e2) { data = {}; }
     if (!res.ok) {
+      revokeLocalPreview(state);
+      m.redraw();
       alert(data.message || data.error || ('Upload failed (' + res.status + ')'));
       return;
     }
+    revokeLocalPreview(state);
     var url = data.url || data.publicUrl || '';
     if (onChange) onChange(url);
     m.redraw();
   } catch (err) {
+    revokeLocalPreview(state);
+    m.redraw();
     alert(err.message || 'Upload failed');
   }
 }

package/plugins/admin-panel/field-renderers/file-upload.js

@@ -13,8 +13,76 @@ function getUploadUrlFromAdminConfig() {
   }
 }
 
+function isImageAccept(accept) {
+  return accept && accept !== '*/*' && String(accept).includes('image');
+}
+
+function isImageUrl(url) {
+  if (!url || typeof url !== 'string') return false;
+  if (url.startsWith('blob:')) return true;
+  return /\.(jpe?g|png|gif|webp|svg|avif|bmp|ico)(\?|#|$)/i.test(url.trim());
+}
+
+function shouldShowImagePreview(url, accept) {
+  return isImageAccept(accept) || isImageUrl(url);
+}
+
+function renderUploadedFilePreview(url, { accept, readonly, onRemove, label }) {
+  if (!url) return null;
+
+  if (shouldShowImagePreview(url, accept)) {
+    return m('.mt-3.flex.flex-col.items-start.gap-2', [
+      m('a.block', { href: url, target: '_blank', rel: 'noopener noreferrer' },
+        m('img.max-h-48.max-w-full.rounded-lg.border.border-gray-200.dark:border-slate-600.object-contain.bg-white.dark:bg-slate-900.shadow-sm', {
+          src: url,
+          alt: label || 'Preview',
+          loading: 'lazy',
+        })
+      ),
+      m('p.text-xs.text-gray-500.dark:text-slate-400.break-all', url),
+      !readonly && onRemove
+        ? m('button.text-red-600.dark:text-red-400.hover:text-red-800.dark:hover:text-red-300.text-sm', {
+            type: 'button',
+            onclick: onRemove,
+          }, 'Remove')
+        : null,
+    ]);
+  }
+
+  return m('.mt-3.flex.flex-col.items-start.gap-2', [
+    m('a.text-sm.text-indigo-600.dark:text-indigo-400.break-all', {
+      href: url,
+      target: '_blank',
+      rel: 'noopener noreferrer',
+    }, url),
+    !readonly && onRemove
+      ? m('button.text-red-600.dark:text-red-400.hover:text-red-800.dark:hover:text-red-300.text-sm', {
+          type: 'button',
+          onclick: onRemove,
+        }, 'Remove')
+      : null,
+  ]);
+}
+
+function revokeLocalPreview(state) {
+  if (state?.localPreview) {
+    try {
+      URL.revokeObjectURL(state.localPreview);
+    } catch {
+      // ignore
+    }
+    state.localPreview = null;
+  }
+}
+
 module.exports = {
   FileUploadField: {
+    oninit: (vnode) => {
+      vnode.state.localPreview = null;
+    },
+    onremove: (vnode) => {
+      revokeLocalPreview(vnode.state);
+    },
     oncreate: (vnode) => {
       const { name, meta = {} } = vnode.attrs;
       if (!getUploadUrlFromAdminConfig()) return;
@@ -60,17 +128,24 @@ module.exports = {
     },
 
     view: (vnode) => {
-      const { name, value = '', meta = {}, required = false } = vnode.attrs;
+      const { name, value = '', meta = {}, required = false, readonly = false } = vnode.attrs;
+      const state = vnode.state;
       const dropZoneId = 'drop-zone-' + name;
       const maxSize = meta.maxSize || meta.maxBytes || 10 * 1024 * 1024;
       const accept = meta.accept || '*/*';
       const uploadUrl = getUploadUrlFromAdminConfig();
+      const displayUrl = state.localPreview || value;
+      const label = meta.label || name;
+      const clearValue = () => {
+        revokeLocalPreview(state);
+        if (vnode.attrs.onchange) vnode.attrs.onchange('');
+      };
 
       if (!uploadUrl) {
         return m('.mb-4', [
           m(
             'label.block.text-sm.font-medium.mb-2',
-            meta.label || name,
+            label,
             required ? m('span.text-red-500', ' *') : null
           ),
           m('p.text-xs.text-amber-700.dark:text-amber-400.mb-2', 'Upload URL is not configured.'),
@@ -80,62 +155,57 @@ module.exports = {
             value: typeof value === 'string' ? value : '',
             placeholder: 'https://… or /uploads/…',
             required,
+            readonly,
             oninput: (e) => {
               if (vnode.attrs.onchange) vnode.attrs.onchange(e.target.value);
             },
           }),
+          value
+            ? renderUploadedFilePreview(value, { accept, readonly, onRemove: clearValue, label })
+            : null,
         ]);
       }
 
       return m('.mb-4', [
         m(
           'label.block.text-sm.font-medium.mb-2',
-          meta.label || name,
+          label,
           required ? m('span.text-red-500', ' *') : null
         ),
+        displayUrl
+          ? renderUploadedFilePreview(displayUrl, { accept, readonly, onRemove: clearValue, label })
+          : null,
         m(
-          'div.border-2.border-dashed.border-gray-300.dark:border-slate-600.rounded.p-8.text-center',
+          'div.border-2.border-dashed.border-gray-300.dark:border-slate-600.rounded.p-6.text-center',
           {
             id: dropZoneId,
-            style: 'cursor: pointer;',
+            style: readonly ? undefined : 'cursor: pointer;',
           },
           [
             m('input[type=file]', {
               class: 'hidden',
               id: 'file-input-' + name,
               accept,
+              disabled: readonly,
               onchange: (e) => {
                 if (e.target.files.length > 0) {
                   handleFileUpload(e.target.files[0], vnode, meta);
                 }
               },
             }),
-            m('div', [
-              m('p.text-gray-600.dark:text-slate-400.mb-2', 'Drag and drop a file here, or'),
-              m(
-                'label.text-blue-600.hover:text-blue-800.cursor-pointer',
-                { for: 'file-input-' + name },
-                'browse'
-              ),
-            ]),
-            value
-              ? m('.mt-4', [
+            readonly
+              ? null
+              : m('div', [
                   m(
-                    'p.text-sm.text-gray-600.break-all',
-                    'Current: ' + (typeof value === 'string' ? value : value.name || 'uploaded')
+                    'p.text-gray-600.dark:text-slate-400.mb-2',
+                    displayUrl ? 'Drag and drop to replace, or' : 'Drag and drop a file here, or'
                   ),
                   m(
-                    'button.text-red-600.hover:text-red-800.text-sm.mt-2',
-                    {
-                      type: 'button',
-                      onclick: () => {
-                        if (vnode.attrs.onchange) vnode.attrs.onchange('');
-                      },
-                    },
-                    'Remove'
+                    'label.text-blue-600.hover:text-blue-800.cursor-pointer',
+                    { for: 'file-input-' + name },
+                    displayUrl ? 'choose another file' : 'browse'
                   ),
-                ])
-              : null,
+                ]),
           ]
         ),
         m('input[type=hidden]', {
@@ -169,6 +239,12 @@ async function handleFileUpload(file, vnode, meta) {
     return;
   }
 
+  if (file.type?.startsWith('image/')) {
+    revokeLocalPreview(vnode.state);
+    vnode.state.localPreview = URL.createObjectURL(file);
+    if (typeof m !== 'undefined' && m.redraw) m.redraw();
+  }
+
   const fd = new FormData();
   fd.append('file', file);
 
@@ -181,13 +257,18 @@ async function handleFileUpload(file, vnode, meta) {
       data = {};
     }
     if (!res.ok) {
+      revokeLocalPreview(vnode.state);
+      if (typeof m !== 'undefined' && m.redraw) m.redraw();
       alert(data.message || data.error || `Upload failed (${res.status})`);
       return;
     }
+    revokeLocalPreview(vnode.state);
     const url = data.url || data.publicUrl || '';
     if (vnode.attrs.onchange) vnode.attrs.onchange(url);
     if (typeof m !== 'undefined' && m.redraw) m.redraw();
   } catch (err) {
+    revokeLocalPreview(vnode.state);
+    if (typeof m !== 'undefined' && m.redraw) m.redraw();
     alert(err.message || 'Upload failed');
   }
 }

package/templates/skills/webspresso-usage/REFERENCE-framework.md

@@ -169,6 +169,7 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 - **Relations:** `belongsTo`, `hasMany`, `hasOne` with `model: () => OtherModel`.
 - **Scopes:** `softDelete`, `timestamps`, optional `tenant` column.
 - **`hidden`:** columns never exposed in admin/API (e.g. `password_hash`).
+- **`zdb.file()`:** varchar column for uploaded asset URL/path; admin forms render a file upload widget when `uploadPlugin` is registered (or `adminPanelPlugin({ uploadUrl })`). Optional `ui: { label, accept, maxBytes }`. For `zdb.string()` columns use `admin.customFields: { col: { type: 'file-upload' } }`.
 - **Nanoid PK:** `zdb.nanoid()` / `zdb.nanoid({ maxLength: 12 })` — string primary key; migrations use `string(length)`. On **`create()`**, omitting the PK auto-fills a URL-safe id (built-in generator, same alphabet as `nanoid`). Use **`zdb.foreignNanoid('table', { maxLength })`** when the parent uses nanoid PKs; **`generateNanoid`** is exported from `webspresso` for manual ids. In API **`schema`**, use **`z.nanoid()`** / **`z.nanoid(12)`** / **`z.nanoid({ maxLength })`** (the `z` from `schema: ({ z })` is extended by Webspresso). **`zodNanoid`** / **`extendZ`** are also exported for non-route use.
 
 **Database:** `createDatabase({ client, connection, models: './models' })` — auto-loads `models/*.js` (ignore `_prefix`).
@@ -197,7 +198,7 @@ Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and pl
 | `adminPanelPlugin` | SPA admin CRUD — needs **`db`**; optional **`uploadUrl`** (or infer from **`uploadPlugin`**); optional **`userManagement: { enabled, model, fields }`** + **`auth`** (same **`AuthManager`** as **`createApp({ auth })`**) for site-user CRUD + remember-me session UI — see **Session authentication** above |
 | `dataExchangePlugin` | Admin-only **Excel export** + **CSV/XLSX import** under `${adminPath}/api/data-exchange/*`; register **after** `adminPanelPlugin` with same `db` / `adminPath`; optional `maxRows`, `maxFileBytes`; adds UI buttons + bulk `export-xlsx` |
 | `redirectPlugin` | Configurable **301–308** redirects in `register()` — runs **before** file-based SSR routes; `rules` (`from` path or `RegExp`, `to`, `status`, `methods`), `preserveQuery`, `allowExternal`, `trailingSlash`, `defaultMethods`; docs **[`doc/index.html#plugins-redirect`](../../../doc/index.html#plugins-redirect)**, README **Redirect plugin** |
-| `uploadPlugin` | `POST` multipart (`multer`), `createLocalFileProvider` or custom `provider`; set **`mimeAllowlist`** / **`maxBytes`** in production |
+| `uploadPlugin` | `POST` multipart (`multer`), `createLocalFileProvider` or custom `provider`; set **`mimeAllowlist`** / **`maxBytes`** in production; pairs with admin **`zdb.file()`** / **`customFields.file-upload`** when registered before **`adminPanelPlugin`** |
 | `siteAnalyticsPlugin` | Self-hosted page views + admin charts |
 | `auditLogPlugin` | Admin mutation audit trail |
 | `recaptchaPlugin` | v2/v3 + middleware |