Module

@admin-bro/koa

This is an official plugin allowing you to run AdminBro on koa framework.

installation

Assuming you have koa installed, you have to also install this package along with its peerDependencies:

yarn add admin-bro @admin-bro/koa @koa/router koa2-formidable

now you can use either buildRouter or buildAuthenticatedRouter functions.

Usage

const { buildRouter } = require('@admin-bro/koa')
// or
const { buildAuthenticatedRouter } = require('@admin-bro/koa')

As you can see it exposes 2 methods that create an Koa Router, which can be attached to a given url in the API. Each method takes a pre-configured 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 { buildRouter } = require('@admin-bro/koa')

const Koa = require('koa');
const app = new Koa();

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

const router = buildRouter(adminBro, app)

app
  .use(router.routes())
  .use(router.allowedMethods())

app.listen(3000)

Using build in authentication

Plugin gives you a second method: buildAuthenticatedRouter. In order to have sign in logic out of the box - you can use it.

Example with build in authentication

Build in authentication is using cookie. So in order to make it work you have to set set koa app.keys:

const app = new Koa();
app.keys = ['super-secret1', super-'secret2']

And this is how buildAuthenticatedRouter might look like:

const router = buildAuthenticatedRouter(adminBro, app, {
    authenticate: async (email, password) => {
      const user = await User.findOne({ email })
      if (password && user && await argon2.verify(user.encryptedPassword, password)){
        return user.toJSON()
      }
      return null
    },
  })
  • We used argon2 to decrypt the password.
  • In the example User is a mongoose model.

Adding custom authentication

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

In this predefined router you can protect the routes with a session authentication where you can use any middleware you want. Furthermore, you can create your own sign-in/sign-up form.

Methods

# static buildAuthenticatedRouter(admin, app, auth, predefinedRouteropt, formidableOptions) → {Router}

Builds regular koa router.

Parameters:
Name Type Attributes Description
admin AdminBro

AdminBro instance

app Application

koa application created by new Koa()

auth KoaAuthOptions

authentication options

predefinedRouter Router <optional>

if you have any predefined router pass it here

formidableOptions FormidableOptions

options passed to formidable module https://github.com/node-formidable/formidable#options

View Source admin-bro-koa/src/buildAuthenticatedRouter.ts, line 27

@koa/router

Router

# static buildRouter(admin, app, predefinedRouteropt, formidableOptions) → {Router}

Builds regular koa router.

Parameters:
Name Type Attributes Description
admin AdminBro

AdminBro instance

app Application

koa application created by new Koa()

predefinedRouter Router <optional>

if you have any predefined router pass it here

formidableOptions FormidableOptions

options passed to formidable module https://github.com/node-formidable/formidable#options

View Source admin-bro-koa/src/buildRouter.ts, line 18

@koa/router

Router

Type Definitions

# KoaAuthenticateFunction(email, password) → {Promise.<CurrentAdmin>}

An async authentication function, returning CurrentAdmin

Parameters:
Name Type Description
email string

email address passed in a form

password string

Password passed in a form

View Source admin-bro-koa/src/types.ts, line 4

Promise.<CurrentAdmin>
object

# KoaAuthOptions

Authentication options

Properties:
Name Type Description
authenticate KoaAuthenticateFunction

Function returning CurrentAdmin

View Source admin-bro-koa/src/types.ts, line 16