Module

@adminjs/koa

This is an official plugin allowing you to run AdminJS on

koa framework.

installation

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

yarn add adminjs @adminjs/koa @koa/router koa2-formidable

now you can use either buildRouter or buildAuthenticatedRouter functions.

Usage

const { buildRouter } = require('@adminjs/koa')
// or
const { buildAuthenticatedRouter } = require('@adminjs/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 AdminJS.

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 AdminJS routes.

Example without an authentication

const AdminJS = require('adminjs')
const { buildRouter } = require('@adminjs/koa')

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

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

const router = buildRouter(adminJs, 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(AdminJS, 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 adminjs-koa/src/index.ts, line 2

Methods

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

Builds authenticated koa router.
Parameters:
Name Type Attributes Description
admin AdminJS

AdminJS 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 adminjs-koa/src/buildAuthenticatedRouter.ts, line 20

@koa/router

Router

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

Builds regular koa router.
Parameters:
Name Type Attributes Description
admin AdminJS

AdminJS 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 adminjs-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 adminjs-koa/src/types.ts, line 6

Promise.<CurrentAdmin>
object

# KoaAuthOptions

Authentication options
Properties:
Name Type Attributes Description
authenticate KoaAuthenticateFunction

Function returning CurrentAdmin

sessionOptions Partial.<SessionOptions> <optional>

Session options passed to koa-session

View Source adminjs-koa/src/types.ts, line 18