@airoom/nextmin-node

Schema‑driven Node.js toolkit that turns a JSON schema into a secure, policy‑aware REST API with authentication, CRUD, relationship querying, and file uploads. Pair it with @airoom/nextmin-react to get a fully‑featured Admin Panel in minutes.

• “From JSON schema to REST API + Admin”
• 1 month → 1 hour

Documentation

Read the full documentation at: https://nextmin.gscodes.dev/

Highlights

• Express router factory: mount a complete REST API in a few lines
• Auth built in: register, login, me, change‑password, forgot‑password
• CRUD per model with read masks, write restrictions, and role/owner policies
• Advanced list endpoint: filter, multi‑field search, date ranges, multi‑field sort, paginate
• Relationship endpoints: forward and reverse lookups without autopopulate
• Schemas hot‑reload during development; automatic model wiring
• File uploads via pluggable storage (e.g., S3/MinIO); delete by key
• Database adapters: MongoDB (with index sync) and in‑memory for tests
• Emits a trusted API key stored in your Settings model for client access

Installation

# npm
npm install @airoom/nextmin-node

# yarn
yarn add @airoom/nextmin-node

# pnpm
pnpm add @airoom/nextmin-node

Quick start (Express + Mongo + S3 optional)

import dotenv from 'dotenv';
import express from 'express';
import http from 'http';
import {
  createNextMinRouter,
  MongoAdapter,
  S3FileStorageAdapter,
} from '@airoom/nextmin-node';
import cors from 'cors';

dotenv.config();

async function start() {
  const app = express();
  const server = http.createServer(app); // pass this to the router for sockets

  app.use(cors());

  // 1) Database
  const db = new MongoAdapter(process.env.MONGO_URL!, process.env.MONGO_DB!);
  await db.connect();

  // 2) Optional: file storage adapter (S3/MinIO)
  const files = new S3FileStorageAdapter({
    bucket: process.env.S3_BUCKET!,
    region: process.env.S3_REGION!,
    credentials:
      process.env.S3_ACCESS_KEY_ID && process.env.S3_SECRET_ACCESS_KEY
        ? {
            accessKeyId: process.env.S3_ACCESS_KEY_ID!,
            secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
          }
        : undefined,
    endpoint: process.env.S3_ENDPOINT || undefined,
    forcePathStyle: /^(1|true|yes)$/i.test(process.env.S3_FORCE_PATH_STYLE || ''),
    defaultACL: (process.env.S3_DEFAULT_ACL as any) || 'public-read',
    publicBaseUrl: process.env.S3_PUBLIC_BASE_URL || undefined,
  });

  // 3) Mount NextMin REST router
  const router = createNextMinRouter({ dbAdapter: db, server, fileStorageAdapter: files });
  app.use('/rest', router);

  // 4) Listen with the same server instance
  const port = Number(process.env.PORT || 8081);
  server.listen(port, () => console.log(`REST ready: http://localhost:${port}/rest`));
}

start().catch((e) => {
  console.error(e);
  process.exit(1);
});

REST endpoints (summary)

Base: /rest

• Schemas: GET /_schemas → public schema list (requires x-api-key)
• Auth (users):
  • POST /auth/users/register
  • POST /auth/users/login
  • GET /auth/users/me
  • POST /auth/users/change-password
  • POST /auth/users/forgot-password
• Generic CRUD per model (model names are lowercase):
  • POST /:model
  • GET /:model (query: page, limit, q, searchKey(s), searchMode, dateFrom/to/key, sort, sortType)
  • GET /:model/:id
  • PUT /:model/:id (or PATCH depending on client)
  • DELETE /:model/:id
• Relationship queries:
  • Forward: GET /find/:container/:refField/:id
  • Reverse: GET /find/reverse/:target/:byField/:id
• Files (when file storage adapter is configured):
  • Upload: POST /files (multipart form, fields named file)
  • Delete: DELETE /files/:key(*)

See full examples in documentation and the examples/node app inside this monorepo.

Headers and auth

• All requests must include the API key header: x-api-key: <YOUR_API_KEY>
• Authenticated routes also require: Authorization: Bearer <JWT>

Where do I find my API key?

• On first run, the server initializes default data and stores a trusted apiKey in your Settings collection/table.
• Copy that value into your clients. You can also preseed it by setting NEXTMIN_API_KEY before the first boot.

Configuration (env)

Application

• APP_MODE: development | production (affects dev features)
• JWT_SECRET: secret used to sign JWTs

Database

• MONGO_URL: e.g. mongodb://localhost:27017
• MONGO_DB: database name

File storage (optional)

• S3_BUCKET, S3_REGION
• S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY
• S3_ENDPOINT (for MinIO or custom)
• S3_FORCE_PATH_STYLE (true for MinIO)
• S3_DEFAULT_ACL (e.g., public-read)
• S3_PUBLIC_BASE_URL (CDN/base URL for public links)

Frontend integration

• NEXT_PUBLIC_GOOGLE_MAPS_KEY (used by address autocomplete within the Admin UI)

Default super admin (after setup)

After the initial setup, you can sign in with the default super user and should immediately change the password:

• Email: [email protected]
• Username: superadmin
• Password: supersecurepassword

Change it right after the first login.

TypeScript

Types are bundled. Example import:

import type { APIRouterOptions } from '@airoom/nextmin-node';

Troubleshooting

• 401 Unauthorized: verify x-api-key matches Settings.apiKey and that JWT is present for protected routes.
• CORS issues: allow your frontend origin in development.
• Sorting/filters: unknown fields are ignored; ensure you pass existing attribute names.
• Relationship endpoints: confirm your schema uses proper ref fields.

License

Licensed under the Nextmin Proprietary License. © 2025 GSCodes. For commercial licensing or extended rights, contact: [email protected].