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
},
})
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}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
admin |
AdminJS
|
AdminJS instance |
|
app |
Application
|
koa application created by |
|
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 |
@koa/router
# static buildRouter(admin, app, predefinedRouteropt, formidableOptions) → {Router}
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
admin |
AdminJS
|
AdminJS instance |
|
app |
Application
|
koa application created by |
|
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 |
@koa/router
Type Definitions
# KoaAuthenticateFunction(email, password) → {Promise.<CurrentAdmin>}
Parameters:
Name | Type | Description |
---|---|---|
email |
string
|
email address passed in a form |
password |
string
|
Password passed in a form |
Promise.<CurrentAdmin>
object
# KoaAuthOptions
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
authenticate |
KoaAuthenticateFunction
|
Function returning CurrentAdmin |
|
sessionOptions |
Partial.<SessionOptions>
|
<optional> |
Session options passed to koa-session |