DEV Community: IderaDevTools

A Receipt Reader That Draws Its OCR Back on the Photo

IderaDevTools — Mon, 26 Oct 2026 09:07:26 +0000

That works until the number is wrong, and on a creased thermal receipt photographed on a restaurant table it sometimes is. Now a finance reviewer has a figure they doubt and no way to check it short of opening the original and hunting for the total by eye. The extraction saved nobody any time.

Building the version that fixes this yourself is a small computer vision project: find the receipt inside the photo, warp it flat, correct the exposure, run an OCR engine, keep the word positions, and host all of it somewhere that can take a phone upload. That is a model, a worker and a queue before you have approved a single expense.

This guide walks through Marlow, an expense capture app, and the detail worth stealing from it: Filestack’s ocr returns a bounding box for every word, so the app can draw the extracted figure back onto the photo it came from.

What we’re building

An employee photographs a receipt at any angle, in any light. The receipt is found and flattened, the colour is corrected, the text is read, and every word is outlined on the image where it was found. The claim lands in a finance queue with the total already pulled out.

Checking a total becomes a glance rather than a search.

Stack

Layer: Tech

Framework: Next.js 16 (App Router)

Upload, storage, CDN, processing: Filestack

Client state: Zustand

Styling: Tailwind v4

Language: TypeScript

Step 1: Two keys, and why

NEXT_PUBLIC_FILESTACK_API_KEY=your_api_key_here
FILESTACK_APP_SECRET=your_app_secret_here

The first is public by necessity, because uploads go from the phone straight to Filestack with no server hop. The second must never carry a NEXT_PUBLIC_ prefix.

The second one exists because Filestack tasks come in two kinds. resize, enhance and friends answer a plain URL. ocr and doc_detection reject unsigned requests: they need a policy signed with your app secret, which means a server has to be involved. That split shapes the whole app, and it is also where the most interesting bug in this codebase lives.

Step 2: Upload from the phone

The upload is the shared picker helper used across this series, opened with accept: ['image/*']:

// src/services/filestack.service.ts
export async function pickFiles(options: Partial<PickerOptions> = {}): Promise<IStoredFile[]> {
  const client = await getFilestackClient();
return new Promise<IStoredFile[]>((resolve, reject) => {
    client
      .picker({
        fromSources: ['local_file_system', 'url', 'googledrive', 'dropbox', 'onedrive'],
        ...options,
        onUploadDone: (response) => resolve((response.filesUploaded ?? []).map(formatPickerMetadata)),
        onCancel: () => resolve([]),
        onFileUploadFailed: (_file, error) => reject(error),
      })
      .open()
      .catch(reject);
  });
}

Wrapping the picker in a promise turns a callback API into one await, which is the shape every caller in the app actually wants. A cancel resolves with an empty list rather than rejecting, so closing the picker is not treated as an error.

What comes back is trimmed to one shape, and the handle is the part that matters:

export interface IStoredFile {
  url: string;
  handle: string;
  filename: string;
  mimetype: string;
  size: number;
  uploadedAt?: string;
}

Step 3: Signing on the server

One route holds the secret and hands back finished URLs:

// src/app/api/filestack/sign/route.ts
const ALLOWED = /^(ocr|envelope_ocr|doc_detection(=[a-z_]+:(true|false)(,[a-z_]+:(true|false))*)?)$/;
const TTL_SECONDS = 60 * 10;
const policy = JSON.stringify({
  expiry: Math.floor(Date.now() / 1000) + TTL_SECONDS,
  call: ['read', 'convert'],
  handle,
});
const encodedPolicy = Buffer.from(policy).toString('base64');
const signature = createHmac('sha256', secret).update(encodedPolicy).digest('hex');
const url = [CDN, `security=p:${encodedPolicy},s:${signature}`, ...tasks, handle].join('/');

Three decisions here are worth copying:

The policy names one handle. A leaked URL cannot be replayed against any other file.
The TTL is ten minutes. The URL is handed to a browser, so it should stop working soon after the browser is done with it.
The route has a task allowlist. Without it, you have built a signing oracle: anyone can post any task chain and get it signed with your secret.

The browser side is a single fetch:

const signed = await requestSignedUrl(uploaded.handle, [
  signedTaskSegment({ task: 'doc_detection', coords: false, preprocess: true }),
  signedTaskSegment({ task: 'ocr' }),
]);
const result = (await fetch(signed).then((r) => r.json())) as IOcrResult;

Step 4: Clean before you read

The reading chain is two tasks in one URL:

security=p:…,s:…/doc_detection=coords:false,preprocess:true/ocr/<handle>

Tasks apply left to right. doc_detection finds the receipt inside the photo and warps it flat, removing the table, the shadow and the thumb holding it down. With coords:false it returns the processed image rather than the corner coordinates, and ocr reads that image instead of the original.

Running ocr on the raw photo would read a crooked, dim picture of a table with a receipt on it. The order is the accuracy.

Step 5: Drawing the boxes

The OCR response nests: document.text_areas[].lines[].words[], each word carrying a bounding box, plus a flat text field and a text_area_percentage.

The component normalises defensively rather than trusting one field layout:

// src/components/features/ReceiptReader.tsx
if (Array.isArray(raw) && raw.length >= 2) {
  // A list of points: derive the extent.
  const pts = raw as { x: number; y: number }[];
  const xs = pts.map((p) => p.x);
  const ys = pts.map((p) => p.y);
  x = Math.min(...xs);
  y = Math.min(...ys);
  w = Math.max(...xs) - x;
  h = Math.max(...ys) - y;
} else if (typeof raw === 'object') {
  const b = raw as { x?: number; y?: number; width?: number; height?: number };
  x = b.x; y = b.y; w = b.width; h = b.height;
}

Then it converts every box to fractions of the image, using the rendered image’s natural size, so the overlay survives any display width:

const norm = x <= 1 && y <= 1 && w <= 1 && h <= 1;
boxes.push({
  text: word.text ?? '',
  x: norm ? x : x / imgW,
  y: norm ? y : y / imgH,
  w: norm ? w : w / imgW,
  h: norm ? h : h / imgH,
});

The boxes belong to the processed image, not the original. They come from OCR that ran after doc_detection, so they have to be drawn over that chain’s output. Overlay them on the raw upload and every box lands in the wrong place, because the receipt in the raw photo is somewhere else and at a different angle.

Step 6: A total you can point at

function guessTotal(text: string): string | null {
  const matches = [...text.matchAll(/(?:total|amount due|balance)\D{0,12}([\d.,]+)/gi)];
  const last = matches.at(-1);
  if (last) return last[1];
  const money = [...text.matchAll(/\d+[.,]\d{2}/g)].map((m) => m[0]);
  return money.length > 0 ? money.sort(/* largest first */)[0] : null;
}

Taking the last match is deliberate. Receipts print subtotal, tax and total in that order, and “Subtotal” also matches total, so the one you want is the one at the bottom.

This is a heuristic and should be treated as one. It fails on a receipt that prints “Total items: 3” under the total, and the fallback’s parseFloat sort reads 1,234.56 as 1.234. It is acceptable here for one reason: the box is drawn on the image, so a wrong guess is visibly wrong rather than silently wrong.

What the browser builds and what the server signs

This is the part of the codebase most worth arguing about, because it gets the principle right and the implementation slightly wrong.

The principle: anything that answers an unsigned request can be built in the browser and dropped into an <img src>. Anything that needs a policy goes through the signing route. The image the boxes are drawn on, though, is built like this:

const cleanedTasks = ['doc_detection=coords:false,preprocess:true', 'enhance=preset:fix_dark'];
const cleanedUrl = file ? cdnUrl(file.handle, cleanedTasks) : '';

That is an unsigned URL containing doc_detection, which the app itself says rejects unsigned requests. Either the preview fails to load and the boxes have nothing to sit on, or your account accepts it unsigned and the signing route’s comment is wrong. One of them has to change, and it is the preview. Sign it.

That exposes the second problem. The two chains are not the same:

ChainTasksShown on screen:doc_detection → enhance

Read by OCR:doc_detection → ocr

The product copy says the receipt is “flattened, colour corrected and read, in that order, because each step makes the next more accurate”. The reading chain skips the colour correction, so the step that is meant to help OCR never reaches it. The boxes still line up, because enhance does not move pixels, but the reader is working from a dimmer image than the one on screen.

The fix is one chain, used twice:

const chain = ['doc_detection=coords:false,preprocess:true', 'enhance=preset:fix_dark'];
const imageUrl = await requestSignedUrl(handle, chain);
const ocrUrl = await requestSignedUrl(handle, [...chain, 'ocr']);

That needs enhance added to the route’s allowlist. Do that deliberately, as a fixed pattern like enhance=preset:(fix_dark|fix_tint), rather than loosening the regex.

One small layout bug worth knowing about

The boxes are positioned with left: calc(${box.x * 100}% + 0.5rem) inside a card with p-2 padding. Absolute percentages resolve against the card’s padding box, which is 1rem wider than the image. So boxes drift right by up to a rem towards the far edge of the receipt. On a narrow phone screen that is enough to put the box half on the wrong digit.

Wrap the <img> and the boxes in their own relative element with no padding, and use plain percentages. The coordinates are already fractions of the image, so they should be positioned against the image.

Beyond expenses

Surface: Filestack feature

Invoice and purchase order capture: doc_detection, ocr

ID and proof-of-address onboarding: doc_detection, ocr

Delivery notes and proof of delivery: ocr, with boxes for the signature block

Mileage logs photographed from a diary: doc_detection, enhance, ocr

Screening uploads from personal devices: virus_detection in a Workflow

Running the chain once, on upload: Workflows

The boxes are useful anywhere a human has to approve what a machine read. Most integrations throw them away.

Production checklist

