Upgrading filestack-react From v6 to v7

Upgrading filestack-react from v6 to v7 is a version bump, one extra install, and one behaviour change that alters a working application without producing an error. What shipped in the release is listed in the React SDK v7.0.0 notes.

The before-and-after code for every step below is in filestack-snippets.

Key takeaways

• v7 needs two installs, because filestack-js is now a peer dependency.
• Passing both onSuccess and onUploadDone no longer fires both callbacks.
• Upload counts halving after the upgrade is the corrected number, not a regression.
• Delete type shims and SSR workarounds, since the package now ships types and 'use client'.
• Component names, props and picker options are unchanged, so nothing else has to move.

Install two packages, not one

npm install filestack-react@^7.0.1 filestack-js@^4.0.1

v7 moves filestack-js from a direct dependency to a peer dependency. If you skip the second package the build fails at import time.

Two things follow from the change. Projects that already had filestack-js in their own package.json were shipping two copies of it, and now ship one. And the client methods that arrived in filestack-js v4, including download, prefetch, setSecurity, setCname and folder upload, become reachable from a v7 integration.

Use ^4.0.1 rather than a pinned 4.0.0 so later 4.x patch releases are installed.

The change that alters behaviour silently

In v6, providing both onSuccess and onUploadDone called both of them on every completed upload. In v7 only onUploadDone fires, and onSuccess is the fallback used when onUploadDone is absent.

 <PickerOverlay
-  onSuccess={trackUpload}
-  onUploadDone={trackUpload}
+  onUploadDone={trackUpload}
 />

Nothing errors either way. What changes is the count. If you passed both callbacks and both did something, that something happened twice per upload for as long as you were on v6, and after the upgrade it happens once. Analytics events, database writes and webhook triggers all sit in this category.

A 50% drop in those counts the week you ship the upgrade is the corrected number.

onSuccess still works and is marked deprecated. Moving to onUploadDone now costs one line and removes the ambiguity.

Expect the console to go quiet

v7 writes nothing to the browser console on a successful upload. Your logging is yours to place, at the level of detail your environment calls for.

To confirm an upload from the console after the upgrade, log the result yourself inside onUploadDone.

Delete your type shims

The SDK was rewritten from JavaScript to TypeScript and the declaration files ship inside the package. There is no @types/filestack-react to install, and if one is in your package.json it should come out, since a stale community declaration will shadow the real one.

Any local shim goes too:

-declare module 'filestack-react';

A bodyless declare module types the entire package as any and overrides the declarations the package ships.

Remove the SSR workarounds

v7 ships 'use client' on both the ESM and CJS builds, derives DOM ids with useId() so the server and client agree, and corrects the export map. The workarounds that existed only to route around v6 can go:

• dynamic-import wrappers whose only job was keeping the picker out of the server bundle
• transpilePackages entries added for Next.js
• manually generated container ids passed in to avoid hydration mismatches
• typeof window !== 'undefined' guards wrapped around the component itself

Remove them one at a time and rebuild between each. On the App Router there is one thing not to remove, covered below.

The one App Router caveat

The package shipping 'use client' does not mean a Server Component can render FilestackProvider. The provider takes function props, functions cannot cross the server to client boundary, and the page render fails with Functions cannot be passed directly to Client Components rather than the build failing.

Keep the small client component that holds your callbacks:

'use client';

export default function Providers({ children }) {
  return (
    <FilestackProvider apikey={KEY} onUploadDone={handleDone}>
      {children}
    </FilestackProvider>
  );
}

layout.tsx stays a Server Component and renders that. Nothing else about the App Router integration needs special handling in v7, and the React, Next.js and plain HTML setup guide shows the same boundary in a fresh project.

Optional, and the reason to bother

Everything above is compatibility work. FilestackProvider is the part that makes the upgrade worth doing on a codebase with more than two upload screens.

-<PickerOverlay apikey={KEY} pickerOptions={opts} onUploadDone={done} />
-<PickerInline  apikey={KEY} pickerOptions={opts} onUploadDone={done} />
+<FilestackProvider apikey={KEY} pickerOptions={opts} onUploadDone={done}>
+  <PickerOverlay />
+  <PickerInline />
+</FilestackProvider>

Component props still win over the provider, and option objects are shallow-merged with the provider’s values as the base, so one screen can accept a different file type without the provider knowing. Migrating to it is not required and can be done screen by screen. Every prop the provider accepts is listed on the React file upload SDK page.

Planning the rollout

On a small application the upgrade is a single commit. On a large one it is worth splitting, because the compatibility work and the provider migration have completely different risk profiles.

The first commit is the install, the callback consolidation and the deletions. It touches every upload screen but changes behaviour in exactly one way, so it reviews quickly and reverts cleanly. Ship it on its own and watch whatever counts your uploads for a day.

The second commit introduces FilestackProvider and removes the repeated props. It is a larger diff and a smaller risk, since component props still win over context and a screen you have not migrated behaves identically. Doing it screen by screen is fine, and there is no half-migrated state that breaks.

Keeping them apart isolates the double-callback fix, which is the only change across the two commits that moves your upload counts. The wider question of which parts of an upload integration survive a version bump is covered in the guide to future-proofing a React uploader.

What did not change

Component names, props and the picker options object are all the same. There is no renamed export, no changed import path and no altered options schema. For most applications the whole migration is the install, the callback edit, and deleting things.

v7 supports React 18.3.1 and React 19, so the upgrade does not force a React version move in either direction.

Verifying the upgrade

Four checks, in the order that finds problems fastest.

Build first, because a missing peer dependency and a stale type shim both surface there. Then open an upload screen and confirm the picker still opens, which catches export-map problems. Then upload one file and confirm your callback ran exactly once. Finally, on a server-rendered route, view source and confirm the page still renders without the picker in the initial HTML.

If the picker no longer appears at all, check the workarounds you removed in the previous step. A Remix route that lost its typeof window guard still needs a mounted check, because Remix has no client boundary to lean on.

After the upgrade

The v4 client is the part worth exploring once you are on v7. download, prefetch, setSecurity, setCname and folder upload all become reachable, and none of them need another dependency. Transformations work as they always have, as path segments in front of a handle, so the image editing api is available from a v7 integration with nothing else installed.

If the integration you are upgrading predates the component API altogether, rebuilding it from the current SDK is often less work than migrating it, and the React file upload tutorial starts from an empty app.

FAQ

Will the upgrade break my existing pickers?

No. Component names, props and the picker options schema are unchanged, so screens that compile on v6 compile on v7. The only behaviour that shifts is the callback count when both onSuccess and onUploadDone were passed.

Why did my upload numbers drop by half after upgrading?

Because they were double counted on v6. Passing both callbacks fired both on every upload, so analytics events, database writes and webhooks all ran twice. The post-upgrade figure is the accurate one.

Do I have to migrate to FilestackProvider?

No. It is optional and worth it once you have more than two upload screens. Component props still win over the provider, so you can migrate one screen at a time with no half-migrated state that breaks.

Does v7 force a React version upgrade?

No. v7 supports React 18.3.1 and React 19, so you can upgrade the SDK without touching your React version, or upgrade both separately.

 

 

Read More →