Adonis Cockpit is currently in prerelease version. Documentation, references and examples might not be correct and are subject to change. Give your feedback.

Installation

Important notices

⚠ Pre-release

Adonis Cockpit is in pre-release stage. It might not work as expected and is subject to change. You can track current progress on the dedicated issue.

Feedback is greatly appreciated, feel free to create an issue.

Install `adonis-cockpit`

Adonis Cockpit tries to be an Out of the box Administration panel. It relies on different dependencies that will be installed and configured if they are not already present in your project:

Install and configure Adonis Cockpit using the following command.

node ace add adonis-cockpit

Installs the adonis-cockpit package using the detected package manager.

Registers the following provider inside the adonisrc.ts file.

{
  commands: [
    // ...other commands
    () => import('adonis-cockpit/providers/cockpit_provider')
  ]
}

Registers the following commands inside the adonisrc.ts file.

{
  providers: [
    // ...other providers
    () => import('adonis-cockpit/commands')
  ]
}

Creates the start file start/cockpit.ts and registers it inside the adonisrc file.

{
  preload: [
    // ...other preload
    () => import('#start/cockpit')
  ]
}

Generates the file inertia/app/cockpit.ts that creates the Cockpit inertia app.
Generates the config/cockpit.ts configuration file.
Installs and configure the required peer dependencies.
Installs and configure TailwindCSS

Configure Inertia Root layout

Adonis Cockpit bring its own root layout, to avoid breaking your existing Inertia configuration you have to manually update it to use the Cockpit layout when the path starts with /admin.

config/inertia.ts

const inertiaConfig = defineConfig({
  rootView: ({ request }) => {
    if (request.url().startsWith('/admin')) {
      return 'cockpit::layouts/app'
    }

    return 'inertia_layout'
  },
})

export default inertiaConfig

Disable SSR for Cockpit pages

Cockpit does not support Server Side Rendering. If you are using SSR for a different Inertia app, you will encounter an error. Hopefully, it is possible to disable SSR for all the Cockpit pages:

config/inertia.ts

const inertiaConfig = defineConfig({
  ssr: {
    enabled: true,
    entrypoint: 'inertia/app/ssr.ts',
    pages(ctx, page) {
      if (page.startsWith('cockpit::')) {
        return false
      }
      return true
    },
  },
})

export default inertiaConfig

Configure TailwindCSS

Adonis Cockpit uses TailwindCSS for styling. To give you the ability to customize the styles the CSS is not pre-generated.

tailwind.config.ts

import { Config } from 'tailwindcss'
import cockpit from 'adonis-cockpit/tailwind'

export default {
  presets: [cockpit],
} as Config

TailwindCSS does not allow plugins to extends content and plugins options, if you have a custom TailwindCSS configuration you must manually extend them using the preset:

tailwind.config.ts

import { Config } from 'tailwindcss'
import cockpit from 'adonis-cockpit/tailwind'
import customPlugin from 'custom-plugin'

export default {
  content: ['../custom-content/**/*.vue', ...cockpit.content],
  plugins: [customPlugin, ...cockpit.plugins],
  // Rest of your config...
} as Config

Start your Adonis App

Start your Adonis application using node ace serve command and navigate to the /admin route.

You should already see an empty Administration Panel! It is now time to create your first Resource.