AdminJS Integration

Experimental

This feature is experimental and may change in future versions. Use with caution in production environments.

Hysteria ORM provides built-in integration with AdminJS, a powerful auto-generated admin panel for Node.js applications. This integration allows you to quickly set up an admin interface for your models without writing any additional code.

Installation

AdminJS and its dependencies are optional peer dependencies. Install them based on your needs:

# Core AdminJS package
npm install adminjs

# For Express integration
npm install adminjs @adminjs/express express express-formidable

Basic Setup

Enable AdminJS when connecting to your database by providing the adminJs configuration option:

import { SqlDataSource, column, Model } from "hysteria-orm";

class User extends Model {
  static table = "users";

  @column.bigIncrement()
  id!: number;

  @column({ type: "varchar", length: 100 })
  name!: string;

  @column({ type: "varchar", length: 255 })
  email!: string;

  @column({ type: "integer" })
  age!: number;

  @column({ type: "boolean" })
  isActive!: boolean;

  @column.date({ autoCreate: true })
  createdAt!: Date;
}

const sql = await SqlDataSource.connect({
  type: "postgres",
  host: "localhost",
  port: 5432,
  username: "root",
  password: "root",
  database: "test",
  models: {
    User,
  },
  adminJs: {
    enabled: true,
    rootPath: "/admin",
  },
});

Express Integration

The most common use case is integrating AdminJS with an Express application:

import express from "express";
import { SqlDataSource, column, Model } from "hysteria-orm";

class User extends Model {
  static table = "users";

  @column.bigIncrement()
  id!: number;

  @column({ type: "varchar", length: 100 })
  name!: string;

  @column({ type: "varchar", length: 255 })
  email!: string;

  @column({ type: "integer" })
  age!: number;

  @column({ type: "boolean" })
  isActive!: boolean;

  @column.date({ autoCreate: true })
  createdAt!: Date;
}

(async () => {
  const sql = await SqlDataSource.connect({
    type: "postgres",
    host: "localhost",
    port: 5432,
    username: "root",
    password: "root",
    database: "test",
    models: {
      User,
    },
    adminJs: {
      enabled: true,
      rootPath: "/admin",
      branding: {
        companyName: "My App Admin",
        withMadeWithLove: false,
      },
      resourceOptions: {
        users: {
          navigation: {
            name: "User Management",
            icon: "User",
          },
          listProperties: ["id", "name", "email", "isActive"],
          showProperties: ["id", "name", "email", "age", "isActive", "createdAt"],
          editProperties: ["name", "email", "age", "isActive"],
          filterProperties: ["name", "email", "isActive"],
        },
      },
    },
  });

  const app = express();

  // Initialize AdminJS with Express router
  const { router, admin } = await sql.initializeAdminJsExpress();

  // Mount the AdminJS router
  app.use(admin.options.rootPath, router as express.Router);

  app.listen(3000, () => {
    console.log("AdminJS running at http://localhost:3000/admin");
  });
})();

Configuration Options

AdminJsOptions

Option	Type	Default	Description
enabled	boolean	false	Enable AdminJS integration
rootPath	string	"/admin"	Root URL path for the admin panel
branding	AdminJsBranding	-	Custom branding options
resources	Model[]	-	Specific models to expose (defaults to all registered models)
resourceOptions	Record<string, AdminJsResourceOptions>	-	Per-model configuration
locale	AdminJsLocale	-	Localization settings
assets	AdminJsAssets	-	Custom CSS/JS assets
settings	AdminJsSettings	-	General settings
pages	Record<string, AdminJsPage>	-	Custom pages

Branding Options

adminJs: {
  enabled: true,
  branding: {
    companyName: "My Company",
    logo: "https://example.com/logo.png",
    favicon: "https://example.com/favicon.ico",
    withMadeWithLove: false,
    theme: {
      colors: {
        primary100: "#4268F6",
      },
    },
  },
}

Resource Options

Configure how each model appears in the admin panel:

adminJs: {
  enabled: true,
  resourceOptions: {
    users: {
      // Navigation grouping
      navigation: {
        name: "User Management",
        icon: "User",
      },

      // Custom display name
      name: "Users",

      // Properties shown in list view
      listProperties: ["id", "name", "email", "isActive"],

      // Properties shown in detail view
      showProperties: ["id", "name", "email", "age", "isActive", "createdAt"],

      // Properties available for editing
      editProperties: ["name", "email", "age", "isActive"],

      // Properties available for filtering
      filterProperties: ["name", "email", "isActive"],

      // Default sorting
      sort: {
        sortBy: "createdAt",
        direction: "desc",
      },

      // Property-level configuration
      properties: {
        email: {
          isRequired: true,
          description: "User's email address",
        },
        age: {
          type: "number",
          isVisible: {
            list: false,
            edit: true,
            filter: false,
            show: true,
          },
        },
      },
    },
  },
}

API Reference

SqlDataSource Methods

initializeAdminJsExpress()

Initializes AdminJS with an Express router. Returns an AdminJsInstance with both admin and router properties.

const { admin, router } = await sql.initializeAdminJsExpress();

getAdminJs()

Returns the cached AdminJS instance if already initialized.

const adminInstance = sql.getAdminJs();

isAdminJsEnabled()

Checks if AdminJS is enabled in the configuration.

if (sql.isAdminJsEnabled()) {
  // AdminJS is configured
}

Static Methods

All instance methods are also available as static methods on SqlDataSource:

// Static usage
const { admin, router } = await SqlDataSource.initializeAdminJsExpress();
const isEnabled = SqlDataSource.isAdminJsEnabled();

Type Definitions

AdminJsInstance

type AdminJsInstance = {
  admin: {
    options: { rootPath: string; [key: string]: unknown };
    watch: () => Promise<void>;
    initialize: () => Promise<void>;
    resources: unknown[];
    findResource: (resourceId: string) => unknown;
  };
  router?: unknown;
};

Supported Features

The AdminJS integration automatically provides:

• List View: Browse records with pagination and sorting
• Create: Add new records
• Edit: Modify existing records
• Delete: Remove records
• Filtering: Filter records by properties
• Search: Search across text fields

Limitations

Current Limitations

• Authentication is not built-in; implement your own auth middleware
• File uploads require additional configuration
• Complex relationships may need custom handling
• Some AdminJS features may require direct AdminJS configuration

See Also

• AdminJS Documentation
• Models
• Caching