• Requirements
• Installing the Free Package
  • Step 1: Require via Composer
  • Step 2: Run the Installer
  • Step 3: Import the CSS
  • Step 4: Configure Tailwind Source Detection
  • Step 5: 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
• resources/css/vendor/aura-ui/aura.css -- the component stylesheet

Step 3: Import the CSS#

Open your resources/css/app.css and add the Aura UI import after Tailwind:

@import 'tailwindcss';
@import './vendor/aura-ui/aura.css';

Step 4: Configure Tailwind Source Detection#

Tailwind CSS 4 needs to know where to scan for class names. Add a @source directive in your resources/css/app.css to include the Aura UI vendor views:

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

This ensures Tailwind generates CSS for all utility classes used inside Aura UI components.

Step 5: 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:

• resources/css/vendor/aura-ui-pro/aura-pro.css -- the Pro component stylesheet

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/aura-ui-pro/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 Pro-exclusive component:

{{-- resources/views/test-pro.blade.php --}}
<x-aura::tabs>
    <x-aura::tabs.tab name="overview" label="Overview" active>
        <p>Tab content goes here.</p>
    </x-aura::tabs.tab>
    <x-aura::tabs.tab name="settings" label="Settings">
        <p>Settings content.</p>
    </x-aura::tabs.tab>
</x-aura::tabs>

<x-aura::date-picker
    label="Select a date"
    wire:model="selectedDate"
/>

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/aura-ui-pro/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