|
| 1 | +--- |
| 2 | +description: '@adminjs/adonis' |
| 3 | +--- |
| 4 | + |
| 5 | +# Adonis |
| 6 | + |
| 7 | +`@adminjs/adonis` is an official integration with [AdonisJS](https://adonisjs.com/) and it's Lucid ORM. It supports AdonisJS v6+ and requires NodeJS v20.6.x+. |
| 8 | + |
| 9 | +{% hint style="warning" %} |
| 10 | +`@adminjs/adonis` currently only supports Lucid as it's ORM. We will soon add support for other database adapters. |
| 11 | +{% endhint %} |
| 12 | + |
| 13 | +The easiest way to get started with AdonisJS integration is to follow their [official documentation](https://docs.adonisjs.com/guides/installation).  |
| 14 | + |
| 15 | +Below you will find a simplified list of steps required to set up your AdminJS panel. |
| 16 | + |
| 17 | +First of all, create your AdonisJS app if you haven't got one yet: |
| 18 | + |
| 19 | +```bash |
| 20 | +$ npm init adonisjs@latest -- -K=slim |
| 21 | +``` |
| 22 | + |
| 23 | +Follow the steps from AdonisJS CLI to configure your application and once it's installed, navigate to the newly created directory. |
| 24 | + |
| 25 | +```bash |
| 26 | +$ cd <your_app_directory> |
| 27 | +``` |
| 28 | + |
| 29 | +AdminJS requires you to install and configure `@adonisjs/session` and `@adonisjs/lucid` |
| 30 | + |
| 31 | +```bash |
| 32 | +$ npm install @adonisjs/session @adonisjs/lucid |
| 33 | +$ node ace configure @adonisjs/session |
| 34 | +$ node ace configure @adonisjs/lucid |
| 35 | +``` |
| 36 | + |
| 37 | +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](https://docs.adonisjs.com/guides/session#session). |
| 38 | + |
| 39 | +You should also configure Lucid in `config/database.ts`. Without this, you won't be able to start your app. |
| 40 | + |
| 41 | +You will also need to install the core package of AdminJS: |
| 42 | + |
| 43 | +```bash |
| 44 | +$ npm install adminjs |
| 45 | +``` |
| 46 | + |
| 47 | +Finally, install `@adminjs/adonis` which will add AdminJS integration into your application. |
| 48 | + |
| 49 | +```bash |
| 50 | +$ npm install @adminjs/adonis |
| 51 | +$ node ace configure @adminjs/adonis |
| 52 | +``` |
| 53 | + |
| 54 | +Three new files should appear in your codebase. |
| 55 | + |
| 56 | +* **config/adminjs.ts** contains the configuration of Lucid adapter, Authentication and AdminJS |
| 57 | +* **app/admin/component\_loader.ts** is a file where [ComponentLoader](../../ui-customization/writing-your-own-components.md) is instantiated and exported |
| 58 | +* **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. |
| 59 | + |
| 60 | +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](http://localhost:3333/admin/login) |
| 61 | + |
| 62 | +### Authentication |
| 63 | + |
| 64 | +Authentication can be configured in `config/adminjs.ts` under the `auth` option. |
| 65 | + |
| 66 | +Default configuration: |
| 67 | + |
| 68 | +```typescript |
| 69 | +import authProvider from '../app/admin/auth.js' |
| 70 | + |
| 71 | +// ... |
| 72 | +auth: { |
| 73 | + enabled: true, |
| 74 | + provider: authProvider, |
| 75 | + middlewares: [], |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +The authentication can be disabled or enabled using the `enabled` flag. |
| 80 | + |
| 81 | +[Provider](../../basics/authentication/) contains the logic for authenticating the users in your admin panel. The default provider uses `email` and `password` to authenticate users. |
| 82 | + |
| 83 | +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. |
| 84 | + |
| 85 | +### AdminJS Configuration |
| 86 | + |
| 87 | +AdminJS can be configured in `config/adminjs.ts` under the `adminjs` option. It expects you to provide [AdminJSOptions](https://github.com/SoftwareBrothers/adminjs/blob/master/src/adminjs-options.interface.ts) object with the exception of `databases` which cannot be configured with `@adminjs/adonis` and you will have to configure every resource manually. |
| 88 | + |
| 89 | +Resources configuration will be described in more detail in [Lucid ](adonis.md#lucid)section. |
| 90 | + |
| 91 | +```typescript |
| 92 | +adminjs: { |
| 93 | + rootPath: '/admin', |
| 94 | + loginPath: '/admin/login', |
| 95 | + logoutPath: '/admin/logout', |
| 96 | + componentLoader, |
| 97 | + resources: [], |
| 98 | + pages: {}, |
| 99 | + locale: { |
| 100 | + availableLanguages: ['en'], |
| 101 | + language: 'en', |
| 102 | + translations: { |
| 103 | + en: { |
| 104 | + actions: {}, |
| 105 | + messages: {}, |
| 106 | + labels: {}, |
| 107 | + buttons: {}, |
| 108 | + properties: {}, |
| 109 | + components: {}, |
| 110 | + pages: {}, |
| 111 | + ExampleResource: { |
| 112 | + actions: {}, |
| 113 | + messages: {}, |
| 114 | + labels: {}, |
| 115 | + buttons: {}, |
| 116 | + properties: {}, |
| 117 | + }, |
| 118 | + }, |
| 119 | + }, |
| 120 | + }, |
| 121 | + branding: { |
| 122 | + companyName: 'AdminJS', |
| 123 | + theme: {}, |
| 124 | + }, |
| 125 | + settings: { |
| 126 | + defaultPerPage: 10, |
| 127 | + }, |
| 128 | +} |
| 129 | +``` |
| 130 | + |
| 131 | +`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`. |
| 132 | + |
| 133 | +### Middlewares |
| 134 | + |
| 135 | +Middlewares that will be applied to public routes can be configured in `config/adminjs.ts` under the `middlewares` option. |
| 136 | + |
| 137 | +### Lucid |
| 138 | + |
| 139 | +In order to add Lucid resources into your admin panel, you will first have to enable the adapter in `config/adminjs.ts`. |
| 140 | + |
| 141 | +```typescript |
| 142 | +adapter: { |
| 143 | + enabled: true |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +After you enable the adapter, you can start adding your Lucid models as resources to `adminjs#resources` in `config/adminjs.ts`: |
| 148 | + |
| 149 | +```typescript |
| 150 | +import { LucidResource } from '@adminjs/adonis' |
| 151 | + |
| 152 | +import User from '../app/models/user.js' |
| 153 | +import Profile from '../app/models/profile.js' |
| 154 | + |
| 155 | +// ... |
| 156 | +adminjs: { |
| 157 | + resources: [ |
| 158 | + new LucidResource(User, 'postgres'), |
| 159 | + { |
| 160 | + resource: new LucidResource(Profile, 'postgres'), |
| 161 | + options: {}, |
| 162 | + } |
| 163 | + ], |
| 164 | + // ... |
| 165 | +} |
| 166 | +``` |
| 167 | + |
| 168 | +**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. |
| 169 | + |
| 170 | +**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`). |
| 171 | + |
| 172 | +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](https://github.com/SoftwareBrothers/adminjs/blob/master/src/backend/decorators/resource/resource-options.interface.ts#L48) in `options`. |
0 commit comments