• Versioning Policy
• Upgrading the Free Package
  • Standard Update
  • Re-Publish Assets
  • Re-Publish Configuration (Optional)
  • Clear Caches
  • Rebuild Frontend Assets
  • Complete Upgrade Checklist
• Upgrading the Pro Package
  • Standard Update
  • Re-Publish Pro Assets
  • Complete Pro Upgrade Checklist
  • Authentication Issues
• Upgrading to a New Major Version
  • General Major Upgrade Steps
• Handling Published Views
  • Checking for Outdated Published Views
  • Updating Published Views
• Breaking Changes Policy
  • What Constitutes a Breaking Change
  • What Is NOT a Breaking Change
  • Deprecation Process
• Changelog
  • Viewing the Changelog
  • Changelog Format
• Pinning a Specific Version
• Rollback
• Automated Updates
• Getting Help
• Next Steps

Versioning Policy#

Aura UI follows Semantic Versioning (SemVer):

Within a major version, you can update freely without worrying about breaking changes. Minor releases may add new components, props, or CSS classes, but never remove or rename existing ones.

Upgrading the Free Package#

Standard Update#

To update to the latest version within your current major version constraint:

composer update bluestarsystem/aura-ui

Re-Publish Assets#

After updating, re-publish the CSS assets to pick up any style changes or new component styles:

php artisan vendor:publish --tag=aura-ui-css --force

Note: The --force flag overwrites the published resources/css/vendor/aura-ui/aura.css. If you have customized this file directly, back it up before re-publishing. A better approach is to override styles in your own app.css rather than modifying the published file.

Re-Publish Configuration (Optional)#

If a new version introduces new configuration options, you may want to re-publish the config file:

php artisan vendor:publish --tag=aura-ui-config --force

Compare the new config with your existing one to merge any new options while preserving your customizations.

Clear Caches#

After updating, clear the relevant caches:

php artisan view:clear
php artisan cache:clear
php artisan config:clear

Rebuild Frontend Assets#

Recompile your CSS and JavaScript to pick up any new Tailwind classes from updated component views:

npm run build

Complete Upgrade Checklist#

# 1. Update the package
composer update bluestarsystem/aura-ui

# 2. Re-publish CSS assets
php artisan vendor:publish --tag=aura-ui-css --force

# 3. Clear caches
php artisan view:clear
php artisan cache:clear

# 4. Rebuild frontend
npm run build

# 5. Run your test suite
php artisan test

Upgrading the Pro Package#

The Pro package follows the same upgrade flow, but pulls updates from the private Satis repository.

Standard Update#

composer update bluestarsystem/aura-ui-pro

This also updates the Free package if a new compatible version is available.

Re-Publish Pro Assets#

php artisan vendor:publish --tag=aura-ui-pro-css --force

Complete Pro Upgrade Checklist#

# 1. Update both packages
composer update bluestarsystem/aura-ui bluestarsystem/aura-ui-pro

# 2. Re-publish CSS assets
php artisan vendor:publish --tag=aura-ui-css --force
php artisan vendor:publish --tag=aura-ui-pro-css --force

# 3. Clear caches
php artisan view:clear
php artisan cache:clear

# 4. Rebuild frontend
npm run build

# 5. Run tests
php artisan test

Authentication Issues#

If Composer fails to pull the Pro update, verify your authentication:

# Check if auth.json exists and has valid credentials
cat auth.json

# Or test authentication directly
composer show bluestarsystem/aura-ui-pro --all

If your license key has expired or changed, update it:

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

Or edit auth.json directly:

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

Upgrading to a New Major Version#

Major version upgrades may contain breaking changes. Always read the upgrade guide for the specific major version before proceeding.

General Major Upgrade Steps#

1. Read the changelog for the new major version. Each major release includes a detailed list of breaking changes and migration steps.

2. Update your composer.json constraint:

{
    "require": {
        "bluestarsystem/aura-ui": "^2.0"
    }
}

3. Run the update:

composer update bluestarsystem/aura-ui

4. Follow the migration guide for the specific version. Common changes in major releases include:

   • Renamed components or props
   • Changed default values
   • Removed deprecated features
   • New required dependencies
   • CSS custom property changes

5. Re-publish all assets:

php artisan vendor:publish --tag=aura-ui-config --force
php artisan vendor:publish --tag=aura-ui-css --force

