How livewire/livewire works
Purpose and integration surface
Livewire is a Laravel package for server-authored, dynamically updated UI components. Laravel applications consume its PHP API/components and load its browser runtime. Primary integration and bootstrap points are src/LivewireServiceProvider.php, src/Livewire.php, and js/index.js.
Component model and discovery
A component is a PHP class with public state, actions, rendering, and lifecycle behavior. LivewireManager coordinates component registration and invocation; Finder resolves named, view-based, single-file, and multi-file components. Key paths: src/Component.php, src/LivewireManager.php, src/Finder/Finder.php.
Server request/render pipeline
Laravel routes Livewire update requests into request handling, which validates protocol/security constraints and delegates to the component mechanism. Component handling hydrates a client snapshot, applies property updates and method calls, renders Blade, dehydrates a new snapshot/effects payload, and signs/verifies payloads. Key boundaries: src/Mechanisms/HandleRequests/HandleRequests.php, src/Mechanisms/HandleComponents/HandleComponents.php, src/Mechanisms/HandleComponents/Checksum.php.
State serialization and extensibility
Snapshots cross the PHP/browser boundary through synthesizers: type-specific adapters serialize and hydrate primitives, collections, models, enums, form objects, and user-defined Wireable values. This is the central protocol extension seam. Key paths: src/Mechanisms/HandleSynths/HandleSynths.php, src/Mechanisms/HandleComponents/Synthesizers/Synth.php, src/Wireable.php.
Browser runtime and DOM reconciliation
The JavaScript runtime discovers Livewire roots and wire: directives, maintains client component state, batches/intercepts interactions, sends update messages, then morphs returned HTML into the DOM. It also exposes $wire, hooks, events, and Alpine interoperability. Key paths: js/lifecycle.js, js/request/request.js, js/morph.js.
Feature modules
Cross-cutting behavior is implemented as independently registered PHP feature modules, with corresponding browser support where needed. Major examples include attributes/lifecycle policy, nested components, navigation, validation, pagination, streaming, redirects, and reactive/modelable properties. Key paths: src/Features/SupportAttributes/SupportAttributes.php, src/Features/SupportNestingComponents/SupportNestingComponents.php, src/Features/SupportNavigate/SupportNavigate.php.
Compilation, Blade, and assets
Livewire extends Laravel Blade compilation for component tags, stable wire keys, morph-aware markup, and single-/multi-file component compilation. It also resolves and serves/injects the browser asset endpoint. Key paths: src/Mechanisms/CompileLivewireTags/CompileLivewireTags.php, src/Compiler/Compiler.php, src/Mechanisms/FrontendAssets/FrontendAssets.php.
Infrastructure and external boundaries
Runtime requirements are PHP/Laravel and the bundled JavaScript runtime; dependencies are managed through composer.json and package.json. Uploads use Laravel storage and can issue signed or multipart Amazon S3 upload flows; the browser runtime supports form, chunked, and S3 strategies. Key paths: src/Features/SupportFileUploads/SupportFileUploads.php, src/Features/SupportFileUploads/S3MultipartUpload.php, js/features/supportFileUploads/strategies/s3.js.
Main entry points: HandleComponents.php Component handler · LivewireServiceProvider.php Service provider · SupportAttributes.php Feature modules · index.js JS runtime
Components 24
Laravel / PHP runtime
Server package bootstrap, component execution, and protocol handling.
- Service provider · Registers Livewire services, mechanisms, features, and assets.
src/LivewireServiceProvider.php - Livewire API · Public PHP integration surface.
src/Livewire.php - Component · Defines public state, actions, lifecycle behavior, and rendering.
src/Component.php - Component manager · Coordinates component registration and invocation.
src/LivewireManager.php - Component finder · Resolves named, view, single-file, and multi-file components.
src/Finder/Finder.php - Update request handler · Validates update protocol and delegates component handling.
src/Mechanisms/HandleRequests/HandleRequests.php - Component handler · Hydrates, updates, renders, and dehydrates component payloads.
src/Mechanisms/HandleComponents/HandleComponents.php - Checksum · Signs and verifies component snapshots.
src/Mechanisms/HandleComponents/Checksum.php - Synthesizer registry · Selects type-specific snapshot serializers and hydrators.
src/Mechanisms/HandleSynths/HandleSynths.php - Synth contract · Base protocol adapter for typed values.
src/Mechanisms/HandleComponents/Synthesizers/Synth.php - Wireable · Lets application values define snapshot serialization.
src/Wireable.php - Feature modules · Registered policies such as attributes, nesting, navigation, validation, and pagination.
src/Features/SupportAttributes/SupportAttributes.php - Nested components · Coordinates nested component behavior.
src/Features/SupportNestingComponents/SupportNestingComponents.php - Navigation · Provides Livewire navigation behavior.
src/Features/SupportNavigate/SupportNavigate.php - Livewire compiler · Compiles Livewire tags and component forms into morph-aware markup.
src/Mechanisms/CompileLivewireTags/CompileLivewireTags.php - Frontend assets · Resolves, serves, and injects the browser runtime.
src/Mechanisms/FrontendAssets/FrontendAssets.php - File uploads · Supports form, chunked, and signed S3 upload flows.
src/Features/SupportFileUploads/SupportFileUploads.php
Browser runtime
Client state, requests, DOM updates, and upload support.
- JS runtime · Initializes Livewire client behavior and integrations.
js/index.js - Client lifecycle · Discovers roots and directives and maintains client components.
js/lifecycle.js - Update client · Batches interactions and sends update messages.
js/request/request.js - DOM morphing · Applies returned HTML to the browser DOM.
js/morph.js - S3 upload strategy · Performs browser-side multipart S3 uploads.
js/features/supportFileUploads/strategies/s3.js
External boundaries
Host application and storage services.
- Laravel application · Consumes Livewire components and routes update requests.
- Laravel storage / S3 · Receives stored or multipart uploaded files.
Connections 29
- Laravel application → Service provider: boots
- Laravel application → Livewire API: uses
- Service provider → Component manager: registers
- Service provider → Feature modules: registers
- Service provider → Livewire compiler: enables
- Service provider → Frontend assets: registers
- Livewire API → Component manager: delegates to
- Component manager → Component finder: resolves via
- Component manager → Component: invokes
- Laravel application → Update request handler: routes updates to
- Update request handler → Component handler: delegates updates
- Component handler → Component: hydrates and renders
- Component handler → Synthesizer registry: serializes state via
- Synthesizer registry → Synth contract: uses adapters
- Wireable → Synthesizer registry: extends protocol
- Component handler → Checksum: signs and verifies
- Feature modules → Nested components: includes
- Feature modules → Navigation: includes
- Component handler → Feature modules: applies policies
- Frontend assets → JS runtime: serves
- JS runtime → Client lifecycle: initializes
- Client lifecycle → Update client: queues interactions
- Update client → Update request handler: update payloads
- Component handler → DOM morphing: HTML and effects response
- JS runtime → DOM morphing: updates through
- File uploads → Laravel storage / S3: issues upload flows
- S3 upload strategy → Laravel storage / S3: multipart upload
- JS runtime → S3 upload strategy: uses for S3 uploads
- Feature modules → File uploads: includes