Adding to an existing project

This page walks you through adding Acun UI to an existing Laravel project without the theme.

If you're starting a new project with the theme, you don't need this page; Quick start is all you need.

What you need

Laravel 12 or 13; Livewire 4; Vite; Tailwind CSS 4
PHP 8.2 or later; Node.js 20.19+ or 22.12+ for building
For the fonts: Laravel 13 and laravel-vite-plugin 3.1 or later
The theme's zip: everything you need is in its starter-kit folder

Step by step

Copy the packages. Copy the zip's starter-kit/packages/acun-ui folder to the root of your project, at the same path. From the project root:
```
mkdir -p packages
cp -R /where-you-unzipped/acun-admin-1.1.0/starter-kit/packages/acun-ui packages/
```
Register the packages with Composer. Copy two things from the starter kit's composer.json into your own composer.json: the repositories block and the acunsoft/* lines under require. The repositories block looks like this:
```
"repositories": [
    { "type": "path", "url": "packages/acun-ui/acun-ui-core" },
    { "type": "path", "url": "packages/acun-ui/acun-ui-free" },
    { "type": "path", "url": "packages/acun-ui/acun-ui-pro" }
]
```
Install the PHP packages:
```
composer update "acunsoft/*"
```
Composer links the packages under vendor/acunsoft/ and discovers their service providers automatically. The acun:* components are ready to use right away.
Add the build dependencies. Add these lines to your package.json, then run npm install:
```
"dependencies": {
    "@acunsoft/acun-ui-core": "file:packages/acun-ui/acun-ui-core",
    "apexcharts": "^3.54.1",
    "flatpickr": "^4.6.13",
    "leaflet": "^1.9.4"
},
"devDependencies": {
    "@tailwindcss/forms": "^0.5.11"
}
```
@acunsoft/acun-ui-core comes from the folder you copied, not from npm. ApexCharts, flatpickr and Leaflet are only needed for the chart, date range and map components.

Wire up the CSS. In resources/css/app.css, import Acun UI after Tailwind and add the packages' views to Tailwind's sources:

@import 'tailwindcss';
@plugin '@tailwindcss/forms';
@import '@acunsoft/acun-ui-core';
@import '../../vendor/acunsoft/acun-ui-pro/resources/css/acun-ui-pro.css';

@source '../../vendor/acunsoft/acun-ui-free/resources/views';
@source '../../vendor/acunsoft/acun-ui-pro/resources/views';

Without the @source lines, the components' Tailwind classes don't make it into the build and the components appear unstyled. Keep your own @source lines in the file.

Create the Acun UI JavaScript entry. A new resources/js/acun-ui.js file:
```
import '@acunsoft/acun-ui-core';
import '@acunsoft/acun-ui-pro';
```
app.js stays for your own code and doesn't import Acun UI. Alpine ships with Livewire, so you don't need to install it separately.

Configure Vite. Make your vite.config.js look like this:

import path from 'node:path';
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { bunny } from 'laravel-vite-plugin/fonts';
import tailwindcss from '@tailwindcss/vite';
import { woff2Only } from '@acunsoft/acun-ui-core/vite';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/acun-ui.js', 'resources/js/app.js'],
            refresh: true,
            fonts: [
                bunny('Public Sans', { weights: [400, 500, 600, 700], subsets: ['latin', 'latin-ext'], preload: [{ weight: 400 }, { weight: 600 }] }),
                bunny('DM Mono', { weights: [400, 500], subsets: ['latin', 'latin-ext'], preload: false }),
            ],
        }),
        woff2Only(),
        tailwindcss(),
    ],
    resolve: {
        // The PRO JavaScript ships in the Composer package, not on npm.
        alias: { '@acunsoft/acun-ui-pro': path.resolve(import.meta.dirname, 'vendor/acunsoft/acun-ui-pro/resources/js/index.js') },
    },
});

input lists the three files loaded on every page. fonts loads the theme's fonts: Public Sans for text, DM Mono for code and numbers. The latin-ext subset contains the Turkish letters (ş, ğ, İ, ı). Details: Fonts.

