Module

admin-bro-expressjs

Plugin that allows you to add AdminBro to Express.js applications.

Installation

npm install admin-bro-expressjs

It has 2 peerDependencies: express-formidable and express, so you have to install them as well.

Usage

const AdminBroExpress = require('admin-bro-expressjs')

It exposes 2 methods that create an Express Router, which can be attached to a given url in the API. Each method takes a preconfigured instance of AdminBro.

If you want to use a router you have already created - not a problem. Just pass it as a predefinedRouter parameter.

You may want to use this option when you want to include some custom auth middleware for you AdminBro routes.

Example without an authentication

const AdminBro = require('admin-bro')
const AdminBroExpress = require('admin-bro-expressjs')

const express = require('express')
const app = express()

const adminBro = new AdminBro({
  databases: [],
  rootPath: '/admin',
})

const router = AdminBroExpress.buildRouter(adminBro)
app.use(adminBro.options.rootPath, router)
app.listen(8080, () => console.log('AdminBro is under localhost:8080/admin'))

Using build in authentication

To protect the routes with a session authentication, you can use predefined module:admin-bro-expressjs.buildAuthenticatedRouter method.

Note! To use authentication in production environment, there is a need to configure express-session for production build. It can be achieved by passing options to sessionOptions parameter. Read more on express/session Github page

Adding custom authentication

You can add your custom authentication setup by firstly creating the router and then passing it via the predefinedRouter option.

let router = express.Router()
router.use((req, res, next) => {
  if (req.session && req.session.admin) {
    req.session.adminUser = req.session.admin
    next()
  } else {
    res.redirect(adminBro.options.loginPath)
  }
})
router = AdminBroExpress.buildRouter(adminBro, router)

Where req.session.admin is AdminBro#CurrentAdmin, meaning that it should have at least an email property.

View Source admin-bro-expressjs/index.js, line 1

Members

# static name

Plugin name

View Source admin-bro-expressjs/plugin.js, line 202

# static version

Version of the plugin

View Source admin-bro-expressjs/plugin.js, line 196

Methods

# static buildAuthenticatedRouter(admin, auth, predefinedRouteropt, sessionOptionsopt) → {express.Router}

Builds the Express Router which is protected by a session auth

Using the router requires you to install express-session as a dependency.

Parameters:
Name Type Attributes Default Description
admin AdminBro

instance of AdminBro
auth Object

authentication options
authenticate module:admin-bro-expressjs.Authenticate

authenticate function
cookiePassword String

secret used to encrypt cookies
cookieName String adminbro

cookie name
predefinedRouter express.Router <optional>

Express.js router
sessionOptions session.options <optional>

Options that are passed to express-session

View Source admin-bro-expressjs/plugin.js, line 132

Express.js router

express.Router
Example
const ADMIN = {
  email: '[email protected]',
  password: 'password',
}

AdminBroExpress.buildAuthenticatedRouter(adminBro, {
  authenticate: async (email, password) => {
    if (ADMIN.password === password && ADMIN.email === email) {
      return ADMIN
    }
    return null
  },
  cookieName: 'adminbro',
  cookiePassword: 'somepassword',
}, [router])

# static buildRouter(admin, predefinedRouteropt) → {express.Router}

Builds the Express Router that handles all the pages and assets

Parameters:
Name Type Attributes Description
admin AdminBro

instance of AdminBro
predefinedRouter express.Router <optional>

Express.js router

View Source admin-bro-expressjs/plugin.js, line 27

Express.js router

express.Router

Type Definitions

# Authenticate(emailopt, passwordopt) → {CurrentAdmin|null}

function taking 2 arguments email and password

Parameters:
Name Type Attributes Description
email string <optional>

email given in the form
password string <optional>

password given in the form

View Source admin-bro-expressjs/plugin.js, line 89

returns current admin or null

CurrentAdmin | null