• Requirements
• Installing the Free Package
  • Step 1: Require via Composer
  • Step 2: Run the Installer
  • Step 3: Import the CSS
  • Step 4: Verify Installation
• Installing the Pro Package
  • Step 1: Add the Satis Repository
  • Step 2: Configure Authentication
  • Step 3: Require the Pro Package
  • Step 4: Run the Pro Installer
  • Step 5: Import the Pro CSS
  • Step 6: Verify Pro Installation
• CSS Setup
  • Complete app.css Example
  • Font Setup
• Vite Configuration
  • Refresh Paths
• Alpine.js Setup
  • Option A: Via NPM (Recommended)
  • Option B: Via CDN
  • Livewire Integration
• Troubleshooting
  • Components render without styles
  • "Component not found" error
  • Pro package authentication fails
  • Dark mode classes are not generated
  • Styles appear but look wrong
• Next Steps

Requirements#

Before installing Aura UI, make sure your environment meets the following requirements:

Installing the Free Package#

Step 1: Require via Composer#

composer require bluestarsystem/aura-ui

The package auto-discovers its service provider. No manual registration is needed.

Step 2: Run the Installer#

php artisan aura:install

This command publishes config/aura-ui.php, the configuration file you are meant to edit, along with a copy of the stylesheet and the playground's JavaScript assets.

Step 3: Import the CSS#

Open your resources/css/app.css and add two lines after Tailwind — one telling Tailwind where to scan for class names, one pulling in the stylesheet:

@import 'tailwindcss';
@source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php';
@import '../../vendor/bluestarsystem/aura-ui/resources/css/aura.css';

The @source line is what makes Tailwind generate the utility classes used inside Aura's own components; without it they render unstyled.

Both lines point at vendor, which is the point: the stylesheet stays in step with the package on every composer update, with nothing to re-publish and nothing that can quietly fall behind.

Upgrading from an older setup? Earlier versions of this page told you to import ./vendor/aura-ui/aura.css — the copy under resources/css. That still works, but the copy is only refreshed when you re-run php artisan aura:install. If you upgraded the package and a new component looks unstyled, that copy is why: either re-run the installer or switch the import to the vendor path above.

Step 4: Verify Installation#

Create a test Blade view to confirm everything works:

{{-- resources/views/test.blade.php --}}
<x-aura::button variant="primary">
    Aura UI is working!
</x-aura::button>

<x-aura::alert variant="info" class="mt-4">
    Installation successful.
</x-aura::alert>

Run npm run dev (or npm run build) and visit the page. If you see a styled button and alert, the Free package is installed correctly.

Installing the Pro Package#

The Pro package is distributed through a private Satis repository at packages.elju.it. You need a valid license and authentication token to install it.

Step 1: Add the Satis Repository#

Add the Aura UI Pro repository to your project's composer.json:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.elju.it"
        }
    ]
}

Or via the command line:

composer config repositories.aura-ui-pro composer https://packages.elju.it

Step 2: Configure Authentication#

Authenticate with your Aura UI license key using Composer's Bearer token authentication:

composer config bearer.packages.elju.it AURA-XXXX-XXXX-XXXX-XXXX

Replace AURA-XXXX-XXXX-XXXX-XXXX with the license key from your Aura UI account dashboard.

This creates an auth.json file in your project root:

{
    "bearer": {
        "packages.elju.it": "AURA-XXXX-XXXX-XXXX-XXXX"
    }
}

Important: Add auth.json to your .gitignore file to avoid committing credentials to version control.

echo "auth.json" >> .gitignore

Step 3: Require the Pro Package#

composer require bluestarsystem/aura-ui-pro

This will also install the Free package as a dependency if it's not already present.

Step 4: Run the Pro Installer#

php artisan aura-pro:install

This publishes:

• a copy of the Pro stylesheet under resources/css/vendor/aura-ui-pro/, which the import below deliberately does not use

Step 5: Import the Pro CSS#

Update your resources/css/app.css to include both Free and Pro styles:

@import 'tailwindcss';

@source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php';
@source '../../vendor/bluestarsystem/aura-ui-pro/resources/views/**/*.blade.php';

@import './vendor/aura-ui/aura.css';
@import '../../vendor/bluestarsystem/aura-ui-pro/resources/css/aura-pro.css';

The order matters: Tailwind first, then @source directives, then Aura UI Free, then Aura UI Pro.

Step 6: Verify Pro Installation#

Test a component that only the Pro package ships:

{{-- resources/views/test-pro.blade.php --}}
<x-aura::date-range-picker label="Period" wire:model="range" />

<x-aura::color-picker
    label="Brand Color"
    name="brand_color"
    class="mt-4"
/>