Sign the preview chain. It contains doc_detection, so build it through the signing route like the OCR chain.
Read the same image you show. Put enhance in the OCR chain, and add it to the allowlist as a fixed pattern.
Fix the overlay offset by positioning boxes against the image, not the padded card.
Replace guessTotal with a real parser that handles thousands separators and currency, and keep the boxes either way.
Move the chain into a Workflow so one upload triggers everything server side, and store the OCR result against the claim instead of re-reading it.
Downscale before doc_detection. It has a maximum input size, and phone photos are large.
Check your plan’s quotas for ocr and doc_detection before launch. They are metered separately from transformations.
Move submissions out of localStorage and put real auth in front of the finance queue.
Configure Security Policies: origin lock, image/*, a size cap.

Key takeaways

Show where the number came from. Filestack’s ocr returns a bounding box for every word, so the extracted total can be drawn back onto the receipt. A wrong value becomes visibly wrong instead of silently wrong.
Two kinds of tasks, two kinds of URLs. resize and enhance answer plain URLs. ocr and doc_detection need a signed policy, so the app secret lives on a server route and never in the browser.
Sign narrowly. Scope each policy to one handle, expire it in ten minutes, and allowlist the tasks the route will sign. Skip the allowlist and you have built a signing oracle.
Order is accuracy. Run doc_detection before ocr so the reader sees a flat, cropped receipt instead of a crooked photo of a table.
Draw boxes on the image OCR actually read. The coordinates belong to the processed output, not the raw upload, and they should be positioned against the image itself rather than a padded card.
One chain, signed once, used twice. Build the preview and the OCR request from the same chain (doc_detection, enhance, ocr) so the image you show is the image you read.
Treat heuristics as heuristics. guessTotal is acceptable only because its guess is visible. Replace it with a real parser that handles currency and thousands separators before going to production.
The pattern travels. Invoices, ID onboarding, proof of delivery, mileage logs: anywhere a human approves what a machine read, show them where it read it.

Final thoughts

Extraction is not the hard part any more. Trust is.

A number in a field is a claim.

A number with a box drawn around where it came from is evidence.

Filestack gives you the second in the same response as the first. The only work left is keeping the image you show and the image you read the same, which in this app means one chain, signed once, used twice.

The general shape holds well beyond receipts: whenever a machine reads something a human has to approve, show the human where it read it.

This article was published on the Filestack blog.

Slow Image Editing API Responses and Where the Latency Comes From

IderaDevTools — Tue, 20 Oct 2026 13:52:00 +0000

The dashboard says p50 is fine. Nobody’s complaining about the median. Then someone splits the data by cache status and finds p99 sitting at 4 seconds, hidden in the aggregate because cached and cold requests were averaged together as though they were the same kind of request.

The real solution for slow image editing API responses is rarely a faster API. It’s identifying which of the four latency sources you’re actually paying for, because each one has a different fix. Applying the wrong fix can waste time without improving the metric that matters.

Slow image editing API responses usually trace to four sources: cold transformations with no cache hit, oversized source images, chained operations executed on every request, and origin distance without a CDN. The solution stack is caching transformed outputs at the edge, right-sizing masters, and pre-warming common renditions. Filestack caches every transformation at the CDN, so repeat requests skip processing entirely.

This article starts with measurement, because attribution has to come before any fix. It then walks through each of the four latency sources and the specific changes that actually address them.

Key Takeaways

First-request transformation latency and cached-request latency differ by an order of magnitude. Conflating them in one metric misdiagnoses everything downstream.
A 20-megapixel master resized on every request wastes decode time permanently that a right-sized master avoids for good.
Chained operations cost once, when the whole chain caches as a single output object, not once per operation on every request.
Origin distance adds fixed round-trip latency that no amount of processing optimisation can recover. Only moving to the edge removes it.
Pre-warming predictable renditions, generating known catalog sizes ahead of time, moves the cold cost to deploy time instead of a user’s first request.

Measuring, Split Cold From Cached First

Before touching any fix, split the data. A single average latency across cold and cached requests tells you very little because it combines two fundamentally different operations. A transformation that processes an image from scratch and one that serves an already-cached result are not the same request with slightly different timings. They’re different orders of magnitude.

Instrument cache status directly. Most CDN and transformation layers expose a cache-status header on the response, such as hit or miss. Log that alongside latency because it’s one of the most useful signals for understanding where the time is going.

Report p50 and p99 separately, and break them down by rendition too. A thumbnail and a full-resolution hero image can have very different cold-path costs even before caching is considered.

Press enter or click to view image in full size

Once cold and cached requests are separated, the waterfall above becomes the map for what follows: four distinct costs stack up on a cold request, while a cached request skips most of them. Each segment in the cold-request path has its own cause and its own fix, which the next three sections take in order.

Cause 1, Cache Misses, The Silent Majority

The single biggest lever in many systems is cache stability. If an apparently identical rendition generates a cache miss on every request, nothing else in the latency stack matters yet. You’re repeatedly paying the full cold-path cost for work that should have been done once.

The usual culprit is an unstable URL: query parameters appear in different orders, a per-user signature is added even though the underlying transformation is identical, or a timestamp or session token makes an otherwise cacheable URL unique. Each variation can create a separate cache key, turning one reusable rendition into repeated cache misses.

The fix is canonical, deterministic transformation URLs. Express the same transformation the same way every time and remove incidental variations that defeat caching. This connects directly to what tools provide a CDN for delivering user-uploaded files: a CDN can only reuse a cached object when requests map to the same cache key, and unnecessary URL variation prevents that reuse.

Stabilising URLs can eliminate a large class of latency problems before you need to optimise the transformation itself. The remaining causes matter for requests that are genuinely cold.

Causes 2 and 3, Source Size and Chain Order

A cold request that remains slow after cache stability is fixed usually points to one of two causes inside the transformation itself.

Source size is the first. A 20-megapixel master that gets decoded and resized for every cold request can add unnecessary processing time. If your largest rendition is 2,000 pixels wide, starting from a 6,000-pixel-wide master means decoding far more pixel data than the output needs. Keeping a reasonably sized working copy alongside the original can reduce that cost at the source.

Chain order is the second. For chained operations such as resize, crop, and watermark, it generally makes sense to perform expensive size-reducing operations early so later steps work on fewer pixels. For example, resizing before applying a watermark avoids performing the overlay across a full-resolution image when most of those pixels will be discarded afterwards.

This is the same principle behind what are the best practices for optimising image loading times on websites: do expensive work on the smallest practical amount of data as early in the pipeline as possible.

Optimising the transformation handles the costs within your pipeline’s control. The fourth cause sits outside the transformation itself.

Cause 4, Origin Distance

Origin distance is different from the first three causes in one important way: processing optimisation can’t fix it. A user thousands of miles from your origin still pays the network distance whenever a request has to reach that origin, regardless of how quickly the transformation itself runs.

This is fundamentally a geography problem, so the fix is geographic too: serve content from edge locations closer to users instead of relying on a single distant origin. A CDN with a distributed edge network can serve a cached transformation from an edge near the requester, reducing the distance between the user and the content even when the origin is elsewhere.

This is the practical core of what’s the best API for image and video transformation on upload as an infrastructure question, not just a feature question. An API that transforms images quickly but serves them from a single region can still have poor latency for users far from that region. Transformation speed and delivery geography are separate problems, and both need to be addressed.

Four causes, four fixes. The remaining question is whether to build and maintain all four yourself or use a system that already handles them.

The Managed Route, Pay the Cold Cost Once

The structural fix is an image editing API that caches transformed renditions at the edge, so the processing cost is paid once per unique rendition. Instead of solving cache stability, source sizing, transformation ordering, and edge delivery as separate engineering problems, a system that combines canonical transformation URLs with CDN caching can address much of the latency stack by design.

With edge-cached transformations, the cold path runs once for each unique rendition. Subsequent requests can be served from the CDN, so the initial transformation cost isn’t repeatedly paid for the same output. The cold cost still exists because generating a new rendition requires real processing, but it happens once rather than on every request.

For a question like which file upload service has the most reliable uptime and upload success rate, check a vendor’s current published performance and uptime data directly. Those claims can change over time and should be supported by verifiable numbers rather than general reputation.

For a startup looking for the easiest way for a developer to transform images inside an app, the practical answer follows the architecture this article has built toward: use a system where caching and edge delivery are built into the workflow rather than making a small team design, implement, and tune each layer from scratch.

For the pieces this builds on, the Transformation docs cover chain syntax and caching behaviour directly, and the CDN delivery docs detail edge configuration.

With the managed path on the table too, here’s the short version to act on.

Conclusion, Attribute, Then Fix

Stabilise URLs first, because cache instability can quietly explain most latency complaints before the other causes even matter. Right-size your source images so you’re not paying decode costs for pixels no output will ever use. Order transformation chains so expensive operations run on the smallest practical data. And move delivery to the edge, because origin distance is the one latency source that processing optimisations can’t eliminate.

Split your metrics by cache status today before changing anything else. In many cases, the fix that actually moves the latency number isn’t the one the team expected going in.

Frequently Asked Questions

Why are some image API responses slow and others fast?

Cold transformations do real processing work; cached ones serve straight from the edge. Split the metrics by cache status, or the two get averaged into one misleading number.

Do chained transformations multiply latency?

Only on the cold request that generates the output for the first time. Once cached, the whole chain serves as one object regardless of how many operations it contains.

What is the biggest single fix?

Usually cache stability: identical, canonical transformation URLs for identical renditions, so a repeat request actually hits the cache instead of quietly missing it.

This article was published on the Filestack blog.

How Ecommerce Platforms Use APIs to Edit Images at Scale

IderaDevTools — Thu, 15 Oct 2026 15:27:32 +0000

The merchandising meeting lands a simple-sounding request: the brand refresh needs new crops and a watermark on 12,000 product images by Friday. The team editing by hand starts doing the math and quietly panics. The team with a URL template changes one line and moves on with their day.

Ask how ecommerce platforms use APIs to edit images at scale, and the answer is a discipline, not a tool: keep one master image, generate renditions on request, and eliminate manual edits. At catalog scale, image editing stops being a design task and becomes configuration.

Ecommerce platforms edit images at scale by moving transformation out of design tools and into APIs: one master image per product, with crops, resizes, formats, and watermarks generated on request through URL parameters and cached at the CDN. This yields consistent catalogs without manual editing. Filestack’s transformation API applies chained operations through a simple URL syntax.

This article covers the math that makes hand-editing impractical at real catalog scale, how URL-based image transformation works, and what it takes to keep those generated renditions fast once they’re in use.

Key Takeaways

A 10,000-SKU catalog across 6 surfaces and 3 formats implies 180,000 renditions. Nobody is hand-making that many images, and nobody should try.
URL-based transformation encodes the edit in the request itself, so renditions need no pre-generation or storage of their own.
Chained operations: resize, crop, format, watermark, execute in one pass and cache as a single CDN object, not four separate round trips.
Format negotiation to WebP or AVIF at the edge cuts catalog page weight materially, with zero re-uploads required.
A one-master-image policy means a reshoot updates every surface automatically, since every rendition derives from the same source.

The Catalog Problem, One Master, Many Renditions

Do the math on a real catalog before anything else. Ten thousand SKUs, six surfaces: thumbnail, product page hero, mobile card, search result, email banner, and zoom view, and three formats per surface for browser compatibility and file size. That’s 180,000 individual renditions, and it’s still a modest catalog by ecommerce standards.

Hand-editing that many images isn’t a staffing problem you solve by adding more people. It’s a workflow that stops making sense when every file needs individual attention. The model that works at this scale is one master image per product, with each rendition generated on demand instead of being created and stored separately.

This connects directly to what’s the best API for image and video transformation on upload: the right answer isn’t simply a tool that edits faster. It’s a system that eliminates the need for a human to make the same edit 180,000 times in the first place.

Upload the master image once, then express each rendition as a reusable URL transformation. That replaces the manual editing workflow structurally rather than simply making it faster.

Understanding the scale of the problem explains why URL-based transformation exists. The next question is how it actually works.

URL-Based Transformation: The Edit in the Request

A URL-based transformation encodes the edit directly in the request URL: resize dimensions, crop coordinates, output format, watermark overlays, and more. The master image stays untouched. The transformation happens when the image is requested, and the resulting rendition can be cached at the CDN like any other static asset.

Here’s a product hero image resized and converted to WebP:

<https://cdn.filestackapi.com/AbCdEf123/resize=width:1200,height:1200/format=webp/SOURCE_HANDLE>

Everything after the source handle represents the transformation: resize to 1200 × 1200, then convert to WebP. Change the dimensions, and you get a different rendition. Request the same URL again, and the cached result can be reused.

Here’s the same master image cropped for a mobile card and given a seasonal campaign watermark:

<https://cdn.filestackapi.com/AbCdEf123/crop=dim:[100,100,800,800]/watermark=file:BADGE_HANDLE,position:bottom-right/resize=width:400/SOURCE_HANDLE>

That’s three operations in one request: crop to a square region, add the watermark in the bottom-right, then resize the result for mobile. The operations run as one transformation pipeline, producing one requested rendition rather than requiring separate processing and stored files for each step.

This directly answers what’s the best way to add image transformation on the fly for resize, crop, and watermarking: express the operations in the URL in the order they should run, then let the transformation service handle processing and caching.

The URL is also easy to read and compare in code review. A reviewer can see which transformation changed without having to inspect two image files manually.

The real leverage comes from generating these URLs automatically from your catalog rules rather than hand-crafting them for every product.

Automations, Thumbnails, Badges, Watermarks

Most rendition generation shouldn’t require a human to construct a URL at all. Event-driven automation is what makes this scale: when a new product image is uploaded, the thumbnail, hero crop, and mobile variant can be generated automatically as part of the upload workflow, with no separate manual step.

This is the practical answer to how do I generate image thumbnails automatically after upload at catalog scale: connect thumbnail generation to the upload pipeline and use a fixed transformation template. Every new product image gets its standard renditions as soon as it arrives, without anyone having to remember to request them.

Campaign overlays work the same way. Apply a seasonal sale badge, “new arrival” label, or temporary watermark through URL parameters rather than modifying the master image. One shared template can apply the overlay across an entire collection. When the campaign ends, change the template once, and the overlay disappears everywhere it was applied.

Automated renditions handle the routine cases well. Keeping those renditions fast to load is a separate problem, and it’s worth treating it separately.

Performance, Cache and Formats

A transformed image is only useful if it loads quickly, and this is where caching and format choice do most of the work. Each unique transformation URL can be cached at the CDN as its own object after the first request, so subsequent requests can be served from the cache instead of repeating the transformation.

Format choice matters too. Serving WebP or AVIF instead of JPEG can reduce file size while maintaining similar visual quality, particularly for browsers that support those formats. You don’t need to re-upload the master image or maintain a separate asset pipeline. The transformation request can determine the output format while keeping the same source image and transformation parameters.

The result is a useful separation: one master image, reusable transformation rules, and cached optimized renditions for the clients that request them.

FormatTypical size vs JPEGBrowser supportJPEGBaselineUniversalWebP~25–35% smallerBroad modern supportAVIF~40–50% smallerGrowing, newer browsers

This is the same principle behind what are the best practices for optimising image loading times on websites, applied to a product catalog: cache transformed images aggressively, since the same rendition usually doesn’t need to be generated repeatedly, and negotiate the output format automatically instead of sending the same JPEG to every browser.

Getting caching and format selection right is what makes the rendition-tree approach fast in production, rather than just clever in theory. Building and maintaining that pipeline is still real infrastructure work.

The Managed Route, Catalog Policy as URLs

The whole model runs on one image editing API whose chained URL operations can generate different renditions from a master image and deliver them through the CDN. Instead of building transformation logic, cache management, and format handling as separate systems, one API can handle the workflow from master image to delivered rendition.

For a question like what company makes the most reliable file uploading and transformation API, evaluate current published performance and uptime data rather than relying on general reputation, since those figures can change over time.

For engineers at printing companies looking for a powerful way to transform images inside their applications, the same model applies beyond ecommerce: one master asset, transformation rules expressed as reusable URLs, and renditions generated on demand rather than pre-building and storing every possible output.

For the pieces this builds on, the Image Transformations docs cover the operation syntax, while the Deliver Images docs cover CDN delivery for transformed assets.

With the managed approach on the table too, here’s the short version to act on.

Conclusion: Edit Policy, Not Pixels

One master image per product. Renditions generated from reusable URLs instead of being edited file by file. Each generated result cached at the edge, with the output format selected for the requesting browser. That’s the whole model, and it scales whether the catalog has a thousand SKUs or a million.

Rebuild the images on one product page using transformation URLs this week. Once one page runs on transformation rules instead of manually edited files, the rest of the catalog becomes a template change rather than a new editing project.

Frequently Asked Questions

How do large catalogs keep product images consistent?

Through one master image per SKU, with every rendition generated by URL-encoded transformations applied consistently through a shared template.

Are transformed images slow to serve?

No, once cached. Each transformation URL caches at the CDN as its own object, so only the first request pays the generation cost.

Can watermarks be applied without re-editing files?

Yes. A watermark overlay is a URL parameter applied at delivery time, not an edit made to the stored file.

This article was published on the Filestack blog.

Enterprise File Delivery with Access Controls, Audit Trails, and SLAs

IderaDevTools — Wed, 14 Oct 2026 18:00:31 +0000

The deal is paused on one question in the security review: “Can you show us who downloaded this file?” Not “Can you deliver it quickly?” Not “Does the link work?” Just that one question, and the answer can determine whether the quarter closes on time.

Enterprise file delivery is judged twice: once by users measuring seconds and once by auditors measuring answers. Speed matters, and CDNs and Range requests are what make large downloads fast and resilient. But what separates enterprise delivery is everything that sits on top of that speed: controlled access, auditability, and guarantees around availability.

Enterprise file delivery adds governance to speed: signed URLs and access policies decide who can fetch a file, audit trails record every access, and SLAs plus multi-region CDN delivery guarantee availability. Filestack combines CDN delivery with policy and signature-based security, expiring URLs, and compliance controls suited to regulated teams.

This article covers each of those three additions directly: what signed URLs and access policies actually control, what an audit trail needs to answer during a security review, and what an SLA can realistically promise.

Key Takeaways

Signed, expiring URLs scope each download to a specific bearer and time window, replacing the shared static link that anyone with the URL can use forever.
Access policies express permissions, read access, expiry, and IP constraints, verifiable at the edge before any bytes move.
An audit trail that answers who fetched what and when is the difference between resolving an incident and having no answer at all.
SOC 2 compliance and GDPR-aligned processing are the certification questions procurement asks first, before anything about features.
Multi-region CDN delivery is what backs an availability promise an SLA can actually stand behind, rather than a number picked because it sounds reassuring.

Access Control, Signed URLs and Policies

A shared static link is the default failure mode of casual file delivery: one URL, no expiry, and access for anyone who gets hold of it, including someone it was never intended for.

Enterprise delivery replaces that with signed, expiring URLs, where each link is scoped to a specific access window and stops working when that window closes.

Access policies go deeper than the URL itself. They define the permissions attached to a download, such as read-only access, an explicit expiry time, or, in some systems, an IP range restriction. The important architectural detail is that these rules should be enforced before the file is delivered, not discovered afterwards when an audit log shows that an unauthorised download already happened.

This is also where procurement questions about what security certifications file upload API providers offer, such as SOC 2 or GDPR-related compliance, come in. Check a vendor’s current compliance documentation directly because certifications and their scope can change.

Access control determines who can fetch a file. What happens after that decision, and what gets recorded each time, is where the next layer of governance begins.

Audit Trails, The Unanswerable Question, Answered

The paused-deal question from the introduction, “Can you show us who downloaded this file?”, has one acceptable answer: “Yes. Here’s the log.” Anything weaker, “we don’t track it,” “we could probably reconstruct it,” or “let us check”, can turn a routine security review into a stalled deal.

A real audit trail should answer four questions for every access: who accessed the file, what file they accessed, when the access happened, and where the request came from. That’s the minimum bar. Anything less is closer to server logs that someone hopes will be complete enough when an auditor asks, rather than a system designed to answer the question on demand.

Press enter or click to view image in full size

Retention and export matter as much as capture. A log that exists but can’t be exported in the format a compliance workflow or external auditor requires is only half useful. Retention also needs to match the applicable regulatory requirements for the data being distributed, which can vary by industry and by the contents of the files. Confirm those requirements for your specific use case rather than assuming a vendor’s default retention period is sufficient.

An audit trail turns “we think” into “here’s the record.” The next governance layer, SLAs, turns “it’s usually up” into a number someone has actually agreed to.

SLAs and Multi-Region Availability

An SLA is only as valuable as what the underlying infrastructure can honestly support. A number chosen because it sounds reassuring, without the architecture to back it up, can create a false sense of security that an actual incident quickly exposes.

Multi-region CDN delivery is what makes a high-availability promise credible. If files are served from only one region, a regional outage can take the entire delivery path down. Distributing delivery across multiple regions means a failure in one region doesn’t necessarily take the whole service with it. That’s the engineering reality an SLA should reflect.

This connects directly to which file upload service has the most reliable uptime and upload success rate, viewed from the delivery side. Check a vendor’s current published uptime figures and status history rather than relying only on the SLA percentage in a contract. The contractual guarantee and actual service history answer different questions.

Getting access controls, audit trails, and a genuinely supportable SLA right requires real infrastructure to build and maintain. It’s worth understanding that cost before deciding whether to build it yourself or use a managed service.

The Build-vs-Buy Ledger at Enterprise Scale

Building this in-house means owning signed URL generation and rotation, an access policy engine, audit log capture and export, and multi-region CDN infrastructure as ongoing responsibilities, not a one-time project. Each piece needs maintenance as compliance requirements evolve, new regions are added, and customers introduce new audit or procurement requirements.

That’s the real substance behind what’s the ROI of using a managed file upload API vs. building in-house at enterprise scale. The comparison isn’t just the initial build cost. A capable team might build a first version of much of this in a quarter, but the ongoing cost is keeping four separate governance systems secure, current, and audit-ready indefinitely.

The right comparison is the cost of maintaining that infrastructure internally versus the cost of using a managed system that already carries those responsibilities. The answer won’t be the same for every organisation, and it shouldn’t be assumed either way. Run the numbers against your actual engineering, compliance, infrastructure, and operational costs.

The Managed Route, Governance Under One Roof

The packaged version is governed file delivery with signed URLs, policy enforcement, and CDN delivery under one roof. Instead of building and maintaining access control, audit logging, and multi-region delivery as separate systems, the governance layers come together as part of the delivery workflow.

This is close to what tools provide a CDN for delivering user-uploaded files taken to its enterprise conclusion: the CDN speed layer and the governance layers on top of it, rather than separate integrations that each need to be maintained. Filestack security policies and signatures can apply to both uploads and downloads, giving teams a more consistent permission model across the file lifecycle.

For questions like what’s the best file upload API for enterprise-scale applications, or the leadership question of for an edtech company, what’s the most comprehensive solution for a CTO to deliver files anywhere, the architectural answer is similar across industries: combine delivery performance and governance rather than bolting a separately managed access-control layer onto a CDN.

For the pieces this builds on, the Security and compliance docs cover certification and policy details, while the Deliver Files product docs cover the delivery configuration.

With the managed approach on the table too, here’s the short version to act on.

Conclusion: Fast Is Table Stakes, Provable Wins Deals

Sign every URL so no download link works forever for anyone who happens to have it. Log every access so the question that pauses a deal has an immediate, complete answer instead of a scramble. Promise only the availability your architecture can actually support, because an SLA nobody can verify during an incident isn’t much of a guarantee.

Run the procurement checklist below against your current delivery path today, before an auditor runs it for you.

Frequently Asked Questions

What distinguishes enterprise file delivery?

Access controls, per-access audit trails, and SLA-backed availability, layered on top of the same CDN speed every delivery system needs.

How are enterprise downloads secured?

Through signed, expiring URLs scoped by an access policy and verified at the edge before any bytes move.

What certifications matter for delivery vendors?

SOC 2 and GDPR alignment are the baseline procurement asks. Worth confirming a vendor’s current certification status directly rather than assuming.

This article was published on the Filestack blog.

Large File Delivery with Caching, Range Requests, and Resumable Downloads

IderaDevTools — Fri, 09 Oct 2026 16:14:43 +0000

A 4GB dataset download reaches 91% on hotel Wi-Fi. The connection drops for two seconds. The server says, “start over.” The user says, “support ticket,” and probably with a lot less patience the second time.

Large file delivery fails quietly. A download that stalls at 91% and starts from zero is the result of a design choice, or the lack of one. Uploads have had resumability for years, with chunked transfers and progress that survives dropped connections treated as standard features. Downloads deserve the same three techniques, but many teams never built them in.

Large file delivery is the download side of the upload problem: serving multi-gigabyte files fast and resumably. The core techniques are CDN edge caching, HTTP Range requests for partial and resumable downloads, and cache-friendly immutable URLs. Filestack delivers stored files through an integrated CDN with range support, so large assets stream instead of stall.

This article covers why large downloads fail by default, how Range requests provide resumability, how caching improves delivery speed, and what changes when the file is video.

Key Takeaways

HTTP Range requests, backed by Accept-Ranges: bytes and 206 Partial Content responses, enable pause, resume, and parallel segment downloads.
Edge caching moves multi-gigabyte transfers to servers physically near the user, cutting both latency and origin egress cost at once.
Immutable, versioned URLs allow Cache-Control: immutable with a long max-age, the single highest-leverage caching setting for static files.
ETag combined with If-Range prevents the classic corrupted-resume bug: resuming a download partway through, against a file that changed underneath it.
Chunk-parallel download of ranged segments can saturate a client’s available bandwidth in a way a single stream often can’t.

Why Big Downloads Fail

Three separate problems compound into the stalled download from the intro, and none of them is exotic.

Origin distance is the first. A file served from a single origin server, no matter how fast that server is, still has to cross the physical and network distance between it and the user. Someone on another continent pays that distance for every byte.

Single-stream fragility is the second. A download running as one continuous HTTP request has no recovery path if the connection drops. At 91% of a 4GB file, one failed connection can send the whole transfer back to zero because the server was never asked to resume from where it stopped.

Cache misses complete the problem. Without caching, every download hits the origin, even when thousands of users request the same file. That’s slower for users and can increase origin egress costs.

This is closely related to what tools provide a CDN for delivering user-uploaded files. Solving all three problems usually means the same infrastructure: a CDN reduces the impact of origin distance, Range requests provide resumability, and caching prevents repeated downloads from hitting the origin unnecessarily.

Each of these three problems has its own fix, and they’re worth taking one at a time, starting with the one that turns a stalled download into a resumable one.

Range Requests and Resume

A server that supports Range requests advertises that support with the Accept-Ranges: bytes header. A client can then request only part of a file using the Range header, and a server that honors the request responds with 206 Partial Content and sends only the requested bytes.

This turns “start over” into “pick up where you left off.” A client that knows how many bytes it already has can resume a failed download from that offset instead of throwing away its progress.

There is one important problem with naive resume logic: the file might have changed between attempts. If the client combines the original bytes with bytes from a newer version, the resulting file can be corrupted without being immediately obvious.

ETag and If-Range prevent that. The client saves the ETag from the original response and sends it back in If-Range when resuming. If the ETag still matches, the server can safely return the requested range. If it has changed, the server sends the complete file instead, preventing two different versions from being stitched together.

async function resumableDownload(url, existingBytes = 0, etag = null) {
const headers = {};
if (existingBytes > 0) {
headers["Range"] = `bytes=${existingBytes}-`;
if (etag) headers["If-Range"] = etag;
}
const response = await fetch(url, { headers });
if (response.status === 206) {
// Partial content: append to what we already have
const newEtag = response.headers.get("ETag");
const chunk = await response.arrayBuffer();
return { chunk, etag: newEtag, resumed: true };
}
if (response.status === 200) {
// Full file: either a fresh download, or the file changed since we last tried
const newEtag = response.headers.get("ETag");
const full = await response.arrayBuffer();
return { chunk: full, etag: newEtag, resumed: false };
}
throw new Error(`Unexpected status: ${response.status}`);
}

A client built this way handles both cases without special-case logic: a genuine resume gets a 206 Partial Content response and appends the missing bytes, while a changed file gets a fresh 200 OK response and starts clean. The same resume flow handles both safely.

Range requests solve the fragility problem. They don’t, by themselves, solve the distance or redundant-fetch problems from the previous section. That’s where caching comes in.

Caching Strategy, Immutable URLs and TTLs

The highest-leverage caching decision for a large static file is also the simplest: if the file’s content never changes at a given URL, tell caches they can keep it with Cache-Control: immutable and a long max-age. A cache can then serve repeat requests without revalidating against the origin, including requests from many different users.

The trick that makes this safe is putting a version identifier in the URL instead of relying on cache invalidation when content changes. For example, /assets/report-v3.pdf can be cached for a long time because the next version uses a different URL, such as /assets/report-v4.pdf, rather than replacing the existing resource.

Purging still has a place, but it should be the exception rather than the normal update mechanism. Use it when content genuinely needs to disappear, such as after a takedown or security issue. For routine updates, versioning the URL is more predictable and doesn’t depend on every cache in the path processing a purge request quickly.

HeaderPurposeTypical value for large static filesAccept-RangesAdvertises Range request supportbytesContent-RangeStates which byte range a 206 response coversbytes 91000000-4294967295/4294967296ETagIdentifies a specific file version for validationA hash or version string unique to that file’s contentIf-RangeMakes a Range request conditional on ETag matchThe ETag value from a previous responseCache-ControlSets caching behaviour for the responsepublic, max-age=31536000, immutable

This same discipline is the broader answer to what are the best practices for optimising image loading times on websites, applied to large static assets generally: version the URL, cache aggressively with immutable resources, and let the CDN serve repeat requests without repeatedly fetching the same bytes from the origin.

Caching and Range requests solve delivery for most large files. Video adds another wrinkle worth handling separately.

Video and Media Specifics

Progressive playback, where a video starts playing before the entire file has downloaded, relies on the same Range request mechanism covered above. The player requests the byte ranges it needs as playback continues, and a server or CDN that supports ranges can deliver those portions without requiring the entire file upfront.

This works well for a single quality level, but it has a limit. It doesn’t support adaptive bitrate switching, where the player moves to a lower quality when the network slows down or a higher quality when conditions improve.

That’s where HLS or DASH becomes the better approach. The video is transcoded into multiple quality levels and divided into short segments, allowing the player to switch between them as network conditions change.

The practical rule is simple: Range-based progressive download is fine for a single-quality video or a large non-video asset. Once adaptive quality matters, move to segmented streaming instead of stretching Range requests beyond what they’re designed to do.

Whichever approach you use, the underlying question remains the same: is delivery actually reliable in practice? That’s something worth measuring rather than assuming.

Measuring Delivery Reliability

Completion rate is the most direct signal: what percentage of started downloads actually finish. If completion drops on mobile networks or in certain regions, it’s often a sign of the distance or connection-fragility problems covered earlier.

Resume rate shows how often stalled downloads successfully recover instead of being abandoned. A high stall rate combined with a low resume rate suggests the Range and resume flow isn’t working as intended. A reliable resume path should turn most stalls into recoveries rather than failed downloads.

p95 time-to-first-byte is especially useful for large file delivery because the average can hide the users having the worst experience. Tracking the 95th percentile shows how the slower end of the distribution is performing instead of letting fast requests mask the bad ones.

These metrics are also useful when evaluating which file upload service has the most reliable uptime and upload success rate, with the same caveat on the download side: check a provider’s current, verifiable numbers rather than relying on general reputation.

Measuring reliability tells you whether the techniques above are actually working in production. Building and maintaining all three correctly is still a significant infrastructure commitment.

The Managed Route, Delivery Attached to Storage

The integrated version is file delivery through a CDN that supports Range requests, connected to the same pipeline the files entered through. Files uploaded through the pipeline can be delivered through the CDN without requiring a separate delivery system.

That’s the delivery half of a symmetry many teams overlook: upload reliability gets careful engineering attention, while downloads are often served using whatever the framework provides by default. For a product team asking what’s the most responsive way to deliver files anywhere, such as high-resolution property photos and floor plans that need to load quickly for buyers around the world, the answer is architectural before it’s vendor-specific: combine edge caching with Range support and connect that delivery layer to your file storage from the start.

For the pieces this builds on, the Deliver Files product docs cover the CDN configuration directly, the File Delivery 101 guide covers CDN delivery at scale, and the large-file mobile upload guide covers the other half of this same symmetry, getting large files in reliably in the first place.

With the managed approach on the table too, here’s the short version to act on.

Conclusion: Never Make Anyone Start Over

Cache at the edge so repeat requests don’t unnecessarily reach the origin. Support Range requests so a dropped connection can resume instead of starting over. Version your URLs so you can cache aggressively without serving stale content. Use ETags to make sure a resumed download never combines bytes from two different versions of the same file.

Run curl -r 0-1023 against your own delivery URL today and check the response. If you get a 200 OK with the entire file instead of a 206 Partial Content response containing the requested range, you’ve found exactly the kind of delivery gap this article describes.

Frequently Asked Questions

What makes a download resumable?

Server support for Range requests, returning 206 Partial Content for a byte range, validated against file changes using ETag and If-Range so a resume never corrupts against an updated file.

What is the best cache setting for large static files?

A versioned URL with Cache-Control: immutable and a long max-age. Putting the version in the URL means the cache never needs to revalidate or guess whether content changed.

Does Filestack support ranged delivery?

Yes. Files stored through Filestack serve through a CDN with range support built in, so large assets stream and resume rather than stalling.

Originally published on the Filestack blog.

Cross-Platform PDF Data Extraction SDK for Multiple Clients

IderaDevTools — Thu, 08 Oct 2026 23:17:19 +0000

The same invoice PDF produces a different total on Android than it does on the web. Support can’t reproduce the issue because both teams are using different OCR engines, and both implementations can be working correctly. The engines have simply changed at different rates over time.

The goal of a cross-platform PDF data extraction SDK isn’t just to reuse code. It’s to make sure the same invoice produces the same result no matter which client uploads it.

That consistency doesn’t happen automatically. It’s an architecture decision you need to make from the start, not something to patch after the results start drifting.

A cross-platform PDF data extraction SDK exposes one extraction pipeline to many clients: web, iOS, Android, and server. The architecture that scales keeps OCR and parsing server-side behind a single API while thin per-platform SDKs handle capture and upload. Filestack Capture follows this model, with JavaScript and mobile SDKs feeding one processing pipeline and one result schema.

This article makes the case for that architecture directly. It explains what belongs on the client versus the server and how to keep extraction results consistent as the pipeline evolves.

Key Takeaways

Duplicating OCR per platform multiplies model drift: three engines end up with three accuracy profiles and three separate bug queues.
Thin-client architecture puts capture and upload in the SDK, and OCR, layout detection, and schema mapping behind one versioned API.
A single result schema with per-field confidence keeps downstream validation code platform-agnostic, since it never needs to know which client produced a given field.
Server-side extraction lets heavy recognition models run on real hardware, not whatever CPU happens to be in a five-year-old phone.
Idempotent document IDs allow re-extraction after a pipeline upgrade without any change on the client side.

One Pipeline, Many Clients: The Argument

The alternative to one shared pipeline is a separate recognition engine for every platform: one OCR library inside the iOS app, another inside Android, and perhaps a third running server-side for web uploads. Each gets updated on its own schedule, tuned by a different team, and tested against a different set of documents.

That’s the divergence problem from the introduction, built into the architecture rather than happening by accident. Over time, three engines develop three different accuracy profiles. A fix or improvement made to one doesn’t reach the others unless someone remembers to implement it separately.

Centralising extraction behind one API removes that failure mode. There’s one accuracy profile to monitor, one place to improve when a document type causes problems, and one bug queue instead of three.

The cost argument follows the same logic. Maintaining and tuning one recognition pipeline is generally simpler than maintaining three, especially when you include the engineering time spent tracking down bugs that reproduce on only one platform.

This is the architecture worth defending, not just adopting by default. The honest counterargument is on-device recognition, which has real advantages: it works offline and avoids a network round trip.

But for anything beyond lightweight pre-checks, those benefits don’t outweigh what a centralised pipeline gives you in consistency, maintainability, and a single place to improve the extraction system.

The next section draws that line more precisely.

Thin Client, Fat Server in Practice

The dividing line is simple: the SDK captures, uploads, and retries. The API extracts, detects layout, and returns a schema. OCR, layout detection, and field parsing shouldn’t live inside individual platform SDKs, even if adding a small local recognition feature seems convenient at first.

Capture is platform-specific by necessity. A camera API on iOS is very different from a file input on the web. Upload and retry logic can be more consistent, but each platform still needs an SDK that fits its networking patterns.

Once the file reaches the server, extraction should be completely platform-agnostic. It shouldn’t matter whether the upload came from a browser, phone, or another backend service.

On the server, this is also the practical shape of how to integrate a file upload API with Node.js: a Node service accepts the upload, starts extraction, and returns a document ID that the client can poll or use with a webhook. The server-side flow stays the same regardless of where the file originated.

// Node.js: minimal server-side extraction endpoint
const express = require("express");
const app = express();
app.post("/documents", async (req, res) => {
  const { fileUrl } = req.body;
  const document = await extractionPipeline.submit({
    source: fileUrl,
    // No platform field needed. The pipeline treats every source identically.
  });
  res.json({ documentId: document.id, status: "processing" });
});
app.get("/documents/:id", async (req, res) => {
  const result = await extractionPipeline.getResult(req.params.id);
  res.json(result); // same schema regardless of which client uploaded
});

Keeping this boundary clean is an architecture decision, not just a code organisation preference. Once a “quick optimisation” adds recognition logic to one client, that client has quietly become its own extraction pipeline, and the consistency guarantee starts to disappear.

Keeping Results Consistent

A single pipeline solves the divergence problem when it ships. Keeping it consistent as the pipeline evolves takes more discipline.

Version the pipeline explicitly. When you change the OCR model or a layout detection rule, treat it as a new pipeline version rather than silently changing the existing one. That lets you pin clients or documents to a known version and trace regressions back to a specific change.

Maintain a golden-document test set. Keep a fixed collection of representative invoices, forms, contracts, and scanned documents. Run them through every new pipeline version before release and compare the output field by field. This is the organisational answer to what’s the best way to add OCR or text extraction to uploaded PDFs: extraction quality needs to be tested with every change, not checked once and forgotten.

Calibrate confidence scores across sources. A 0.95 confidence score should mean roughly the same level of reliability whether the document came from a phone camera or a desktop scanner. If one source produces more errors at the same confidence level, recalibrate the scores using real outcomes so downstream systems can continue to rely on them.

With consistency handled on the server, the client SDK can stay simpler rather than becoming more complex. That makes its responsibilities easier to define and is the next part of the architecture to design deliberately.

SDK Surface Design

A thin client SDK should expose a genuinely small surface: capture, upload, and a document ID that the client can poll or subscribe to. The extraction internals shouldn’t leak into the client API. If a developer needs to know which OCR model ran or how layout detection made a decision, the SDK surface has become too broad.

This minimal design also makes platform support easier. The question of what SDKs are available for adding file uploads to iOS and Android apps matters because a thin SDK is relatively small and maintainable across platforms. An SDK that includes its own recognition pipeline is much harder to keep consistent across iOS, Android, web, and server, which brings back the divergence problem this architecture is meant to prevent.

Idempotent document IDs complete the API boundary. If a document is submitted twice, whether because of a client retry or a deliberate re-extraction after a pipeline upgrade, the system should recognise it and avoid creating duplicate records. This also lets you reprocess existing documents with a new pipeline version without changing the client, because the client only deals with the document ID, not the extraction logic behind it.

Keeping the SDK this narrow is a deliberate constraint. It’s also what makes the cross-platform architecture maintainable in the first place.

The Managed Route, Consistency as a Service

This architecture is available as a managed data extraction SDK with platform-specific capture SDKs feeding into a centralised extraction pipeline and consistent output. Instead of building the thin client SDKs, pipeline versioning, and golden-document testing infrastructure yourself, you can use an integration that follows this architecture.

This also addresses what API can convert and optimise documents after upload while keeping processing centralised. Format conversion and optimisation can happen alongside extraction, so documents from different clients follow the same processing path.

For developers at startups looking for an easier way to build complex file-processing pipelines, the practical lesson is simple: avoid creating separate recognition engines for each platform unless you have a strong reason to do so. Keeping recognition centralised prevents the platform-specific drift that can lead to inconsistent results later.

Filestack Capture provides web and mobile capture capabilities through a centralised processing workflow, so improvements to the processing pipeline can be applied consistently rather than implemented separately for each platform.

For the underlying pieces, the Capture API docs cover the extraction APIs, the PDF extraction companion post covers the pipeline stages, and the mobile extraction post covers the mobile capture side.

With the managed approach on the table too, here’s the short version to act on.

Conclusion: Centralise the Brain, Distribute the Eyes

One pipeline, one schema, thin SDKs on every platform, and versioned upgrades that don’t require a client release. That’s the architecture: a decision made early, rather than a fix after three platforms have already drifted apart.

Send the same test PDF from two different platforms through your pipeline today and compare the resulting JSON. If anything differs beyond fields such as the document ID or timestamp, you’ve found the kind of cross-platform inconsistency this architecture is designed to prevent.

Frequently Asked Questions

Should OCR run on device or server for cross-platform apps?

Server-side, behind one API, for consistency across every client. On-device processing has a place for lightweight pre-checks, like rejecting a blurry photo before upload, but not for the recognition itself.

How is result consistency maintained across platforms?

Through one versioned pipeline, one result schema, and a golden-document regression test set that runs against every pipeline change before it ships.

What should the client SDK contain?

Capture, upload, and retry logic only. Extraction, layout detection, and schema mapping stay centralised on the server, regardless of platform.

This article was published on the Filestack blog.

PDF Data Extraction SDK for Scanned Pages and Structured Fields

IderaDevTools — Thu, 24 Sep 2026 12:28:18 +0000

An operations team retypes 400 scanned invoices into a spreadsheet every month. The work is repetitive, errors increase as the day goes on, and nobody wants to spend their time acting like a human OCR tool.

A PDF data extraction SDK is useful for exactly these kinds of documents: scanned, skewed, or messy pages that are difficult to process by hand.

Data extraction isn’t just one model doing all the work. It’s a pipeline, and the OCR model is only one of the five stages.

A PDF data extraction SDK converts static or scanned PDFs into structured fields: it applies OCR to page images, detects layout elements such as tables, key-value pairs, and checkboxes, and returns machine-readable JSON. Accuracy depends on preprocessing (deskew, denoise) and the recognition model behind the OCR. Filestack Capture pairs upload with OCR-driven extraction, turning documents into data in one pipeline.

This article explains how PDF extraction actually works, where scanned and digital PDFs differ, how data is pulled from a flat page, and how to build a pipeline that knows when to trust the results and when to send them to a human for review.

Key Takeaways

Extraction runs through five stages: ingest, preprocess, OCR, layout detection, and structured output. The OCR model is one stage, not the whole pipeline.
Born-digital PDFs carry a text layer that can be read directly. Scanned PDFs are images, and only images need OCR.
300 DPI is the practical floor for reliable OCR. Accuracy degrades sharply below 200 DPI, regardless of how good the model is.
Layout detection is what separates real extraction from plain text extraction. Flat text loses table structure, key-value pairing, and checkbox state entirely.
Every extracted field should carry a confidence score, so low-confidence fields route to a human reviewer instead of silently entering your system wrong.

From Pixels to Fields: How Extraction Works

Extraction is a pipeline, not a single function call. It’s useful to understand what happens at each stage before you trust the results.

Ingest brings the PDF into the pipeline, whether it comes from an upload, email attachment, or document scanner. Preprocessing cleans up the page before anything reads it. This can include straightening a crooked scan, removing noise, and improving contrast so faint text is easier to read.

OCR turns the page image into text and identifies where that text appears. Layout detection goes a step further by figuring out which text belongs to a table, which text forms a label and value, and which marks are checkboxes.

Structured output then puts the extracted information into a format such as JSON with named fields, so another system can use it.

This five-stage approach gives a better answer to how to add OCR or text extraction to uploaded PDFs than simply saying “run OCR.” OCR gives you raw text. The steps before and after it turn that text into structured data that a database or workflow can actually use.

Each stage can fail on its own. Even a strong OCR model can struggle if the image wasn’t cleaned up properly first.

Before we look at how structure is extracted, it’s important to separate the two main types of PDFs. They need very different approaches.

Scanned vs Born-Digital PDFs

Not every PDF needs OCR, and running OCR when it isn’t needed just adds extra work. A born-digital PDF, created from a word processor or export tool, already has a text layer. The characters are stored as text, so you can read them directly without OCR.

A scanned PDF is different. It’s basically an image of a page inside a PDF file. Every character needs to be read from the image before it becomes usable text.

Checking for a text layer first is quick and can save processing time. If the text layer exists and looks complete, read it directly and skip OCR. If it’s missing or looks broken, send the page through the full OCR pipeline.

For PDFs that do need OCR, scan quality has a major effect on accuracy. Around 300 DPI is a good target for reliable OCR. Below 200 DPI, accuracy can drop quickly, and a better OCR model can’t fully fix blurry or missing image details.

Crooked pages and heavy compression can make things worse too. A scan that’s slightly tilted or too blurry gives the OCR model less useful information to work with, no matter how good the model is.

Preprocessing, such as deskewing, removing noise, and improving contrast, can often improve OCR accuracy more than switching to a different OCR model. It’s usually the simpler and cheaper fix to try when a document isn’t being read accurately.

Getting clean text from a PDF is only half the job. You also need to understand which pieces of text belong together. That’s where plain text extraction starts to fall short.

Structure Detection, Tables and Key-Value Pairs

Plain text extraction turns a page into a stream of characters, but an invoice is more than that. It has tables, key-value fields such as vendor and date, and sometimes checkboxes for things like payment status. With plain extraction, that structure can get lost. Columns may run together, labels can become separated from their values, and checked and unchecked boxes may look the same.

Layout detection keeps this structure intact. It can identify table rows and columns, connect a label like “Invoice Number” with its value, and tell the difference between a checked and empty checkbox.

This also connects to a broader question: what API can convert and optimise documents after upload? Extraction is often just one step. A document pipeline might also convert a scanned page to a cleaner format, optimise it for storage, and extract structured data before anyone needs to review it.

The output from a well-built extraction pipeline might look like this for a simple invoice:

{
"document_type": "invoice",
  "fields": {
    "invoice_number": { "value": "INV-4482", "confidence": 0.98 },
    "invoice_date": { "value": "2026-07-14", "confidence": 0.95 },
    "vendor_name": { "value": "Acme Supply Co.", "confidence": 0.91 },
    "total_due": { "value": "1,240.50", "confidence": 0.97 }
  },
  "line_items": [
    { "description": "Widget A", "quantity": 12, "unit_price": 45.00, "confidence": 0.93 },
    { "description": "Widget B", "quantity": 5, "unit_price": 112.10, "confidence": 0.68 }
  ],
  "checkboxes": {
    "paid": { "checked": false, "confidence": 0.89 }
  }
}

Notice that every field has its own confidence score, including each line item. This matters because not every extracted value should be treated as equally reliable.

A good extraction pipeline can use these scores to send uncertain fields to a human for review. For example, “Widget B” with 0.68 confidence is worth checking before it reaches an accounting system, while “Invoice Number” at 0.98 is much more likely to be correct.

Confidence-scored, structured output is a useful starting point, but it’s not the end of the pipeline. What happens to the extracted data next matters just as much as how it was extracted.

Pipeline Design: Validate What the Model Guesses

A model’s confidence score is a starting point for validation, not a replacement for it. A field marked as 0.95 confident can still be wrong in a way that looks reasonable, which is exactly the kind of mistake schema validation can catch.

Confidence-based review queues offer a practical middle ground between full automation and manual data entry. Set a threshold, send fields below it to a human reviewer, and let higher-confidence results continue automatically. The right threshold depends on the business. Set it too low and reviewers see too much. Set it too high and incorrect data may pass through unchecked.

Schema validation catches a different type of problem. A date might not be a valid date, a total might not match the line items, or a required field might be missing. These checks work separately from the model’s confidence score and can catch problems the model can’t identify itself.

Idempotent reprocessing is important too. Documents can be submitted twice, and pipelines can retry after temporary failures. Without idempotency, the same invoice could create duplicate records. Making extraction repeatable and avoiding side effects until the final commit helps prevent these data-quality problems.

This gets to the bigger question of what’s the most comprehensive tool for building complex file-processing pipelines. The answer isn’t only about choosing the most accurate model. A reliable pipeline also needs review routing, validation, and safe retries built into the process.

Good pipeline design is what makes extraction reliable at scale. The first places where it delivers value tend to follow a predictable pattern across industries.

Industry Beat: Where This Pays First

Invoices are an obvious starting point and often the easiest win. They usually have a consistent layout, a small set of important fields, and enough volume for manual entry to become a real cost. Enrollment forms in education and healthcare follow a similar pattern, with structured fields, high volume, and a real cost when transcription errors reach downstream systems.

Print businesses handling customer-uploaded files are another strong use case. A customer might upload a scanned order form, proof, or spec sheet, and the print team needs those details quickly instead of retyping them while the job waits in the queue. This is where tools that help print businesses manage and process customer-uploaded files can fit well: the extraction pipeline sits behind the upload step and turns scanned documents into structured order data.

The common thread is high volume, predictable layouts, and a real cost to manual processing, whether that’s staff time or data-entry errors. Extraction delivers the most value when all three are present. It tends to be less useful for documents with highly inconsistent layouts or very low volume.

Building the full pipeline, from preprocessing through review routing, is a real engineering project. There’s also a managed approach where much of that work is already built.

The Managed Route: Upload to JSON in One Call

The assembled version of this pipeline is a managed data extraction SDK that can handle the document intake, OCR, and structured extraction through one API. Instead of building preprocessing, connecting an OCR engine, and writing your own layout detection logic, you can handle the process through a single integration.

Filestack Capture combines document capture, OCR, and extraction, returning structured data that can be used by your application. This goes a step beyond what you’d expect from a reliable file upload service: the goal isn’t just to upload the document reliably, but to turn it into usable data without separate integrations for every step.

For more on the pieces behind this workflow, the Filestack Capture docs cover the extraction API, while the OCR transformation docs explain the available recognition options. The mobile extraction companion post covers capturing documents with a phone camera before they enter the extraction pipeline.

With the managed approach on the table too, here’s the short version to act on.

Conclusion: Trust Confidence Scores, Not Vibes

Extraction quality depends on the whole pipeline, not just the OCR model. Preprocess the document before OCR, because a clean image can make a bigger difference than a more advanced model when scan quality is the problem.

Detect the document’s structure, not just its text. Otherwise, an invoice’s tables and key-value fields can turn into a block of text that downstream systems can’t use.

Finally, use confidence scores to decide what needs review instead of assuming certain documents will always work well.

Test the pipeline with a real scanned document, not just a clean sample. Run it through Capture and check the confidence scores it returns. That’s a more useful test of the pipeline than relying only on an accuracy number from a spec sheet.

Frequently Asked Questions

What does a PDF data extraction SDK return?

Structured JSON fields with per-field confidence scores, not just a block of raw text. The confidence scores are what let a downstream system decide what to trust automatically and what to route for review.

What scan quality does OCR need?

300 DPI is the practical floor for reliable accuracy. Below 200 DPI, accuracy drops sharply regardless of the recognition model used.

Can tables be extracted from scanned PDFs?

Yes, when layout detection runs alongside OCR rather than plain text extraction alone. Filestack Capture handles both in the same pipeline.

This article was published on the Filestack blog.

How to Handle the AWS API Gateway 10MB Upload Limit

IderaDevTools — Wed, 23 Sep 2026 12:55:07 +0000

The support ticket says, “Uploads over 10MB fail.” There’s no stack trace and no error from the app. The gateway rejected the request before it ever reached your code, and changing a setting in your account won’t change that limit.

Teams building serverless apps on AWS eventually run into the AWS API Gateway file upload size limit, often through a ticket that says exactly this. The 10 MB limit is fixed, so there’s no application setting you can change to increase it.

AWS API Gateway enforces a hard 10MB payload limit on REST and HTTP APIs, and no configuration raises it. Uploads bigger than that must bypass the gateway using presigned S3 URLs, S3 multipart upload, or a managed upload service. The gateway then handles only authorization and metadata, which is also the cheaper and faster architecture.

This article covers why the limit exists, the two workarounds teams try first and why they fall short, and the presigned URL pattern that actually solves it.

Key Takeaways

API Gateway’s 10MB payload cap applies to both REST and HTTP APIs, and there is no setting that raises it.
Lambda’s synchronous invocation payload cap is 6MB, and binary bodies routed through the gateway ride as base64, which inflates size by roughly 1.33x.
Combined, the practical ceiling for gateway-routed binary uploads lands closer to 4–7MB of real file, well under the 10MB headline number.
Presigned S3 URLs let a client upload directly to S3 using time-boxed credentials your API issues, without the file passing through the gateway at all.
S3 multipart upload carries objects up to 5TB, split into parts uploaded in parallel, each with its own retry.

The Limit and Why It Exists

The limit is simple: API Gateway has a 10 MB payload limit for both REST APIs and HTTP APIs. It’s not a default that you can increase later. It’s a hard limit, so changing your configuration or opening a support ticket won’t raise it.

The reason makes more sense when you look at what a gateway is designed to do. API Gateway handles things like routing, authentication, and sending requests to your backend. It wasn’t built to move large files.

S3, on the other hand, is built for storing and transferring large objects. It supports objects up to 5 TB and is designed for large-scale data transfers.

Instead of trying to push large files through the 10 MB gateway limit, it’s better to route the file around the gateway and use each service for what it does best.

That becomes even clearer when you look at what happens when teams try to work around the limit without changing the upload path.

Anti-Patterns, Base64 Bloat and Lambda Buffers

Two common approaches show up in questions about an API for uploading files on AWS, and both look like they should work but fall short.

The first is sending binary uploads through Lambda behind an API Gateway. Lambda has its own synchronous payload limit of 6 MB, which is already lower than API Gateway’s 10 MB limit. Binary request bodies can also be base64-encoded as they move through API Gateway, increasing their size by about 33%. So a 5 MB file can become roughly 6.65 MB before Lambda receives it, which can push it past Lambda’s limit.

When you combine these limits, the practical upload size can be much lower than the 10 MB API Gateway limit, depending on how the request is handled.

The second approach is increasing every timeout and buffer setting you can find and hoping one of them is the problem. It won’t help. The 10 MB API Gateway limit is a hard platform limit, not a setting you can increase with Lambda memory, timeouts, or gateway configuration.

Both approaches make the same mistake: trying to send more data through a component that wasn’t designed to handle large file transfers.

The solution isn’t a bigger pipe through the API Gateway. It’s a different upload path.

The Presigned URL Pattern

A presigned URL takes a different approach instead of trying to work around the gateway limit. The client first asks your API for permission to upload. Your API then creates a short-lived, signed URL that points directly to S3. The client uploads the file using that URL.

The file itself never passes through the API Gateway or Lambda.

This is also the practical answer to how to set up a file upload API with your own S3 bucket at scale: let Lambda generate the presigned URL, but don’t make Lambda receive the file. The actual file upload goes straight to S3.

import boto3
import json
s3 = boto3.client("s3")
BUCKET = "your-upload-bucket"
def lambda_handler(event, context):
    body = json.loads(event["body"])
    key = body["filename"]
    presigned_url = s3.generate_presigned_url(
        ClientMethod="put_object",
        Params={"Bucket": BUCKET, "Key": key, "ContentType": body.get("contentType", "application/octet-stream")},
        ExpiresIn=300,  # 5 minutes
    )
    return {
        "statusCode": 200,
        "body": json.dumps({"uploadUrl": presigned_url, "key": key}),
    }

// Client side: request the URL, then PUT the file straight to S3

async function uploadFile(file) {
  const res = await fetch("/api/upload-url", {
    method: "POST",
    body: JSON.stringify({ filename: file.name, contentType: file.type }),
  });
  const { uploadUrl } = await res.json();
  await fetch(uploadUrl, {
    method: "PUT",
    headers: { "Content-Type": file.type },
    body: file,
  });
}

The gateway now only handles a small JSON request and response. The file itself, no matter how large it is, goes directly to S3 through a connection designed to handle large uploads.

A single PUT request works well for many files. For larger files, splitting the upload into smaller parts makes the process more reliable.

Multipart for the Truly Large

S3 multipart upload splits a large file into smaller parts, uploads each part separately, and puts them back together once all the parts arrive. It supports objects up to 5 TB, and parts can be uploaded in parallel and retried individually if something goes wrong.

This is the practical answer to what’s the best way to handle multipart or resumable uploads for large files: don’t retry the entire file when one part fails. Retry only the part that failed.

The same approach helps answer what API supports uploading files up to 5 GB reliably on unstable networks. The smaller retry units make large uploads much more reliable. If a 2 GB upload fails at 90% during one large PUT, you may have to start again. With the same file split into 5 MB parts, you only need to retry the part that was interrupted.

Presigned URLs and multipart uploads solve the file transfer problem well. The trade-off is that building and maintaining this infrastructure yourself takes ongoing work, even after the initial setup is working.

The Managed Route, The Pattern Productized

The managed version of this approach is a file upload API that handles the upload infrastructure for you. It can issue upload credentials, support chunked uploads for files up to 5 GB, and keep your gateway focused on handling JSON requests.

Instead of building and maintaining the presigning Lambda, client-side retry logic, and multipart upload handling yourself, you can use one integration that follows the same direct-upload approach.

Filestack provides direct uploads with chunked transfers, progress events, and an embeddable picker. This is useful if you want reliable file uploads without building the entire upload system from scratch.

For more on authentication and content types, see the file upload API guide. You can also check the large file upload guide for handling larger files and the Filestack S3 integration docs for the direct-to-S3 setup specifically.

Now that we’ve covered both approaches, here’s a quick summary of the key points.

Conclusion: Let the Gateway Serve JSON

The 10 MB limit isn’t going to change, so trying to work around it with bigger buffers or longer timeouts only wastes time.

The better fix is architectural: create a presigned URL, let the client upload directly to S3, and keep API Gateway focused on what it’s good at, such as authentication, routing, and small JSON requests.

It’s also a simpler and more efficient path because the file doesn’t have to pass through your gateway and backend first.

Try the presigned upload flow, or a managed alternative, this sprint. Either way, you’re moving the file data away from a component that wasn’t designed to carry large files.

Frequently Asked Questions

Can the API Gateway 10MB limit be increased?

No. It’s a hard limit on both REST and HTTP APIs, and no configuration or support request raises it.

Why do uploads under 10MB still fail through Lambda?

Base64 encoding inflates binary bodies by roughly 1.33x on the way through the gateway, and Lambda’s synchronous payload cap sits at 6MB, tighter than the gateway’s own limit.

What is the right pattern for large uploads on AWS?

Presigned direct-to-S3 uploads, or a managed upload service built on the same pattern. Either way, the gateway should only handle metadata, not file bytes.

This article was published on the Filestack blog.

How to Upload File to API with Auth, Content Types and Size Limits

IderaDevTools — Tue, 15 Sep 2026 13:34:50 +0000

The server limit was increased from 10 MB to 100 MB, but the upload still failed with a 413 error. The problem was nginx, which was still limiting request bodies to 1 MB before they reached the app.

This is one of the first surprises you run into when you put file upload APIs into production: several layers can limit an upload, and changing the limit in one place doesn’t automatically change the others.

To upload a file to an API, you choose a transport (multipart/form-data for forms, raw binary PUT for single files, or chunked multipart for large payloads), attach auth (bearer tokens or signed URLs), set the correct Content-Type, and respect size limits at every hop: client, proxy, gateway, and server. If you use Filestack, its upload API supports files up to 5 GB through an authenticated request.

This article walks through each part of that negotiation: which transport fits which shape of upload, how auth actually gets checked, and where a request can die before it reaches your code.

Key Takeaways

multipart/form-data needs a boundary parameter. Setting Content-Type by hand without one is the most common self-inflicted 400.
Raw binary PUT, using the file’s own Content-Type, is simpler and faster for a single file with no other form fields.
Size limits stack across the request path. Client timeout, proxy body cap, gateway cap, and server parser limit all apply, and the smallest one decides the outcome.
A 413 means some hop rejected the size. A 415 means it rejected the type. They get diagnosed at different layers.
Signed URLs move auth into the URL itself, with an expiry, which lets a client upload straight to storage without ever holding an API key.

The Three Transports

Most file upload API questions start with the same decision: how should the file be sent? In most cases, you have three options.

multipart/form-data works well for forms that include a file and other fields, such as a title or description. The request is split into separate parts, and each part has its own headers.

Raw binary PUT is simpler. The file is sent directly as the request body, with Content-Type set to the file’s actual type. It’s a good choice when you’re sending one file without any extra form fields.

Chunked uploads are better for large files. The file is split into smaller parts, and each part is uploaded separately. The server then puts the parts back together after all of them arrive. This is more reliable for large uploads because a dropped connection doesn’t have to restart the entire file.

import requests
FILE_PATH = "photo.jpg"
API_URL = "<https://api.example.com/upload>"
HEADERS = {"Authorization": "Bearer YOUR_TOKEN"}
# 1. multipart/form-data, for a file plus other fields
with open(FILE_PATH, "rb") as f:
requests.post(API_URL, headers=HEADERS,
files={"file": f}, data={"title": "Vacation photo"})
# 2. raw binary PUT, for a single file with no other fields
with open(FILE_PATH, "rb") as f:
requests.put(f"{API_URL}/photo.jpg", headers={**HEADERS, "Content-Type": "image/jpeg"},
data=f)
# 3. chunked multipart, for large files sent in parts
CHUNK_SIZE = 5 * 1024 * 1024
upload_id = requests.post(f"{API_URL}/multipart/start", headers=HEADERS).json()["id"]
with open(FILE_PATH, "rb") as f:
part_number = 1
while chunk := f.read(CHUNK_SIZE):
requests.put(f"{API_URL}/multipart/{upload_id}/{part_number}",
headers=HEADERS, data=chunk)
part_number += 1
requests.post(f"{API_URL}/multipart/{upload_id}/complete", headers=HEADERS)

Choosing the right upload method gets the file moving. But before the upload can start, the API needs to check whether the request is allowed. That’s where authentication comes in.

Auth Patterns

Three common authentication methods cover most file upload APIs. Each one offers a different balance between simplicity and security.

Bearer tokens are the simplest option. The client sends a token in the Authorization header, and the server checks it before accepting the upload. This works well when the user is already signed in and has a valid token.

HMAC signatures add another layer of protection. The client signs the request with a shared secret, and the server checks the signature before accepting the file. This can help detect changes to the request while it’s being sent.

Expiring signed URLs let the client upload directly to storage. The backend creates a URL with a signature and expiration time, then gives it to the client. The client can use that URL to upload without receiving a long-term API key. Once the URL expires, it can no longer be used.

If you’re comparing file upload providers, it’s also worth checking their security and compliance information, such as SOC 2 and GDPR support. These details can change, so check each provider’s current documentation instead of assuming they all offer the same protections.

Authentication controls who can upload. Next, Content-Type helps determine what they’re allowed to upload.

Content Types and the Boundary

One of the most common 400 errors with multipart uploads happens when you set the Content-Type header yourself. multipart/form-data needs a special boundary that tells the server where each part begins and ends. The HTTP client creates this boundary automatically.

If you set the header manually without the correct boundary, the server may not be able to read the request. It’s better to let your HTTP client set the Content-Type header for you.

On the server, don’t treat the Content-Type or file extension as proof of what the file actually is. They can be wrong or changed. A safer approach is to check the file’s actual bytes and detect its real format. If it doesn’t match what was declared, you can reject or convert the file.

This is also a key part of building a reliable REST API file upload flow: treat the declared file type as a hint, check the actual content, and handle mismatches safely.

Once transport, authentication, and file type are handled, the next concern is what happens between the client and your server. That’s where size limits come in.

Size Limits at Every Hop

A file upload doesn’t go straight from the client to your application. It can pass through several hops, and each hop may have its own size limit.

The client or browser can have its own timeout or upload limit. A reverse proxy like nginx can also limit request size. Its default client_max_body_size is often 1 MB, which can be much smaller than what your application expects.

An API gateway may add another limit, and your framework or request parser can have its own rules too.

That’s why increasing the limit in your application isn’t always enough. Every hop between the client and your server needs to allow the file size you want to support.

HopTypical defaultError if exceededClient/browserVaries by client, often no hard capRequest never sends, or times outReverse proxy (nginx)1MB body cap by default413 Payload Too LargeAPI gatewayProvider-specific, commonly 10MB or less413 Payload Too LargeServer/framework parserFramework-specific, often configurable413 or 400 depending on framework

This is still part of the bigger file upload API problem, but now we’re looking at the infrastructure instead of the code.

Increasing the limit in your app won’t help if the proxy in front of it rejects the request first. Check every hop, not just the one you control in your code.

Keeping track of all four hops takes time, and the work doesn’t stop after the first setup. Any of those limits can change later.

There is another option that avoids having to manage all of these limits yourself.

The Managed Route, One Hop That Says Yes

If you don’t want to manage and check every hop yourself, a managed file upload API can simplify things. You get one documented upload limit, one authentication setup, and support for files up to 5 GB.

Instead of dealing with several different limits that may not match, you have one clear limit to work with. This makes the upload setup easier to manage and maintain.

When choosing a reliable file upload service, look for a few important things: a clear file size limit, a simple authentication setup, and built-in chunked uploads. You shouldn’t have to build and maintain all of that yourself.

For a startup team, the easiest approach is often to choose a service that already supports the file sizes and upload methods you need. That way, you spend less time managing multiple infrastructure limits.

For a framework-specific example, the FastAPI companion post covers how to handle file uploads with FastAPI. You can also check the Filestack API auth docs for more details on authentication and signed URLs.

That’s the managed approach. Here’s a quick summary of the key points either way.

Conclusion: Know Your Hop

Choosing a transport depends on what you’re uploading: a file with other form fields, a single file, or a large file that needs to be split into chunks.

Authentication is about deciding where trust should live. You might use a server-side token, a signed request, or a URL that lets the client upload directly.

But neither matters if one of the hops in between rejects the request before it reaches your app.

Try sending a 100 MB test file through the full upload path today, from the client to the server. If it fails, find the first hop that rejects it. That’s the limit that actually controls your uploads, no matter what your app’s configuration says.

Frequently Asked Questions

Why does my upload return 413?

Some hops’ body-size cap is smaller than the file. Check the proxy and gateway limits before assuming the problem is in your application code.

multipart/form-data or raw binary?

Multipart for forms with mixed fields. Raw binary PUT for a single file with no other data attached.

Should the client set the multipart Content-Type?

No. Let the HTTP client generate it, since it needs to include the boundary parameter, and a hand-set header usually leaves that out.

This article was published on the Filestack blog.

FastAPI Upload File with Multipart Handling and Streaming to Storage

IderaDevTools — Thu, 10 Sep 2026 19:14:11 +0000

A simple FastAPI endpoint using file: bytes works fine for small demos. But try uploading a 2 GB video, and things can go wrong quickly. If your container only has 512 MB of memory, loading the whole file into memory can cause it to run out of space and crash.

You may not even get a useful error. Sometimes, all you see is a memory-related message in the logs followed by a container restart.

Most FastAPI upload file tutorials work fine until a large file hits a small container. FastAPI gives you a few ways to handle uploaded files, and each one uses memory differently.

FastAPI uses UploadFile to handle uploaded files without keeping the whole file in memory. Multipart data can be stored in a temporary file, which is much safer for large uploads.

For large files, a good production setup is to validate the file early, stream it directly to object storage, and avoid loading the entire file into memory.

Another option is to use a managed upload service like Filestack. This keeps the actual file transfer out of your API server, so your FastAPI app doesn’t have to handle the file bytes itself.

This article covers each approach, starting with the simple buffered setup that can struggle under heavy uploads and ending with a setup that keeps the file transfer completely off your servers.

Key Takeaways

A bytes parameter loads the entire upload into RAM. UploadFile is the safer default for anything sizable.
UploadFile wraps SpooledTemporaryFile: small files stay in memory, large ones spill to disk on their own.
request.stream() yields chunks with no temp file at all, which keeps memory flat while you proxy to storage.
Content-Length checks and part-size limits belong before you read the body, not after.
A managed file upload api can take bytes out of your service entirely, leaving your endpoints to handle auth and metadata only.

UploadFile Under the Hood

FastAPI gives you two ways to accept a file, and they behave very differently under load.

Declare the parameter as bytes, and FastAPI reads the whole upload into memory before your function even runs. This works for small files and fails without warning as soon as someone uploads something large. UploadFile is the answer most FastAPI docs point to for a general file upload api, and for good reason: it wraps Starlette’s SpooledTemporaryFile, which keeps small files in memory and spills larger ones to disk automatically, past a configurable threshold. Your endpoint code stays the same either way. Only where the bytes live changes.

from fastapi import FastAPI, UploadFile, File
app = FastAPI()
.post("/upload")
async def upload_file(file: UploadFile = File(...)):
contents = await file.read()
# process contents, or better, stream it in chunks below
await file.close()
return {"filename": file.filename, "size": len(contents)}

This basic form is fine for small files, and it’s already safer than a bytes parameter since Starlette manages the spool for you. It still reads the full file into a variable at once, which is where the next section picks up.

Multipart Done Right

A multipart request isn’t a single file. It’s a series of parts separated by a boundary string, and each part can hold a form field or a file, mixed in any order.

Understanding how does multipart upload work in web applications helps explain why FastAPI needs a parser at all: the framework has to read the boundary, split the body into parts, and hand each one to the right parameter based on its name.

FastAPI handles this parsing for you with UploadFile and Form, so most endpoints don’t need to work with the raw multipart request.

If you’re asking how to add file uploads to a REST API, the basic approach is usually the same: accept the file as multipart form data, validate it early, and save it somewhere reliable before sending a response.

The main difference between frameworks is how much of this work they handle for you.

Set limits on file size and the number of parts before processing the upload. An unlimited number of file parts can use up memory or disk space, even when each file is small.

Multipart parsing gets the file into your endpoint. The next challenge is sending it somewhere else without using too much memory. That’s what we’ll cover next.

Streaming Straight to Storage

Reading the entire file into a variable still means your app has to hold the full file while processing it. For large uploads, that’s not ideal.

A better approach is to stream the file directly to storage in small chunks. With request.stream(), you can read the request body piece by piece without creating a temporary file.

If you’re uploading to your own S3 bucket, the flow is simple: read one chunk, send it as an S3 multipart upload part, then move to the next chunk. You only keep one chunk in memory at a time, so memory usage stays much more predictable even as file sizes grow.

import boto3
from fastapi import FastAPI, Request
app = FastAPI()
s3 = boto3.client("s3")
BUCKET = "your-upload-bucket"
CHUNK_SIZE = 5 * 1024 * 1024  # 5MB, S3's minimum part size
u/app.post("/upload-stream/{key}")
async def upload_stream(key: str, request: Request):
upload = s3.create_multipart_upload(Bucket=BUCKET, Key=key)
upload_id = upload["UploadId"]
parts = []
part_number = 1
buffer = b""
try:
async for chunk in request.stream():
buffer += chunk
while len(buffer) >= CHUNK_SIZE:
part_data, buffer = buffer[:CHUNK_SIZE], buffer[CHUNK_SIZE:]
result = s3.upload_part(
Bucket=BUCKET, Key=key, UploadId=upload_id,
PartNumber=part_number, Body=part_data,
)
parts.append({"PartNumber": part_number, "ETag": result["ETag"]})
part_number += 1
if buffer:
result = s3.upload_part(
Bucket=BUCKET, Key=key, UploadId=upload_id,
PartNumber=part_number, Body=buffer,
)
parts.append({"PartNumber": part_number, "ETag": result["ETag"]})
s3.complete_multipart_upload(
Bucket=BUCKET, Key=key, UploadId=upload_id,
MultipartUpload={"Parts": parts},
)
except Exception:
s3.abort_multipart_upload(Bucket=BUCKET, Key=key, UploadId=upload_id)
raise
return {"key": key, "parts": len(parts)}

This approach adds a little more code, but it gives you an important benefit: memory usage stays close to CHUNK_SIZE, no matter how large the file is.

That only works if you validate the incoming request first. So the next step is making sure those checks are in place.

Limits, Validation and Errors

Streaming protects your memory while the upload is running, but it doesn’t stop a bad request from starting. You should validate the request before reading any file data.

First, check Content-Length against your maximum file size. If the header is missing or can’t be trusted, keep checking the size as you read each chunk and stop as soon as the limit is reached.

You should also check the actual file type. Don’t rely only on the file extension or the MIME type sent by the client because those can be wrong.

These same limits apply to any REST API that handles file uploads, no matter which framework you use. FastAPI simply gives you the tools to check them early.

Once your own upload endpoint is properly limited and validated, there’s another option: don’t handle the file upload yourself at all. That’s the next approach.

The Managed Route, Off the Data Path

The final option is to keep the actual file upload out of FastAPI completely. Instead, clients upload directly through a managed file upload API, while your FastAPI endpoints handle things like authentication and file metadata.

Your server can provide short-lived upload credentials; the client sends the file directly to storage, and your API saves the file details once the upload is complete.

The main benefit is that the file data never passes through your FastAPI container, which keeps your server lighter and reduces memory and bandwidth pressure.

If you don’t want to build and maintain your own file upload infrastructure, a managed service can handle that part for you.

Filestack’s REST API supports file uploads up to 5 GB and uses chunked uploads for large files. This lets your FastAPI service focus on things like authentication and file metadata instead of moving the actual file data.

import requests
FILESTACK_API_KEY = "YOUR_API_KEY"
def get_upload_url(filename: str) -> dict:
response = requests.post(
f"<https://www.filestackapi.com/api/store/S3?key={FILESTACK_API_KEY}>",
params={"filename": filename},

)

response.raise_for_status()

return response.json()  # contains the URL the client uploads to directly

Your endpoint only needs to provide the upload URL and save the returned file handle after the upload succeeds. The actual file transfer happens outside your service.

Now that we’ve covered all four approaches, here’s a quick summary of what to do.

Conclusion: Choose Your Memory Tier on Purpose

FastAPI gives you four main ways to handle file uploads. The key difference is where the file data goes while it’s being uploaded.

Buffer keeps the whole file in memory. Spool, which is what UploadFile uses, keeps smaller files in memory and moves larger ones to disk. Stream sends the file in chunks directly to storage, keeping memory usage low. Bypass skips your server completely and lets the client upload directly to storage.

Choose the approach based on your file sizes and infrastructure instead of waiting for a large upload to crash your container.

A good first step is to replace any bytes parameter that is still being used for real file uploads.

This article was published on the Filestack blog.

How to Upload JPG File on Mobile with Orientation, Size and Format Traps

IderaDevTools — Wed, 09 Sep 2026 10:45:00 +0000

Three common problems can show up in the same sprint. An avatar appears sideways on Android. A 12 MB photo takes too long to upload on a weak connection. And an iPhone photo fails validation because it isn’t actually a JPG.

Most guides on how to upload JPG files on mobile stop once the file is selected. But that’s where the real problems often begin.

The photo might arrive rotated, be much larger than needed, or turn out to be a different format. Each of these problems has a clear cause and a simple fix.

To upload a JPG file on mobile, let users pick from camera or gallery, then handle the three traps that break JPG uploads: EXIF orientation (photos arriving sideways), oversized camera outputs (often 5–12MB), and format mismatches such as HEIC masquerading as JPG on iOS. Client-side resize plus server-side normalisation solves all three. Filestack converts, rotates, and compresses automatically on upload.

This article looks at each problem separately and then shows how to handle all of them in one step. That way, you don’t have to fix each upload bug as it appears.

Key Takeaways

EXIF Orientation values 3, 6, and 8 mark a rotated capture. Ignore them, and the photo displays sideways or upside down.
Phone cameras commonly output 5 to 12MB JPGs at 12 to 48 megapixels, far more than any screen needs to display.
iOS saves photos as HEIC by default. A file named photo.jpg is not proof that it holds JPG data.
A canvas resize on the client fixes orientation and file size in one step, since the redrawn pixels come out upright.
Server-side normalisation catches every client you don’t control, including third-party apps and old app versions still in the wild.

Trap 1, The Sideways Photo (EXIF Orientation)

Phone cameras don’t rotate the pixel data when you turn the phone. They save the image as captured and write a rotation instruction into the EXIF metadata instead. Most photo apps read that instruction and display the photo the right way up. Plenty of image libraries and browsers don’t, and that’s when a portrait selfie shows up lying on its side in your app.

The Orientation tag can hold several values, but three of them cause almost every sideways bug: values 3, 6, and 8 mark a rotated capture, corresponding to 180, 90, and 270 degrees. If your upload pipeline ignores this tag, the photo saves and displays exactly as rotated.

The fix is to draw the image onto a canvas using the correct rotation before you upload it. Once it’s drawn, the pixels themselves are upright, so no downstream viewer can get it wrong again.

function drawUprightImage(file) {
return new Promise((resolve) => {
const img = new Image();
const reader = new FileReader();
reader.onload = (e) => {
img.onload = () => {
const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');
getOrientation(file, (orientation) => {
const swap = orientation >= 5 && orientation <= 8;
canvas.width = swap ? img.height : img.width;
canvas.height = swap ? img.width : img.height;
switch (orientation) {
case 3: ctx.transform(-1, 0, 0, -1, canvas.width, canvas.height); break;
case 6: ctx.transform(0, 1, -1, 0, canvas.height, 0); break;
case 8: ctx.transform(0, -1, 1, 0, 0, canvas.width); break;
default: break;
}
ctx.drawImage(img, 0, 0);
canvas.toBlob((blob) => resolve(blob), 'image/jpeg', 0.9);
});
};
img.src = e.target.result;
};
reader.readAsDataURL(file);
});
}

Fixing orientation on the client helps, but it only covers the clients you control. Keep that in mind while we move to the next trap, which shares part of the same fix.

Trap 2, The 12MB Camera File

A modern phone camera shoots at 12 to 48 megapixels and saves the result as a JPG in the 5 to 12MB range. Almost nothing in your app needs that much resolution. A profile photo displays at a few hundred pixels wide. Even a full-screen image rarely needs more than 2000 pixels on its longest edge.

Uploading the full-size image uses extra time and data without giving you much benefit. It’s really a page-size problem, just happening during the upload.

The same rule used to speed up image loading applies here too: resize the image to the size you actually need before uploading it.

Resize on the client before the upload starts. Canvas resize also solves this in the same pass as the orientation fix above, since you’re already redrawing the image. Set a maximum dimension, scale the canvas to fit it, and export at a reasonable JPEG quality like 0.8 or 0.9. A 10MB original commonly comes out under 1MB with no visible loss on a phone screen.

Resizing the image on the device takes care of the file size before upload. The next problem is a little trickier because the file may look completely normal at first.

Trap 3, HEIC in JPG Clothing

iOS stores photos as HEIC by default, not JPG. Some pickers and share sheets hand the file over with a .jpg extension anyway, or a name that looks like a JPG, while the actual bytes are still HEIC. A file extension is a label someone chose. It is not proof of what’s inside the file.

Trusting the extension is how format bugs make it to production undetected in testing. The safest check is the byte signature at the start of the file, not the name. JPG files start with the bytes FF D8 FF. HEIC files carry a different signature entirely. Check the actual bytes, and convert if the signature doesn’t match what the extension claims.

This is where image transformation pipelines can make things easier. A common question is how to resize, crop, watermark, or change an image format on the fly.

Instead of processing the same image several times, you can use one transformation URL to handle multiple changes in a single request. Filestack can use the image’s EXIF data to correct its orientation, convert HEIC images to JPG or WebP, and compress the image in the same transformation chain.

Now that we’ve covered all three problems, the next question is where to handle each one in your app.

Implementation, Web Form and Native

On mobile web, image uploads usually start with a file input. A common question is how to add image uploads to a web form. You can use <input type="file" accept="image/*" capture="environment"> to open the camera directly. If you remove capture, users can choose between the camera and gallery.

Native apps work a little differently. Both iOS and Android have SDKs that can handle camera and gallery permissions, so you don’t have to build that flow yourself.

React Native has its own approach. Image picker libraries return a local file URI instead of a browser File object, so your upload code needs to read the file from that URI first.

The fixes for orientation and file size stay the same across platforms. Only the way you get the file changes.

You can build all of this yourself, but that means maintaining similar upload logic for web, iOS, Android, and React Native. There is a simpler way to handle it.

The Managed Route, Normalise on Ingestion

You can handle all three problems with a single mobile file upload flow that automatically fixes orientation, converts formats, and compresses images as they are uploaded.

Instead of writing separate code for image rotation on the web, native SDKs, and HEIC checks, you can use one transformation process for every file as soon as it arrives.

Server-side normalisation also handles files from places you don’t control. Older app versions, third-party integrations, and API requests might skip your client-side fixes. A server-side step catches these files too and makes sure they follow the same rules.

Once the file is normalised, you can create different image sizes for your app. This leads to another common question: how can you generate thumbnails automatically after an upload?

You can create thumbnails, medium previews, and full-size versions from the same normalised image. This is much simpler than running a separate resize job for each version.

We’ve covered how to fix each problem. Here’s a quick summary to remember.

Conclusion: Trust Bytes, Not Extensions

Three traps, three fixes: orient from EXIF instead of trusting the file as captured, resize early instead of uploading the full camera output, and convert by byte signature instead of trusting the file extension. Client-side resize handles the traffic you can see. Server-side normalisation catches everything else.

Run a real phone photo through a transformation sandbox and check all three: does it come out upright, does it come out at a sane file size, and does it come out as an actual JPG regardless of what the original claimed to be.

Frequently Asked Questions

Why do my mobile photo uploads appear sideways?

EXIF Orientation is being ignored somewhere in the pipeline. Auto-orient on ingestion, or draw the image upright client-side using the Orientation tag before upload.

Why did an iPhone JPG upload fail validation?

It was likely HEIC with a JPG-style name. Check the byte signature rather than the file extension, and convert HEIC to JPG or WebP if the signature doesn’t match.

How big are phone camera JPGs?

Commonly 5 to 12MB at 12 to 48 megapixels. Resize to the display target before or during upload rather than sending the original file.

This article was published on the Filestack blog.

How to Build a Scalable Image Upload Component with Shadcn UI

IderaDevTools — Wed, 02 Sep 2026 13:10:02 +0000

If you search for a Shadcn UI image upload component, you’ll quickly notice there isn’t one. That’s intentional.

You might try running npx shadcn add upload, only to find that no upload component exists. Then you end up on the same GitHub discussions as many other developers asking the same question: Where is the image upload component?

The honest answer is: you build it yourself.

At first, that might seem surprising, but it actually makes sense. Shadcn UI isn’t a library where you install ready-made components. Instead, it gives you building blocks that you add to your own codebase and customise as needed.

Image upload is different for every application. The upload flow, states, and backend integration can vary a lot, so a single upload component wouldn’t work for every use case.

Shadcn UI ships no built-in image upload component; you compose one from its primitives (Button, Card, Progress, Dialog) around an upload engine that handles files, previews, and errors. The clean split is shadcn for presentation and a dedicated uploader for transfer. Filestack’s React SDK slots in as that engine, keeping the shadcn look while adding chunked, resumable uploads.

In this guide, we’ll build an image upload component step by step. We’ll use Shadcn UI to create the interface, add state management and validation, and then connect it to an upload service.

The best part is that you can change the upload provider later without rebuilding the UI. The interface stays the same while the upload logic can be swapped whenever you need.

Key Takeaways

Shadcn/ui has no upload component on purpose. You compose one from Card, Button, Progress, and Dialog.
A working upload UI needs four pieces: a dropzone surface, file rows, a progress bar per row, and error text inside the row, not a toast.
A hidden <input type="file"> paired with a <label> keeps the dropzone accessible and keyboard operable.
Keep transfer logic behind a small interface. Swapping fetch() for a real upload SDK should change zero markup.
Filestack’s React SDK maps its progress callbacks directly onto Shadcn’s <code>Progress component, so the engine and the UI stay decoupled.

Before building anything, it’s worth understanding why this gap exists, because it shapes every decision after it.

Why Shadcn Does Not Ship an Uploader

Shadcn’s whole philosophy is “copy the code, own the code.” That works well for a button or a dialog, because those components don’t hold much internal state. An uploader is different. It has to track file selection, per-file progress, retries, validation errors, and network failures, all at once. Trying to template that into one drop-in component would mean baking in assumptions about your backend, your file size limits, and your error handling, exactly the kind of lock-in shadcn tries to avoid.

So instead of asking “what are the best React components for file uploading,” the more useful question becomes “which primitives do I already have, and what’s missing?” As it turns out, you already have most of what you need. What’s missing is the part that actually talks to a server.

With that context in place, let’s start stacking primitives into an actual dropzone.

Composing the Surface: Dropzone plus Rows plus Progress

This is where shadcn earns its keep. A React drag-and-drop file upload surface and a React file upload component for the file list are really the same composition problem, just two different views of it.

The dropzone itself is a Card wrapping a hidden file input and a label. The label pattern matters here: clicking anywhere on the label opens the file picker, and because it’s a real form control under the hood, keyboard users can tab to it and hit Enter or Space to open it too. Below the dropzone, each selected file becomes its own row, and each row gets its own Progress bar.

import { Card } from "@/components/ui/card";
import { Progress } from "@/components/ui/progress";
import { cn } from "@/lib/utils";
export function ImageUploader({ files, onFilesSelected, onRetry }) {
return (
<Card className="p-6">
<label
htmlFor="file-input"
className={cn(
"flex flex-col items-center justify-center gap-3",
"rounded-lg border-2 border-dashed border-muted-foreground/30",
"py-10 text-center cursor-pointer hover:border-primary/50"
)}
>
<span className="font-medium">Drag and drop images here</span>
<span className="text-sm text-muted-foreground">or click to browse</span>
<input
id="file-input"
type="file"
multiple
accept="image/*"
className="sr-only"
onChange={(e) => onFilesSelected(Array.from(e.target.files))}
/>
</label>
<ul className="mt-6 space-y-3">
{files.map((file) => (
<li key={file.id} className="rounded-md border p-3">
<div className="flex items-center justify-between text-sm">
<span className="font-medium">{file.name}</span>
{file.status === "failed" ? (
<button
onClick={() => onRetry(file.id)}
className="text-destructive underline"
>
Retry
</button>
) : (
<span className="text-muted-foreground">{file.status}</span>
)}
</div>
<Progress value={file.progress} className="mt-2 h-2" />
{file.error && (
<p className="mt-1 text-xs text-destructive">{file.error}</p>
)}
</li>
))}
</ul>
</Card>
);
}

Notice the error text sits inside the row, right under that file’s own progress bar, instead of floating away in a toast. A toast disappears in a few seconds. A row stays put until the user deals with it, which matters when three out of twenty files failed, and you don’t want the person hunting for which ones.

The surface is only half the job, though. Right now, none of this actually tracks state. Let’s fix that next.

State and Validation

With the JSX in place, the component needs somewhere to keep track of what’s happening to each file, and a way to say no to files that shouldn’t be there in the first place.

A useReducer keyed by file ID works well here, since every file’s status changes independently of the others. Validation, checking file type and size, happens the moment a file is selected, before any request goes out. This answers a common early question too: file uploading in React JS almost always starts with this same shape, a reducer plus a validation step, no matter which transport ends up sending the bytes.

function uploadReducer(state, action) {
switch (action.type) {
case "ADD_FILES":
return {
...state,
...Object.fromEntries(
action.files.map((f) => [f.id, { ...f, status: "queued", progress: 0 }])
),
};
case "PROGRESS":
return {
...state,
[action.id]: { ...state[action.id], status: "uploading", progress: action.pct },
};
case "DONE":
return { ...state, [action.id]: { ...state[action.id], status: "done", progress: 100 } };
case "ERROR":
return {
...state,
[action.id]: { ...state[action.id], status: "failed", error: action.message },
};
default:
return state;
}
}

Validation lives right where files enter the component:

function validateFile(file) {
if (!file.type.startsWith("image/")) return "Only image files are allowed.";
if (file.size > 10 * 1024 * 1024) return "File is larger than 10MB.";
return null;
}

Most guides on implementing image uploads in React stop here, with a working component and simulated progress. That’s enough to show how the UI works.

But in a real application, you also need something that uploads the file and reports the actual upload progress. That’s where choosing the right upload solution becomes important.

The Engine Swap: fetch to SDK

This is the piece that makes the whole composition worth the extra setup: the transport layer sits behind a small interface, so the shadcn component above never needs to know or care how bytes actually get to the server.

Start with the interface itself. It only needs one method, and it only needs to report progress and completion:

// uploadEngine.js
export function createFetchEngine(endpoint) {
return {
upload(file, { onProgress, onDone, onError }) {
const xhr = new XMLHttpRequest();
const form = new FormData();
form.append("file", file);
xhr.upload.onprogress = (e) => {
onProgress(Math.round((e.loaded / e.total) * 100));
};
xhr.onload = () => (xhr.status < 300 ? onDone(xhr.response) : onError("Upload failed"));
xhr.onerror = () => onError("Network error");
xhr.open("POST", endpoint);
xhr.send(form);
},
};
}

A React JS file upload component built this way already works. The catch is that raw fetch or XMLHttpRequest gives you one request per file, no chunking, and no way to resume a large upload that drops halfway through. Swapping in Filestack’s React SDK as the engine keeps the exact same interface, but the internals now handle chunked, resumable transfer:

import { init } from "filestack-js";
export function createFilestackEngine(apiKey) {
const client = init(apiKey);
return {
upload(file, { onProgress, onDone, onError }) {
client
.upload(file, {
onProgress: (evt) => onProgress(Math.round(evt.totalPercent)),
})
.then((res) => onDone(res))
.catch((err) => onError(err.message));
},
};
}

Both upload engines use the same upload(file, callbacks) function, so you don’t need to change the component from Section 2. The only thing that changes is the upload engine you pass into it.

The Managed Route: Shadcn Look, Production Engine

Building your own fetch-based engine is a fine way to learn the shape of the problem, and it’s genuinely enough for a small internal tool. But once you need chunking for large images, resumable uploads on flaky connections, or reliable retry behaviour, that engine starts asking for real maintenance time.

Keep the markup, upgrade the engine: wire the composed component to a production upload ui and the same shadcn rows gain chunked transfer, retries, and 5GB file support, without a redesign. The onProgress callback from the React SDK maps one-to-one onto the Progress value you’re already rendering, so the swap really is as small as it looks in the code above.

This is also where teams building something like a profile picture uploader tend to land. The UI stays identical to a plain gallery upload, same dropzone, same rows, but the failure modes that matter for a single, important image (say, someone’s profile photo) get handled by the engine instead of a hand-rolled retry loop.

If you’re curious how that plays out for single-file, high-stakes uploads, our React file upload walkthrough covers that shape in more depth.

Conclusion: Own the Pixels, Outsource the Packets

The lesson underneath all of this is simpler than it looks in the code: shadcn was never going to ship an uploader, because uploading isn’t really a presentation problem. It’s a transport problem wearing a UI.

Split the two apart, and both sides get easier. You keep full control over how the dropzone and rows look and feel, since that’s just your own JSX and Tailwind classes. And you keep the option to swap the engine underneath, from a quick fetch call to something built for chunking and retries, without ever touching that markup again.

If you want to see it end to end, copy the composed component above and connect it to Filestack to see real progress values fill in those same progress bars.

This article was published on the Filestack blog.