Installation

This guide covers installing Arqel in a fresh or existing Laravel app. For the end-to-end walkthrough (including your first Resource and UI), continue to Getting Started.

Prerequisites

	Minimum version
PHP	8.3
Composer	2.x
Laravel	12
Node	20.9 LTS
pnpm (recommended)	10+

npm and yarn also work — arqel:install automatically detects the package manager from the lockfile.

Step 1 — Create a Laravel 12 app

If you don't have an app yet:

composer create-project laravel/laravel:^12.0 my-admin-app
cd my-admin-app

If you already have a Laravel 12 app running, skip this step.

Step 2 — Install the meta-package

composer require arqel-dev/framework

The arqel-dev/framework meta-package pulls the entire Arqel stack + inertiajs/inertia-laravel:

• arqel-dev/core — panels, resources, polymorphic routes, Inertia bridge, command palette, telemetry
• arqel-dev/auth — login / register / forgot / reset / verify-email bundled
• arqel-dev/fields — schema types
• arqel-dev/form — server-side render
• arqel-dev/actions — contracts + invokers
• arqel-dev/nav — navigation builder
• arqel-dev/table — query / sort / filter / paginate
• inertiajs/inertia-laravel — required peer

Step 3 — Run the installer

php artisan arqel:install

When prompted for the JS package manager, choose pnpm, npm, or yarn. The installer:

1. Publishes config/arqel.php
2. Generates app/Providers/ArqelServiceProvider.php with the admin panel configured (login + registration + UserResource)
3. Auto-registers the provider in bootstrap/providers.php (idempotent)
4. Generates app/Arqel/Resources/UserResource.php (User CRUD as an example)
5. Publishes app/Http/Middleware/HandleInertiaRequests.php with rootView = 'arqel.layout'
6. Auto-registers the middleware in the web pipeline via ArqelServiceProvider::boot() (without editing bootstrap/app.php)
7. Generates resources/views/arqel/layout.blade.php (Blade root with no Ziggy @routes dependency)
8. Generates resources/js/app.tsx (createArqelApp + AppShell + auth pages)
9. Generates resources/css/app.css (shadcn tokens via @import '@arqel-dev/ui/styles.css' + @source for the framework packages)
10. Publishes vite.config.ts (replaces the default vite.config.js — React + Tailwind v4)
11. Publishes public/login-hero.svg (split-screen auth illustration)
12. Generates AGENTS.md (instructions for Claude Code / Cursor / other LLMs)
13. Installs the JS packages via pnpm/npm/yarn: @arqel-dev/{react,ui,auth,hooks,fields,types} + peers (React, Inertia, Tailwind, Vite, plugins)

Step 4 — Database setup + first admin

php artisan migrate
php artisan arqel:make-user

arqel:make-user interactively prompts for name, email, and password. For non-interactive use (e.g. CI):

php artisan arqel:make-user --name="Ada" --email="ada@example.com" --password="secret"

Step 5 — Start the dev servers

In two terminals:

# Terminal 1 — backend
php artisan serve

# Terminal 2 — Vite dev (HMR)
pnpm dev   # or: npm run dev / yarn dev

Open http://localhost:8000/admin/login and log in with the credentials from step 4.

Final structure

After install, your app looks like this:

my-admin-app/
├── app/
│   ├── Arqel/
│   │   └── Resources/
│   │       └── UserResource.php       # generated by install
│   ├── Http/
│   │   └── Middleware/
│   │       └── HandleInertiaRequests.php   # generated, rootView=arqel.layout
│   └── Providers/
│       └── ArqelServiceProvider.php   # generated, registers the admin panel
├── bootstrap/
│   └── providers.php                  # ArqelServiceProvider auto-registered
├── config/
│   └── arqel.php                      # published config
├── public/
│   └── login-hero.svg                 # split-screen illustration
├── resources/
│   ├── css/app.css                    # @import shadcn + @source workspace
│   ├── js/app.tsx                     # createArqelApp + auth + arqelPages
│   └── views/arqel/layout.blade.php   # Blade Inertia root
└── vite.config.ts                     # React + Tailwind + watch ignored

Common customizations

Change the brand

bootstrap/providers.php loads App\Providers\ArqelServiceProvider. Edit app/Providers/ArqelServiceProvider.php to change the brand, panel path, or login redirect:

$panel = $registry
    ->panel('admin')
    ->path('admin')                           // change to 'painel' if you prefer
    ->brand('Acme Admin')                     // text/logo at the top of the Sidebar
    ->login()
    ->afterLoginRedirectTo('/admin/users')    // landing page after login
    ->registration()
    ->resources([
        UserResource::class,
        // add more Resources here
    ]);

Add more Resources

php artisan make:model Post -m
php artisan arqel:resource Post   # generates app/Arqel/Resources/PostResource.php

Then add it to the resources([...]) list in the provider.

Change the theme (light/dark/system)

The ThemeProvider (from @arqel-dev/react) reads localStorage.arqel-theme. The switcher is already in the Topbar. To customize tokens, edit the CSS vars --primary, --background, etc. — see Theming.

Troubleshooting

Vite manifest not found

The Vite dev server is not running. In local dev: pnpm dev. In production: pnpm build.

View [app] not found

Inertia is looking for the old root view. Make sure app/Http/Middleware/HandleInertiaRequests.php has protected $rootView = 'arqel.layout'; and that the middleware is in the web pipeline (verify with php artisan route:list --path=admin/login showing web middleware).

Empty sidebar after login

Make sure you have at least one Resource registered in resources([...]) in ArqelServiceProvider. The panel.navigation is built automatically from the panel's Resources.

Login returns 404 after submission

Make sure the panel has ->afterLoginRedirectTo('/admin/<resource-slug>') pointing to a route that exists. By default the stub points to /admin/users (which exists via UserResource).

Next steps

• Getting Started — full walkthrough of your first CRUD
• Panels — configure paths, branding, middleware, multi-panel
• Resources — declare fields, columns, filters, actions
• Authentication — login/register options and custom flows
• Theming — shadcn tokens, dark mode, visual customization