If both render, Pro is installed. Pick the component for this check from the Pro Components section of the sidebar: a free component renders whether or not Pro is present, so testing with one proves nothing.

CSS Setup#

Complete app.css Example#

Here is a complete resources/css/app.css for a project using both Free and Pro:

/* Tailwind CSS 4 */
@import 'tailwindcss';

/* Source detection for Tailwind class scanning */
@source '../../vendor/bluestarsystem/aura-ui/resources/views/**/*.blade.php';
@source '../../vendor/bluestarsystem/aura-ui-pro/resources/views/**/*.blade.php';

/* Aura UI component styles */
@import './vendor/aura-ui/aura.css';
@import '../../vendor/bluestarsystem/aura-ui-pro/resources/css/aura-pro.css';

/* Your custom styles and @theme overrides go here */

The aura.css entry point already defines @custom-variant dark, @theme design tokens, and imports all internal CSS files (dark mode overrides, keyframe animations, glass morphism utilities, and residual component styles). See the Theming guide for the full CSS architecture breakdown.

Font Setup#

Aura UI's Vibrant Depth design uses two font families. Include them in your layout:

{{-- resources/views/layouts/app.blade.php --}}
<head>
    <link rel="preconnect" href="https://fonts.bunny.net">
    <link href="https://fonts.bunny.net/css?family=inter:400,500,600,700|jetbrains-mono:400,500" rel="stylesheet" />
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

Vite Configuration#

Refresh Paths#

To enable hot-reloading for Aura UI components during development, add the vendor view paths to your Vite configuration:

// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/js/app.js',
            ],
            refresh: [
                'resources/views/**',
                'vendor/bluestarsystem/aura-ui/resources/views/**',
                'vendor/bluestarsystem/aura-ui-pro/resources/views/**',
            ],
        }),
    ],
});

This ensures that changes to published or vendor component views trigger a page refresh during development.

Alpine.js Setup#

Aura UI uses Alpine.js for client-side interactivity (dropdowns, modals, tooltips, dark mode toggling, etc.). Make sure Alpine.js is loaded in your application.

Option A: Via NPM (Recommended)#

npm install alpinejs

// resources/js/app.js
import Alpine from 'alpinejs';

window.Alpine = Alpine;
Alpine.start();

Option B: Via CDN#

{{-- In your layout <head> --}}
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Tip: If you use Livewire 3, Alpine.js is already bundled and injected automatically. You do not need to install it separately. However, if you need to register custom Alpine data or plugins, import Alpine via NPM and disable Livewire's auto-injection by setting 'inject_assets' => false in config/livewire.php.

Livewire Integration#

If you are using Livewire 3, Aura UI form components work with wire:model natively:

<x-aura::input
    label="Full Name"
    wire:model="name"
    placeholder="John Doe"
/>

<x-aura::select label="Country" wire:model="country">
    <x-aura::select.option value="it">Italy</x-aura::select.option>
    <x-aura::select.option value="us">United States</x-aura::select.option>
    <x-aura::select.option value="de">Germany</x-aura::select.option>
</x-aura::select>

<x-aura::toggle
    label="Receive notifications"
    wire:model.live="notifications"
/>

Troubleshooting#

Components render without styles#

Make sure you have:

1. Imported aura.css (and aura-pro.css for Pro) in your resources/css/app.css
2. Added the @source directives pointing to the vendor Blade views
3. Run npm run build or npm run dev to recompile assets

"Component not found" error#

Verify the package is installed:

composer show bluestarsystem/aura-ui

Check that the service provider is auto-discovered:

php artisan vendor:publish --list | grep aura

If auto-discovery is disabled, manually register the provider in bootstrap/providers.php:

return [
    // ...
    BlueStarSystem\AuraUI\AuraUIServiceProvider::class,
    BlueStarSystem\AuraUIPro\AuraUIProServiceProvider::class, // if Pro is installed
];

Pro package authentication fails#

Double-check your license key. You can also configure authentication globally:

composer config --global bearer.packages.elju.it AURA-XXXX-XXXX-XXXX-XXXX

Make sure your license is active in your Aura UI dashboard.

Dark mode classes are not generated#

Aura UI's aura.css includes @custom-variant dark (&:is(.dark *)); which overrides Tailwind 4's default dark mode to use the .dark class strategy. Make sure the @source directives include the Aura UI view paths so Tailwind can scan those files and detect dark: variant usage.

Styles appear but look wrong#

Clear the Vite cache and rebuild:

rm -rf node_modules/.vite
npm run build

Also clear the Laravel view cache:

php artisan view:clear
php artisan cache:clear

Next Steps#

• Configuration -- Customize component prefix, icons, and behavior
• Theming -- Adapt Aura UI's design to match your brand
• Dark Mode -- Set up theme switching