6. Update published views if you have any. Compare your customized views (in resources/views/vendor/aura/) with the new vendor views. The easiest approach is to delete your published views and re-customize from the updated originals.

7. Rebuild and test:

npm run build
php artisan test

Handling Published Views#

If you have published and customized Blade component views, upgrading requires extra care because vendor updates do not touch published views.

Checking for Outdated Published Views#

After upgrading, compare your published views with the new vendor views:

# List your published views
ls resources/views/vendor/aura/components/

# Compare a specific view
diff resources/views/vendor/aura/components/button.blade.php \
     vendor/bluestarsystem/aura-ui/resources/views/components/button.blade.php

Updating Published Views#

For each published view that has changed in the vendor package:

1. Review the diff to understand what changed
2. Apply the vendor changes to your published view, preserving your customizations
3. Or delete the published view to revert to the new vendor version, then re-apply your customizations

# Option A: Delete and re-customize
rm resources/views/vendor/aura/components/button.blade.php
# Then copy and customize again from vendor

# Option B: Manually merge changes
# Edit the published view to incorporate vendor changes

Tip: Keep published views to a minimum. Prefer CSS overrides and Tailwind utility classes for visual customization, and only publish views when you need to change the HTML structure.

Breaking Changes Policy#

Aura UI follows these rules regarding breaking changes:

What Constitutes a Breaking Change#

• Removing a component
• Removing or renaming a component prop
• Changing the default value of a prop in a way that alters existing behavior
• Removing a CSS custom property
• Changing the HTML structure of a component in a way that breaks existing CSS overrides
• Dropping support for a PHP, Laravel, or Tailwind CSS version

What Is NOT a Breaking Change#

• Adding new components
• Adding new optional props with sensible defaults
• Adding new CSS custom properties
• Adding new CSS classes to component markup
• Bug fixes that correct behavior to match documentation
• Performance improvements
• Internal refactoring that does not affect the public API

Deprecation Process#

Features scheduled for removal in the next major version are deprecated first:

1. The feature is marked as deprecated in a minor release
2. A deprecation notice is logged or documented
3. The deprecated feature continues to work for the remainder of the current major version
4. The feature is removed in the next major version

Changelog#

Each release includes a detailed changelog documenting all changes. Check the changelog before upgrading to understand what is new, changed, or fixed.

Viewing the Changelog#

The changelog is available in the package repository:

# View the changelog
cat vendor/bluestarsystem/aura-ui/CHANGELOG.md

Changelog Format#

The changelog follows the Keep a Changelog format:

## [2.0.1] - 2026-02-15

### Added
- New `StatsCard` component for dashboard metrics
- `loading` prop on Button component for loading states

### Changed
- Improved dark mode contrast on Input component borders

### Fixed
- Modal closing animation stuttering on Safari
- Tooltip positioning when near viewport edge

Pinning a Specific Version#

If you need to stay on a specific version (e.g., to avoid an issue in a newer release):

{
    "require": {
        "bluestarsystem/aura-ui": "2.0.0"
    }
}

Or pin to a specific minor version:

{
    "require": {
        "bluestarsystem/aura-ui": "~2.0.0"
    }
}

Rollback#

If an upgrade causes issues, you can roll back to the previous version:

# Check what version you had before
git diff composer.lock | grep aura-ui

# Restore the previous composer.lock
git checkout composer.lock

# Re-install the previous versions
composer install

# Re-publish the previous assets
php artisan vendor:publish --tag=aura-ui-css --force

# Rebuild frontend
npm run build

If you did not commit your composer.lock before upgrading, you can manually require the previous version:

composer require bluestarsystem/aura-ui:2.0.0
php artisan vendor:publish --tag=aura-ui-css --force
npm run build

Automated Updates#

For projects that want to stay on the latest version automatically, consider adding the update check to your CI/CD pipeline:

# In your CI pipeline
composer outdated bluestarsystem/aura-ui bluestarsystem/aura-ui-pro

This shows available updates without installing them, letting you decide when to upgrade.

Getting Help#

If you encounter issues during an upgrade:

1. Check the changelog for known issues
2. Clear all caches and rebuild assets
3. Verify your published views are compatible with the new version
4. Open an issue on the package repository with your Laravel version, PHP version, and the specific error

Next Steps#

• Getting Started -- Overview of Aura UI
• Installation -- Fresh installation instructions
• Configuration -- Configuration options