Chunk size looks like a simple configuration number - set chunkSize in your Resumable.js config and move on. In practice, it's a dial between competing pressures: throughput, retry cost, memory footprint, and server-side constraints. Get it wrong in either direction and you'll see slower uploads, wasted bandwidth on retries, or outright failures when chunks exceed server limits.
Start with 2 MiB fixed chunks for a custom receiver, or at least 5 MiB non-final parts for an S3 adapter, after checking the complete request path. These are measurement starting points. Use the planner to check limits, then compare completion time and retransmitted bytes on representative networks.
Upload planner and configuration generator
Resumable.js 1.1.0. Numeric planning only. Choose limits for your actual receiver and transfer path.
- Base upload requests
- 3
- Final chunk
- 2,621,440 bytes
- Optional chunk checks
- 3
- Maximum upload attempts if every chunk exhausts retries
- 12
- Bandwidth-only lower bound
- 4.40 seconds
- Illustrative scheduling latency
- 0.05 seconds, excluding processing and checks
Concurrency shares the total upstream bandwidth. Check requests, reconnects, backoff and server completion add time. Actual retry counts depend on failures. The planner uses constant memory even for very large numbers. This is a starting configuration; validate against your receiver and host. Follow the receiver contract or the object-storage adapter guidance.
This configuration targets your authenticated application receiver. A storage profile requires a multipart adapter with durable ownership, part state and completion. It cannot be pointed directly at a bucket.
const r = new Resumable({
"target": "/api/upload",
"chunkSize": 4194304,
"forceChunkSize": true,
"simultaneousUploads": 3,
"testChunks": true,
"maxChunkRetries": 3,
"chunkRetryInterval": 1000
}); The Trade-Off Spectrum
Each chunk request adds headers, framing and server processing. TCP and TLS setup depend on connection reuse, so they are not paid anew for every request. This overhead is roughly constant regardless of chunk size. The question is how much useful payload you amortize it across.
Too small (e.g., 256 KB chunks for a 1 GB file): You're making ~4,000 HTTP requests. Each one pays the fixed overhead cost. Connection reuse (HTTP keep-alive) helps, but you still pay for header parsing, server-side routing, chunk storage I/O, and response handling on every request. The upload spends more time in overhead than in actual data transfer. You'll also see higher CPU usage on the server from request handling.
Too large (e.g., 100 MB chunks for a 1 GB file): Only 10 requests, minimal overhead ratio. But if a chunk fails at 98% completion, you retransmit nearly 100 MB. On unreliable connections, this can mean the upload never finishes - each attempt at the large chunk fails before completing, and you're stuck in a retry loop. Large chunks also increase memory pressure in the browser during FormData construction and on the server during reception.
The sweet spot depends on your specific combination of network conditions, server infrastructure, and file sizes.
Throughput Math
Let's put rough numbers on the overhead. For an illustrative model only, suppose a request involves:
- TLS handshake: ~50-100 ms for a new connection (amortized to near zero with connection reuse)
- HTTP headers + multipart framing: ~1-2 KB per request
- Server-side processing per chunk: varies, but 5-50 ms for disk write + response generation
- Round-trip latency: 20-200 ms depending on geography
For a connection reusing an existing TLS session, the per-request overhead is roughly 30-100 ms and 2 KB of header data. At 1 MB chunk sizes, that's 30-100 ms overhead per 1 MB transferred. At 10 MB chunks, it's 30-100 ms per 10 MB - a 10x improvement in overhead ratio.
On a 100 Mbps connection, uploading 1 MB takes about 80 ms of pure transfer time. So the overhead (30-100 ms) is significant relative to the transfer - you're spending almost as much time on ceremony as on actual data transfer. At 10 MB chunks, the transfer takes ~800 ms and the overhead becomes a rounding error.
This math shifts dramatically on slower connections. On a 5 Mbps mobile connection, 1 MB takes ~1.6 seconds to transfer. The 30-100 ms overhead is negligible. Here, smaller chunks are fine from a throughput perspective, and they give you the retry advantage.
Failure Cost
This is where chunk size has the most dramatic impact. The cost of a failed chunk is proportional to the chunk size multiplied by how far it got before failing.
| Chunk Size | Failure at 98% | Data Retransmitted |
|---|---|---|
| 1 MB | 0.98 MB wasted | 1 MB retransmit |
| 5 MB | 4.9 MB wasted | 5 MB retransmit |
| 10 MB | 9.8 MB wasted | 10 MB retransmit |
| 50 MB | 49 MB wasted | 50 MB retransmit |
For a fixed amount of uploaded data, larger chunks also mean fewer opportunities for a request to fail. A constant per-request failure probability does not by itself imply that total wasted bytes grow linearly with chunk size. Use measured failure rates and interruption positions for each candidate size. Longer requests may have different failure probabilities, especially under timeouts.
The retries and resume guide covers how Resumable.js handles these failures and the retry strategies available.
Memory and Browser Considerations
File.slice() creates a Blob representing a range of bytes. Browser buffering is implementation-dependent, so concurrency multiplied by chunk size is a planning estimate, not a measured heap allocation. Inspect the actual browser and receiver under load. Explicitly reading each whole file into an ArrayBuffer would add a separate allocation that this planner does not require.
Server-Side Constraints
Your chunk size must respect the request body limits configured at every layer of your server infrastructure:
Check the smallest effective request limit across the proxy, runtime and receiver. Hosting limits belong to the deployed plan and request path. Next.js alone does not identify those limits. Enter your verified byte cap in the planner, reserving space for request framing.
Provider multipart limits apply independently. S3 requires at least 5 MiB for non-final parts and supports at most 10,000 parts. A browser-to-storage architecture can keep file bytes out of the application function while retaining an authenticated signing and completion API. Consult the storage provider limits and upload costs before choosing that path.
Practical Starting Points
These ranges work as sensible defaults before you have real measurement data:
| Network Condition | Recommended Chunk Size | Rationale |
|---|---|---|
| Mobile / unstable (< 10 Mbps) | 1-2 MB | Low retry cost, fits in memory |
| Broadband (10-100 Mbps) | 5-10 MB | Good throughput/retry balance |
| LAN / datacenter (100+ Mbps) | 10-20 MB | Minimize request overhead |
| Known reliable + large files | 20-50 MB | Max throughput, acceptable retry cost |
For an S3 adapter, 5 MiB meets the minimum non-final part requirement. Confirm the receiver body cap and file size before using it, and select forceChunkSize explicitly. A custom receiver may support smaller parts.
const r = new Resumable({
target: '/api/upload',
chunkSize: 5 * 1024 * 1024, // 5 MB - a solid default
simultaneousUploads: 3,
});
Change the layout between upload sessions
Resumable.js 1.1.0 prepares chunk objects when adding a file. A changed local variable does not reconfigure those objects. Select the next configuration before creating a new instance and server session. Keep the same boundaries while retrying an existing session so stored part numbers continue to identify the same bytes.
Record measured request times in application-owned state. chunkingComplete identifies preparation, while fileSuccess indicates completion of that client's file requests. The application may still need assembly, scanning and release. Measure those stages separately before choosing a faster setting.
Measuring Your Specific Pipeline
Theory gets you to a starting point. Measurement gets you to the right answer. The variables that matter are specific to your infrastructure: your CDN's request overhead, your server's chunk processing time, your users' actual network conditions.
A practical measurement approach:
- Pick 3-4 chunk sizes spanning your expected range (e.g., 1 MB, 5 MB, 10 MB, 20 MB).
- Upload a representative file size (say, 500 MB) at each chunk size.
- Measure total wall-clock time, not just transfer speed. Include chunk verification, server processing, and the final merge step.
- Run the test from at least two network conditions: your office (good) and a throttled connection simulating mobile (poor).
- Compare. The right chunk size is the one that minimizes total upload time across your expected range of network conditions, while staying within your server constraints.
The timeouts guide covers how to set appropriate timeout values for your chosen chunk size - a 20 MB chunk on a slow connection needs a much longer timeout than a 1 MB chunk. Getting the chunk size right and the timeout wrong still results in failures.
The chunking fundamentals explain how Resumable.js divides bytes and how the receiver assembles them. Start there if you need to understand the mechanics before tuning the numbers. A discussion of large R2 upload speeds illustrates why speed comparisons need a specified client path. Use the same file, region and transfer architecture when comparing measurements.
