description |
---|
@adminjs/adonis |
@adminjs/adonis
is an official integration with AdonisJS and it's Lucid ORM. It supports AdonisJS v6+ and requires NodeJS v20.6.x+.
{% hint style="warning" %}
@adminjs/adonis
currently only supports Lucid as it's ORM. We will soon add support for other database adapters.
{% endhint %}
The easiest way to get started with AdonisJS integration is to follow their official documentation.
Below you will find a simplified list of steps required to set up your AdminJS panel.
First of all, create your AdonisJS app if you haven't got one yet:
$ npm init adonisjs@latest -- -K=slim
Follow the steps from AdonisJS CLI to configure your application and once it's installed, navigate to the newly created directory.
$ cd <your_app_directory>
AdminJS requires you to install and configure @adonisjs/session
and @adonisjs/lucid
$ npm install @adonisjs/session @adonisjs/lucid
$ node ace configure @adonisjs/session
$ node ace configure @adonisjs/lucid
This will create a configuration file for @adonisjs/session
in config/session.ts
. The default configuration will allow you to sign into your admin panel in your development environment, but before you deploy to production, please see the official documentation.
You should also configure Lucid in config/database.ts
. Without this, you won't be able to start your app.
You will also need to install the core package of AdminJS:
$ npm install adminjs
Finally, install @adminjs/adonis
which will add AdminJS integration into your application.
$ npm install @adminjs/adonis
$ node ace configure @adminjs/adonis
Three new files should appear in your codebase.
- config/adminjs.ts contains the configuration of Lucid adapter, Authentication and AdminJS
- app/admin/component_loader.ts is a file where ComponentLoader is instantiated and exported
- app/admin/auth.ts is a file where default authentication provider is created. Do note that by default, it will let everyone into your admin panel, so make sure you modify the
authenticate
method.
You should be able to start the application with npm run dev
command and you should see the login page of AdminJS if you navigate to the default URL: http://localhost:3333/admin
Authentication can be configured in config/adminjs.ts
under the auth
option.
Default configuration:
import authProvider from '../app/admin/auth.js'
// ...
auth: {
enabled: true,
provider: authProvider,
middlewares: [],
}
The authentication can be disabled or enabled using the enabled
flag.
Provider contains the logic for authenticating the users in your admin panel. The default provider uses email
and password
to authenticate users.
You may also configure any additional middlewares
to routes that require authentication. Every custom middleware is run after the user's session is confirmed to exist.
AdminJS can be configured in config/adminjs.ts
under the adminjs
option. It expects you to provide AdminJSOptions object with the exception of databases
which cannot be configured with @adminjs/adonis
and you will have to configure every resource manually.
Resources configuration will be described in more detail in Lucid section.
adminjs: {
rootPath: '/admin',
loginPath: '/admin/login',
logoutPath: '/admin/logout',
componentLoader,
resources: [],
pages: {},
locale: {
availableLanguages: ['en'],
language: 'en',
translations: {
en: {
actions: {},
messages: {},
labels: {},
buttons: {},
properties: {},
components: {},
pages: {},
ExampleResource: {
actions: {},
messages: {},
labels: {},
buttons: {},
properties: {},
},
},
},
},
branding: {
companyName: 'AdminJS',
theme: {},
},
settings: {
defaultPerPage: 10,
},
}
adminjs
comes with some options already preconfigured. Note that ExampleResource
in translations
is just an example of how you would configure translations scoped to a specific resource. If your application has a Lucid User
model that corresponds to users
table, then ExampleResource
could be renamed to users
.
Middlewares that will be applied to public routes can be configured in config/adminjs.ts
under the middlewares
option.
In order to add Lucid resources into your admin panel, you will first have to enable the adapter in config/adminjs.ts
.
adapter: {
enabled: true
}
After you enable the adapter, you can start adding your Lucid models as resources to adminjs#resources
in config/adminjs.ts
:
import { LucidResource } from '@adminjs/adonis'
import User from '../app/models/user.js'
import Profile from '../app/models/profile.js'
// ...
adminjs: {
resources: [
new LucidResource(User, 'postgres'),
{
resource: new LucidResource(Profile, 'postgres'),
options: {},
}
],
// ...
}
LucidResource is an additional wrapper which uses Knex to fetch schema information about your database table. This is required to properly type and configure AdminJS resources. For every resource that you configure, it will query the database to get columns metadata. This is donly only once when you start your application.
LucidResource takes two arguments in it's constructor. The first is your Lucid model, and the second is your database connection name (this can be checked in config/database.ts
).
There are two approaches to adding resources. You can either simply pass new LucidResource(...)
and use the default configuration for that model, or you can pass a { resource: new LucidResource(...), options: {}
object with your custom Resource configuration in options
.