how does this work? How do I migrate?

Question

I have been using the previous version (@uploadcare/blocks). But that does not work any more since a recent update (0.39.0?). Unfortunately I didn't immediately realize this as the version numbers do not imply breaking changes.

After finally realizing the previous implementation was broken and subsequently digging for a while I found that now there exists a version of uploadcare that seems to target react specifically (react-components). Although nowhere does it seem to be mentioned that this is what this version is for.

Unfortunately there seems to exist no migration docs.

I have read the readme of the new version a few times. Unfortunately I am missing a complete picture and can not make sense of what I see.

Some questions coming up are:

how would I migrate an existing implementation?
what can .initFlow() be called on?
is there no more context that needs to be provided?
what exactly is UploadCtxProvider that is shown to be used directly with a useRef unlike previously createRef?
is there somewhere a complete, yet simple working example?

The readme links to the previous documentation. But that being COMPLETELY different does not really help.

This is not a great upgrading experience. Especially not for a paid product. It honestly sucks to have to reimplement uploading from scratch after unintentionally breaking the app. And not being able to do that as the docs only give a few glimpses into what a complete solution could be.

Hi @barbalex,

Thank you for your detailed question and for highlighting our documentation issues. It's greatly appreciated!

Yes, until the future v1 release, we are not following semver, and it seems the only place mentioning this is the installation section of the documentation - https://uploadcare.com/docs/file-uploader/installation/#from-npm. Not very obvious, I agree.

For each new version, we release a changelog with a detailed list of changes, including breaking changes, and we also provide links to migration guides. For example, here's the changelog and migration guide for v0.39.0 - https://github.com/uploadcare/blocks/releases/tag/v0.39.0.

The react-uploader package is a wrapper around @uploadcare/blocks that makes it easier to use within the React ecosystem. It simplifies event handling, encapsulates all uploader components inside, and slightly improves typing.

Under the hood, react-uploader renders all those lr-config, lr-upload-ctx-provider and lr-file-uploader-regular blocks, maps props to attributes and DOM properties, manages event handlers, and provides a ref to the API instance.

Now, let's move on to your questions.

How would I migrate an existing implementation?

Unfortunately, we don't have a specific migration guide for this. You need to:

Replace the set of blocks lr-config, lr-upload-ctx-provider, and lr-file-uploader-regular with a single FileUploaderRegular component.
The former attribute ctx-name is now ctxName, but it can be omitted as it's optional. It's needed only if you have multiple uploaders.
All event handlers that you previously added manually should now be passed as props, such as onChange or onFileUploadStart.
All attributes that were passed to lr-config should now be passed to FileUploaderRegular in camelCase.
All rich data properties that were passed in lr-config through the DOM API can now be passed through props, for example, metadata.
The instance API that you previously obtained through a ref on lr-upload-ctx-provider can now be obtained through a ref on the apiRef prop.

What can .initFlow() be called on?

initFlow is called on the API instance available in the apiRef prop. Example usage from the react-uploader docs:

const Example = () => {
    const uploaderRef = useRef<InstanceType<UploadCtxProvider> | null>(null);
    useEffect(() => {
        if (uploaderRef.current) {
            uploaderRef.current.initFlow();
        }
    }, []);
    return <FileUploaderRegular apiRef={uploaderRef} pubkey="YOUR_PUBLIC_KEY"/>;
}

Is there no more context that needs to be provided?

I didn't quite get this question. Could you please clarify?

What exactly is UploadCtxProvider that is shown to be used directly with a useRef unlike previously createRef?

UploadCtxProvider is a block (technically it's a DOM element or Custom Element) that provides an API. It's described in the documentation here - https://uploadcare.com/docs/file-uploader/api/.

A React ref is used to get access to this DOM element instance. It's a common pattern in React to get access to DOM elements or other instances.

Previously, you had to manually get this instance by passing ref to the lr-upload-ctx-provider block. Now, you can get it through the apiRef prop on FileUploaderRegular.

Is there somewhere a complete, yet simple working example?

Yes, there are examples available on CodeSandbox: https://github.com/uploadcare/blocks-examples/tree/main/examples/react-uploader-adapter.

I hope I have answered all your questions. If you have any more, please feel free to ask!

uploadcare / react-file-uploader