Weave Code
Laravel Chunky Laravel Package
netipar/laravel-chunky
Resumable, chunk-based file uploads for Laravel. Send large files reliably over flaky connections with server-side chunk tracking and fingerprint-based resume. Typed backend plus Vue, React, Alpine and Livewire frontends. No queue worker or broadcasting required by default.
Chunky for Laravel provides resumable, chunk-based file uploads for large files over unreliable connections. Built on ports & adapters, it tracks chunks server-side so uploads resume via a file fingerprint, while a module-level frontend manager keeps uploads alive across SPA navigation.
- Resumable uploads with database or filesystem tracking behind one contract
- Framework-agnostic frontend with Vue 3, React, Alpine.js, and Livewire wrappers
- Works without infrastructure — no queue worker or broadcasting required by default
- Direct-to-S3 and batch upload support
- Typed end to end with PHPStan max and strict TypeScript
Frequently asked questions about Laravel Chunky
- How do I install laravel-chunky in a Laravel application?
- Install the backend with composer require netipar/laravel-chunky, then publish the package config and run the migrations for its upload tracker table. On the frontend, install the matching JavaScript package and drop in the Vue, React, Alpine or Livewire wrapper you need. The happy path is short: Composer, publish, migrate, npm install, then wire up the composable.
- Does laravel-chunky support resumable uploads after a page reload?
- Yes. Chunks are tracked server-side, and a reload resumes the same upload via a file fingerprint instead of re-sending bytes that already landed. On the frontend, uploads are owned by a module-level manager, so SPA page navigation does not cancel an in-flight upload.
- Which frontend frameworks does laravel-chunky support?
- It ships first-class wrappers for Vue 3, React 18/19, Alpine.js and Livewire, all built on a framework-agnostic JavaScript upload engine. Because the backend is a plain REST contract, frontend choice does not constrain the backend, and Livewire shops can avoid adding an npm dependency by using the Composer-installed Livewire path.
- Do I need a queue worker or broadcasting to use laravel-chunky?
- No. In the default auto mode, small files assemble in-request and the final response already carries the file plus your payload, with no Echo and no worker required. Queue assembly is available later for scale, but if you enable it, AssembleFileJob must not run on the sync queue driver.
- What PHP and Laravel versions does laravel-chunky require?
- The package requires PHP 8.3 or higher. Supported Laravel versions are defined by the package's composer.json constraints, so check those before installing into an older application. The frontend packages also have their own Node and framework version requirements.
- How do I secure laravel-chunky upload routes?
- The package registers its endpoints under a named middleware group, chunky.routes.middleware, which you should harden with your own authentication and authorization middleware. A configurable Authorizer contract lets you decide which users may touch which uploads, and foreign upload IDs return 404 to block probing. Expired uploads return 410, late chunks against terminal states return 409, and lock contention returns 503 with a documented safe retry.
- How do direct-to-S3 uploads work in laravel-chunky?
- Chunky supports direct-to-S3 targets, but be aware that cloud-disk targets buffer the full file locally before uploading to object storage. That means staging storage needs roughly concurrency multiplied by max_file_size of headroom, effectively doubling storage cost and transfer time for S3 targets. Size your disks with that in mind before enabling it in production.
- Can laravel-chunky handle batch uploads of multiple files at once?
- Yes, batch uploads are supported alongside single-file uploads and resumable sessions. You can control the limits through configuration such as max_files_per_batch and metadata.max_keys, which should be tuned against your abuse profile. Keep those limits conservative on public endpoints.
- How does laravel-chunky clean up temporary chunks and abandoned uploads?
- The package includes a chunky:cleanup console command that you schedule to remove stale staging chunks and tracker rows. Before relying on it, confirm the default TTL and retention behavior so cleanup cannot race an upload that is still in flight. Temp chunks live under storage/app/chunky/temp/{uploadId}/ and assembled files under storage/app/chunky/uploads/{uploadId}/{fileName}.
- Is laravel-chunky production-ready, and what are the maintenance risks?
- Treat it as young software: it has a single maintainer and few dependents, and its upgrade notes warn that minor releases can carry breaking changes, so pin exact versions and budget upgrade work per bump. It also assumes real infrastructure in production, including a queue driver other than sync and a lock store that supports Cache::lock, such as Redis, Memcached, database or DynamoDB rather than array or file. The MIT license and self-contained ports-and-adapters architecture make forking a credible fallback. Plan for that possibility and test the upload contract with your own client tests.
Weaver
How can I help you explore Laravel packages today?