Create the layout. resources/views/layouts/admin/vertical.blade.php:

@php
    // Tab title: the Blade page's @section('title') or the Livewire page's #[Title].
    $pageTitle = new \Illuminate\Support\HtmlString(View::yieldContent('title', __($title ?? 'Dashboard')));
@endphp

<acun:layout.sidebar customizer brand-name="My App" :home-url="route('dashboard')" :title="$pageTitle">
    <acun:slot:head>
        @acunFonts(['public-sans', 'dm-mono'])
        @vite(['resources/css/app.css', 'resources/js/acun-ui.js', 'resources/js/app.js'])
    </acun:slot:head>

    <acun:slot:nav><acun:menu menu="main" /></acun:slot:nav>

    @hasSection('content')
        @yield('content')
    @else
        {{ $slot ?? '' }}
    @endif
</acun:layout.sidebar>

@acunFonts prints the font tags and @vite prints the CSS and JavaScript. The last block makes the layout work for both Blade and Livewire pages. The first letter of the app name appears at the top of the menu. For your own logo, add <acun:slot:logo><img src="/logo.svg" alt="My App" class="h-8"></acun:slot:logo> to the layout.

Write the menu. resources/menu/main.json:

{
    "menu": [
        { "section": "General" },
        { "title": "Dashboard", "icon": "home", "route": "dashboard" }
    ]
}

Write the first page. resources/views/admin/dashboard.blade.php:

@extends('layouts.admin.vertical')

@section('title', __('Dashboard'))

@section('content')
    <acun:page-header :title="__('Dashboard')" />
    <acun:card title="Welcome">Acun UI is installed.</acun:card>
@endsection

Add the route. routes/web.php:

Route::view('/panel', 'admin.dashboard')->name('dashboard');

Build and open it:
```
npm run build
```
While developing, run npm run dev instead of npm run build. Then open /panel in your browser.

Livewire pages

A Livewire full-page component uses the same layout through attributes:

use Livewire\Attributes\Layout;
use Livewire\Attributes\Title;
use Livewire\Component;

#[Layout('layouts.admin.vertical')]
#[Title('Dashboard')]
final class Dashboard extends Component
{
    // …
}

The layout translates the #[Title] value and uses it as the tab title. See Your first page for more on writing pages.

Charts, maps and date ranges

These components use external libraries, which you register with Acun UI in resources/js/app.js. Copy the ready-made code from the Charts, maps and date ranges section.

Component tags

The examples in these docs use the short syntax: <acun:button>. The same component can also be called with Blade's own component syntax. Both accept the same props and slots and produce the same HTML:

<acun:button variant="danger">Delete</acun:button>
<x-ui.button variant="danger">Delete</x-ui.button>

<acun:card title="Summary">
    <acun:slot:actions><acun:badge>3</acun:badge></acun:slot>
    Body
</acun:card>

Named slots are written as <acun:slot:name> or <acun:slot name="name">.
Dotted names such as <acun:accordion.heading> and PRO components work the same way.
Editor extensions (autocomplete, go to definition) recognize only Blade's own syntax. If you need that support, use the <x-ui.*> syntax.
The short syntax is only for Acun UI components. Your application's own components are still called with <x-…>.

Optional publishing

You can copy the packages' config file and views into your application and change them:

php artisan vendor:publish --tag=acun-ui-config      # config/acun-ui.php (layout and DataTable defaults)
php artisan vendor:publish --tag=acun-ui-views       # resources/views/vendor/acun-ui (e.g. the pagination view)
php artisan vendor:publish --tag=acun-ui-pro-views   # resources/views/vendor/acun-ui-pro (e.g. DataTable partials)

To change a component's view permanently, copy its file from the package into your application's resources/views/components/ui/ folder under the same name. Laravel uses the application's copy first. Copied files don't receive package updates. In most cases, the settings on the Customization page are all you need.

Learn more

CSS, JavaScript and build: JavaScript layers, page-specific code, loading without Vite, troubleshooting.
Configuration: the config/acun-ui.php settings.
Layouts: the other layouts for a horizontal menu, sign-in and error pages.
Menu: every field of the JSON menu.