Installation

Wirechat is a simple yet robust chat package built with the TALL Stack, making it easy to integrate into your Laravel app with just a few commands.

Prerequisites

Before you begin, ensure the following are installed:

• PHP version 8.2 or later
• Laravel version 10 or later
• Livewire version 3.2.3 or later
• Tailwindcss 4.x+

Getting started

1. Install Wirechat

Wirechat can be installed via Composer from your project root:

composer require wirechat/wirechat

2. Install Wirechat Pro (optional)

Wirechat Pro can be activated from the free package:

php artisan wirechat:activate

The command asks for the email address on your license and the license key, then prepares Composer to download the private Pro package.

Get a Wirechat Pro license if you do not have one yet.

Activation creates an auth.json file in your project root. This file stores the Composer credentials used to download Wirechat Pro, so keep it out of version control.

After Pro is installed, update your Wirechat stylesheet import to use the Pro package. See Pro styles.

For each new environment, recreate auth.json or provide the same credentials through your deployment or CI secrets. See Wirechat Pro for cloning an existing project or activating in CI.

Single Project licenses require an activation domain or project ID. This value identifies the app that is using the license. Use the same value for local development, CI, staging, and production for that project:

php artisan wirechat:activate --fingerprint=example.com

The first activation domain used by a Single Project license is registered to that license. A different activation domain counts as another activation and may be rejected when the activation limit is reached.

3. Run Wirechat installer

Run this command to install and publish the necessary files:

php artisan wirechat:install

The following actions will be executed:

• Publish configuration file
• Publish migration files
• Create a default panel with chat search and the new-chat action enabled
• Create a storage symlink

The wirechat:install command also creates a default panel at app/Providers/Wirechat/ChatsPanelProvider.php, so you can move straight into panel configuration after installation.

4. Run Migrations:

Enable UUIDs before running migrations (Optional)

If you want Wirechat to use UUIDs instead of auto-incrementing integers for conversations, update the config before running migrations:

// config/wirechat.php
'uses_uuid_for_conversations' => true,

🔶 Important: This setting should only be configured during initial setup and before running any migrations. Once the tables are created, switching between UUIDs and integers is not supported and may break existing data.

Finally Apply the necessary database migrations with:

php artisan migrate

Setup Tailwind CSS

Wirechat requires Tailwind CSS v4.0 or later.

If Tailwind is already installed in your project, add the free package stylesheet to resources/css/app.css:

/* resources/css/app.css */
@import '../../vendor/wirechat/wirechat/resources/css/app.css';

If you installed Wirechat Pro, use the Pro stylesheet instead:

/* resources/css/app.css */
@import '../../vendor/wirechat/wirechat-pro/resources/css/app.css';

Keep only one Wirechat stylesheet import in your app. The Pro import replaces the free package import.

WebSockets and Queue Setup

Wirechat uses WebSockets to broadcast messages in real-time to conversations and their participants.

Step 1: Enable Broadcasting

In newer Laravel installations, broadcasting is disabled by default. To enable it, run:

php artisan install:broadcasting

Note: This command will prompt you to install Laravel Reverb and necessary front-end packages such as Echo. Accept if you don’t yet have a WebSocket server set up.

Then, start your Reverb server:

php artisan reverb:start

For more details, refer to the Laravel Broadcasting Documentation, including information on integrating Laravel Echo for real-time updates.

Step 2: Start Your Queue Worker

After configuring broadcasting, start a queue worker to handle message broadcasting and other queued tasks:

php artisan queue:listen --queue=messages,default

use Wirechat\Wirechat\Panel;

public function panel(Panel $panel): Panel
{
return $panel
    //...
    ->messagesQueue('messages')
    ->eventsQueue('default');
}

Step 3: Start Your Development Server

To start your development server, run:

composer run dev

If your application does not use Laravel's composer run dev workflow, run your PHP server and frontend build separately instead:

php artisan serve
npm run dev

For more details, see Laravel's Tailwind and Composer Dev Command Documentation.

Publishing Translations

If you need to customize the language files, you can publish them using the following command:

php artisan vendor:publish --tag=wirechat-translations

Publishing Views

To modify Wirechat's Blade views, publish them with this command:

php artisan vendor:publish --tag=wirechat-views