livewire/livewire: Add return types on public FrontendAssets methods

Livewire v3 has been quietly tightening its internal type surface, and PR #10594 continues that work in a small but user-visible spot: the FrontendAssets mechanism. This is the class behind the @livewireStyles, @livewireScripts, and @livewireScriptConfig Blade directives. The PR adds native : string return types to every public static method on that class. If you're upgrading from v3.8.10, nothing about how your app renders changes at all — but if you run PHPStan, Larastan, or a similar static analyzer with strict settings, code paths that touch these methods will now pass type checking cleanly instead of reporting missing return types.

What changed

Seven public static methods on Livewire\Mechanisms\FrontendAssets\FrontendAssets gained explicit string return types:

• livewireScripts($expression): string
• livewireScriptConfig($expression): string
• livewireStyles($expression): string
• styles($options = []): string
• scripts($options = []): string
• js($options): string
• scriptConfig($options = []): string

As part of the change, the manual @return string docblock annotations on styles() and scripts() were removed — a native return type makes the annotation redundant, and unlike a docblock, the runtime and static analyzers both enforce it. In short:

// Before
public static function livewireScriptConfig($expression)

// After
public static function livewireScriptConfig($expression): string

Why it matters

These methods are the guts of Livewire's Blade integration. When you write @livewireScriptConfig in a layout, the registered directive calls FrontendAssets::livewireScriptConfig($expression), which returns a small snippet of raw PHP that Blade then compiles:

{{-- what you write --}}
@livewireScriptConfig

{{-- what the directive produces for the compiler --}}
{!! \Livewire\Mechanisms\FrontendAssets\FrontendAssets::scriptConfig($expression) !!}

Because the directive handlers return compiled PHP strings, anything that type-checks your templates — including compiled Blade output — previously had to guess at what these methods return. Projects that analyze their full dependency tree, precompile Blade strings, or build custom tooling on top of these APIs would see errors along the lines of Method FrontendAssets::scriptConfig() has no return type specified. With explicit types, those analyzers now have certainty instead of a docblock to trust.

What this looks like in your app

For the overwhelming majority of apps, the visible result is simply that your standard Livewire layout keeps working, unchanged:

<!doctype html>
<html>
<head>
    @livewireStyles
</head>
<body>
    {{ $slot }}

    @livewireScriptConfig
    @livewireScripts
</body>
</html>

If you call the underlying API directly — for example, to inject asset markup yourself rather than using the directives — your editor and analyzer now know exactly what you're getting:

use Livewire\Mechanisms\FrontendAssets\FrontendAssets;

$html = FrontendAssets::scripts();
// PHPStan/Larastan now knows $html is a string

Upgrade impact

The runtime impact is effectively zero. These methods always returned strings before; the types just weren't declared. There are only two scenarios worth knowing about:

1. Subclass overrides must now declare the type. If you extend FrontendAssets and override one of these methods, PHP requires your override to have a compatible return type. Omitting it produces a fatal error at class load:

class MyFrontendAssets extends FrontendAssets
{
    public static function scripts($options = []): string // add ": string"
    {
        return parent::scripts($options);
    }
}

2. A non-string return would now throw a TypeError. Since these methods only ever produced strings (asset HTML, compiled directive snippets), this is theoretical, but it's how the guarantee is enforced going forward.

There's no migration step, no config change, and no output difference in the rendered <script> and <style> markup.

Takeaways

• PR #10594 adds native : string return types to all seven public static methods on FrontendAssets, and replaces two docblock @return annotations with enforced code.
• @livewireStyles, @livewireScripts, and @livewireScriptConfig now pass type checking in applications that run strict static analysis — the primary motivation for the change.
• No behavior, output, or configuration changes; upgrading from v3.8.10 is a drop-in patch.
• The only action item: if you subclass FrontendAssets and override any of these methods, add a compatible : string return type to your override.
• This is part of a broader pattern of Livewire v3 internal hardening — expect small, additive typing improvements like this to keep landing in patch releases.

Sources

• Pull request #10594
• Release v4.4.7