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.

View Source admin-bro-koa/src/index.ts, line 2

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

Returns:

@koa/router

Type: 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