Installation

Requirements

Before installing Laravel Hyper, ensure your system meets these requirements:

PHP 8.2 or higher
Laravel 11.0 or higher
A fresh or existing Laravel application

Hyper integrates seamlessly with both new and existing Laravel projects. If you're starting fresh, follow the Laravel installation guide to create a new application first.

Installing Hyper

Install Laravel Hyper via Composer:

bash

composer require dancycodes/hyper

Laravel's package auto-discovery will automatically register Hyper's service provider. You don't need to manually add anything to your config/app.php file.

Publishing Assets

Hyper includes JavaScript files that power the reactive frontend. Publish these assets to your application's public directory:

bash

php artisan vendor:publish --tag=hyper-assets

This command copies Hyper's JavaScript files to public/vendor/hyper/js/. These files include:

Datastar Core: The reactive framework that powers signals and reactivity
Hyper Extensions: Laravel-specific enhancements like CSRF token handling and validation integration

The published files are production-ready and minified. You don't need to build or compile anything, they work immediately.

Including Hyper in Your Views

To use Hyper in your Blade templates, add the @hyper directive in your layout's <head> section:

blade

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Application</title>

    @hyper
</head>
<body>
    @yield('content')
</body>
</html>

The @hyper directive generates two things:

CSRF Token Meta Tag: <meta name="csrf-token" content="your-token">
Script Include: <script type="module" src="/vendor/hyper/js/hyper.js"></script>

That's all you need. Hyper is now available on every page that includes this directive.

Module Script

The script tag uses type="module", which means it's loaded as an ES module. All modern browsers support this. The script is loaded asynchronously and won't block your page rendering.

Configuration (Optional)

Hyper works out of the box with sensible defaults. However, if you want to customize its behavior, publish the configuration file:

bash

php artisan vendor:publish --tag=hyper-config

This creates config/hyper.php with the following options:

Signal Key

php

'signal_key' => env('HYPER_SIGNAL_KEY', 'datastar'),

This controls the key name Hyper looks for when reading signals from requests. The default is 'datastar' for compatibility with the Datastar ecosystem. You typically don't need to change this.

Debug Mode

php

'debug' => env('HYPER_DEBUG', env('APP_DEBUG', false)),

When enabled, Hyper provides additional debugging information in responses. This automatically follows your APP_DEBUG setting unless explicitly overridden.

Route Discovery

php

'route_discovery' => [
    'enabled' => false,

    'discover_controllers_in_directory' => [
        // app_path('Http/Controllers'),
    ],

    // ... additional options
],

Route discovery is an optional feature that automatically generates routes from controller methods using PHP attributes. It's disabled by default. Learn more in the Route Discovery section.

When to Publish Config

Most applications don't need a custom configuration. Only publish config/hyper.php if you specifically need to:

Enable route discovery
Change the signal key for specific integrations
Override the debug mode independent of APP_DEBUG

Verifying Installation

To verify Hyper is installed correctly, create a simple test route and view.

Add a route in routes/web.php:

php

Route::get('/hyper-test', function () {
    return view('hyper-test');
});

Create resources/views/hyper-test.blade.php:

blade

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Hyper Test</title>
    @hyper
</head>
<body>
    <div data-signals="{message: 'Hyper is working!'}">
        <h1 data-text="$message"></h1>
        <button data-on:click="$message = 'You clicked the button!'">
            Click Me
        </button>
    </div>
</body>
</html>

Visit /hyper-test in your browser. You should see "Hyper is working!" and clicking the button should change the message to "You clicked the button!" instantly, without a page reload.

If this works, Hyper is correctly installed and ready to use.

Updating Hyper

To update Laravel Hyper to the latest version:

bash

composer update dancycodes/hyper

After updating, republish the assets to get the latest JavaScript files:

bash

php artisan vendor:publish --tag=hyper-assets --force

The --force flag overwrites the existing files in public/vendor/hyper/js/ with the new versions.

Cache Clearing

If you've published the configuration file and update Hyper, you may need to clear your configuration cache:

bash

php artisan config:clear

Asset Compilation

Hyper's JavaScript files are self-contained and don't require integration with your build process. You don't need to:

Add Hyper to your vite.config.js or webpack.mix.js
Import Hyper in your JavaScript files
Compile or bundle Hyper with your assets

The published JavaScript files load independently as ES modules. This means you can use Hyper alongside your existing frontend build setup (Vite, Mix, etc.) without any configuration.

Next Steps

Now that Hyper is installed, you're ready to build your first reactive application:

Your First App: Follow our step-by-step tutorial building a counter application
Core Concepts: Understand how signals and reactivity work

Troubleshooting

Common Installation Issues

If you encounter errors after installing Hyper, here are the most common issues and solutions:

Fragment Errors ("unexpected end of file")

If you see errors like "unexpected end of file" when using @fragment directives, this is due to Laravel's Blade cache containing compiled views from before Hyper's directives were registered.

Solution:

bash

php artisan view:clear

This clears Laravel's compiled Blade views and allows them to be re-compiled with Hyper's directives properly registered.

Automatic Prevention

Hyper includes a Composer post-install hook that automatically clears the view cache during installation. However, in some environments, you may need to run this command manually.

When to clear cache:

After first installing Hyper
When updating Hyper to a new version
If you encounter Blade compilation errors
When deploying to a new environment

Why This Happens

Hyper registers custom Blade directives (@fragment, @endfragment, @signals, etc.) when the package boots. If views are compiled before these directives are registered, the compiled cache can become corrupted. Clearing the cache ensures views are re-compiled with all directives available.

Other Installation Checks

If you run into any other issues during installation, verify that:

You're running PHP 8.2 or higher: php --version
You're using Laravel 12 or higher: php artisan --version
The assets were published successfully: Check that public/vendor/hyper/js/hyper.js exists
The @hyper directive is in your view's <head> section

Deployment

When deploying to production, always run php artisan view:clear as part of your deployment process to ensure fresh Blade compilations.

Installation ​

Requirements ​

Installing Hyper ​

Publishing Assets ​

Including Hyper in Your Views ​

Configuration (Optional) ​

Signal Key ​

Debug Mode ​

Route Discovery ​

Verifying Installation ​

Updating Hyper ​

Asset Compilation ​

Next Steps ​

Troubleshooting ​

Common Installation Issues ​

Fragment Errors ("unexpected end of file") ​

Why This Happens ​

Other Installation Checks ​

Installation

Requirements

Installing Hyper

Publishing Assets

Including Hyper in Your Views

Configuration (Optional)

Signal Key

Debug Mode

Route Discovery

Verifying Installation

Updating Hyper

Asset Compilation

Next Steps

Troubleshooting

Common Installation Issues

Fragment Errors ("unexpected end of file")

Why This Happens

Other Installation Checks