nextmin-react

React components, pages, and utilities for building an admin dashboard on top of a nextmin-node backend.

Features

• Provider: <NextMinProvider> initializes the Redux store, loads schemas, and opens a live socket
• Admin shell: <AdminApp> renders Auth, Sidebar, and all CRUD pages for your schemas
• Internal router: <NextMinRouter> and <AdminRouteNormalizer> handle admin routes
• Pages: Auth (sign in/up/forgot), Dashboard, List, Create/Edit, Profile, Settings
• Components: Sidebar, SchemaForm, FileUploader, Ref selects, Phone/Password inputs, Table and filters
• Hooks/Utils: Google address autocomplete, list data helpers, formatting helpers

This page shows the exact setup used in the examples/react app.

Installation

# npm
npm install @airoom/nextmin-react
 
# yarn
yarn add @airoom/nextmin-react
 
# pnpm
pnpm add @airoom/nextmin-react

Configure environment

The client reads these env vars:

NEXT_PUBLIC_NEXTMIN_API_URL=http://localhost:8081/rest
# IMPORTANT: Use the API key stored in your database → Settings table
NEXT_PUBLIC_NEXTMIN_API_KEY=your_api_key_here

• NEXT_PUBLIC_NEXTMIN_API_URL should point to your nextmin-node REST base (e.g., http://host:port/rest )
• NEXT_PUBLIC_NEXTMIN_API_KEY must equal the value in your DB Settings document’s apiKey field

Where to find it:

• Start your nextmin-node server once so initialization runs
• Open your database and locate the Settings collection/table
• Copy the first Settings document’s apiKey value and use it here

Default admin credentials (after setup)

After you complete the basic setup and run the server, you can sign in to the Admin with the following default super user:

• Email: super@example.com
• Username: superadmin
• Password: supersecurepassword

For security, make sure to change this password after your first login (Profile → Change password) and, if needed, update the email/username in your Users collection.

App routing (as in examples/react)

Create an admin section that’s fully client-side. The provider wraps only the admin area.

// app/admin/layout.tsx
'use client'
 
import { NextMinProvider } from '@airoom/nextmin-react';
import theme from '../../nextmin-theme';
 
export default function AdminLayout({ children }: { children: React.ReactNode }) {
  return (
    <NextMinProvider theme={theme}>
      {children}
    </NextMinProvider>
  );
}

// app/admin/page.tsx
'use client'
 
import { AdminApp } from '@airoom/nextmin-react';
 
export default function AdminIndex() {
  return <AdminApp />;
}

// app/admin/[...slug]/page.tsx
'use client'
 
import { AdminApp } from '@airoom/nextmin-react';
 
export default function AdminCatchAll() {
  return <AdminApp />;
}

What this gives you:

• AdminApp reads the session from localStorage and redirects:
  • Unauthenticated users are sent to /admin/auth/sign-in
  • Authenticated users visiting /admin/auth/* are redirected to /admin/dashboard
• Inside the shell, Sidebar is shown and NextMinRouter renders pages based on your backend schemas
• Schemas are fetched once via HTTP and then kept in sync over a live socket

Usage notes

• You don’t need to import any CSS manually; the package includes its styles
• Backend paths and auth are configured by env vars (see above)
• To add custom pages inside the admin, link to routes like /admin/your-model/create or /admin/your-model/:id
• The first Settings document (model name “Settings”) is treated as system settings for logo, site name, and Google Maps key

Form Features (SchemaForm)

The SchemaForm component drastically reduces boilerplate by rendering forms from JSON schemas.

• Auto Slug Generation: Use populateSlugFrom: "title" in your schema to automatically generate URL-friendly slugs. It handles uniqueness (appending -1, -2) and supports multi-field sources (populateSlugFrom: "firstName,lastName").
• Reference Selects:
  • RefSelect (RefSingleSelect & RefMultiSelect): Searchable async dropdowns with infinite scrolling, server-side search, eager label hydration (fetchLabels), and automatic column projection (select: 'id,_id,name,title').
  • In-Flight Request Deduplication: Duplicate concurrent GET requests from multiple dropdowns on the same form are automatically deduplicated on the client.
• Client Projection (QueryBuilder.select):
  • api.list() and QueryBuilder support passing explicit column projections (e.g. api.list('Hospitals', { select: 'id,name' })), ensuring the backend only selects required fields from the database.
• Improved JSON Groups: Support for recursive json-group nesting, allowing complex data structures to be managed with full field support (references, dates, etc.) at any depth.
• Enhanced Validation: Automatic propagation of minLength, maxLength, and pattern (regex) constraints from schema to UI fields.
• Dynamic References (refPath): Support for schema-driven dynamic relations. When an attribute specifies refPath: "discriminantField", <RefSelect> listens to the form state and switches its target collection dynamically.
• Attribute Immutability (readOnly / editable: false): Fields marked with readOnly: true or editable: false in schema definitions automatically render as disabled/read-only in the UI.
• Form Validation Propagation: Error messages and isInvalid states are seamlessly propagated to all form components including Text inputs, Passwords, Textareas, Selects, Radios, Checkboxes, Date/Time pickers, and RefSelects.
• Rich Text: Fields with rich: true render an enhanced Tiptap-based editor with slash commands, font styling, and sanitized output.

Data Table (DataTableHero)

The admin list views are powered by DataTableHero, a feature-packed data table component:

• Multi-Select & Bulk Actions: Select multiple rows via checkboxes. A sticky floating action bar displays the number of selected records and provides batch actions such as Bulk Delete with confirmation modals (ConfirmDialog).
• Schema-Driven Custom Actions: Add custom row action buttons by declaring customActions in your schema:
  jsonCopy

  {
    "customActions": [
      {
        "name": "qr",
        "label": "QR Code",
        "action": "qr",
        "urlTemplate": "https://yourdomain.com/items/{slug}"
      }
    ]
  }

• Built-in QR Code Generator (QRCodeModal):
  • Automatically rendered for actions with action: "qr" or type: "qr".
  • Interpolates dynamic record fields like {slug} and {id} into destination URLs.
  • Live SVG preview with copy link button, open in new tab button, and one-click downloads for SVG and high-resolution PNG (1024x1024).
• Protected System Rows: System records marked by the schema prevent accidental deletion or modification by disabling action buttons with informative tooltips.
• Isolated Cell Selection: Interactive elements inside cells (links, copy triggers, chips) prevent unwanted row selection when clicked.

Viewer (Drawer)

We ship a schema-driven, reusable viewer that opens in a right-side Drawer from list rows. It:

• Adds a View (eye) icon next to Edit/Delete in tables
• Hides system/private fields and masks any password/secret-like fields
• Merges baseId object data into the child for viewing when schemas extend others
• Summarizes raw JSON values (including JSON strings) into readable lines

See details and API: Viewer (Drawer)

Advanced Configuration

• Data Table Custom Actions: Inject custom action buttons horizontally into any row by wrapping the standard table component. This allows firing distinct side-effects, navigations, or modal dialogs specific to a single document instance.
• Conditional Role-Based Password Fields: During standard account creation flows (e.g. creating different types of Users with diverse schema types), the password inputs intelligently hide or require themselves based entirely on the specific access roles targeted, reducing admin friction.

Dynamic Theme System

Customize the nextmin admin dashboard layout, styling, and colors using a config file placed in the host project’s root.

Create a nextmin-theme.ts or nextmin-theme.js at the root of your Next.js application:

import type { ThemeConfig } from '@airoom/nextmin-react';
 
export default {
  // Layout background color
  mainAdminBgColor: '#e0f2fe',
  // Sidebar container color
  sidebarColor: '#0f172a',
  // Active sidebar link background
  activeMenuBgColor: '#38bdf8',
  // Active sidebar link text color
  activeMenuTextColor: '#ffffff',
  // Standard sidebar link text color
  menuTextColor: '#94a3b8',
  // Sidebar link hover background
  menuHoverBgColor: '#1e293b',
  // Sidebar elements text color
  sidebarTextColor: '#f8fafc',
  // Sidebar border colors
  sidebarBorderColor: '#1e293b',
  // Top nav background
  topNavBgColor: '#ffffff',
  // Top nav height
  topNavHeight: '70px',
  // Height of forms inputs/selects and table filter headers
  inputHeight: '48px',
  // Border radius of inputs, selects, and buttons
  inputRadius: '12px',
  // Sidebar width
  sidebarWidth: '280px',
  // Sidebar alignment layout: 'left' or 'right'
  sidebarPosition: 'left',
  // HeroUI primary button and control color
  primaryColor: '#38bdf8',
} as ThemeConfig;

TypeScript

Types are bundled with the package.

import type { ApiItemResponse } from '@airoom/nextmin-react/types';

See also

• Server package: nextmin-node
• Back to Introduction: /docs