> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
# Migration guide for @uploadcare/blocks v0.25.0
> Migration guide for @uploadcare/blocks v0.25.0
## BREAKING CHANGES
1. Configuration in CSS is now deprecated.
Although it currently works, it will be removed shortly.
In lieu of this, we are introducing a new lr-config block for configuration definitions.
2. The `css-src` attribute is now required on solution blocks.
This implies that the use of Shadow DOM is enforced.
3. The `ctx-name` attribute is required for each block on the page.
4. Method `setUploadMetadata` is deprecated in favour of `metadata` DOM property
on the `lr-config` block.
5. Method `addFiles` is deprecated in favour of `addFileFromObject`
6. `CloudEditor` (`lr-cloud-editor`) solution block is renamed to
`CloudImageEditor` (`lr-cloud-image-editor`).
7. `CloudImageEditor` (`lr-cloud-image-editor`) activity is renamed to
`CloudImageEditorActivity` (`lr-cloud-image-editor-activity`).
8. All solution bundles are prefixed with `lr-` prefix:
* `file-uploader-regular.min.js` -> `lr-file-uploader-regular.min.js`
* `file-uploader-regular.min.css` -> `lr-file-uploader-regular.min.css`
* `file-uploader-inline.min.js` -> `lr-file-uploader-inline.min.js`
* `file-uploader-inline.min.css` -> `lr-file-uploader-inline.min.css`
* `file-uploader-minimal.min.js` -> `lr-file-uploader-minimal.min.js`
* `file-uploader-minimal.min.css` -> `lr-file-uploader-minimal.min.css`
9. Solution bundles do not automatically register blocks.
You will need to register them manually:
```js
import * as LR from 'https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-file-uploader-regular.min.js'
LR.registerBlocks(LR)
```
9. Bundle `blocks.iife.js` is renamed to `blocks.iife.min.js`.
10. Bundle `blocks-browser.min.js` is deprecated. Use `blocks.iife.min.js`
instead.
## How to migrate
### Configuration
First and foremost, you need to shift all the configuration from CSS to the `lr-config` block.
For instance, if you have the following CSS:
```css
.config {
--ctx-name: 'my-uploader';
--cfg-pubkey: 'YOUR_PUBLIC_KEY';
--cfg-multiple-min: 0;
--cfg-multiple-max: 3;
}
```
Get `YOUR_PUBLIC_KEY` from [API keys](https://app.uploadcare.com/projects/-/api-keys/).
Move it to the `lr-config` block:
```html
```
Subsequently, you should link your solution block to the `lr-config` block using the `ctx-name` attribute:
```html
```
The property names remain the same but without the `--cfg` prefix. For example,
`--cfg-pubkey` becomes simply `pubkey`.
See the [configuration reference](/docs/file-uploader/configuration/) for more details.
### Dynamic configuration updates
If you have dynamically updated CSS configuration like this:
```js
const uploader = document.querySelector('lr-file-uploader-regular')
uploader.style.setProperty('--cfg-pubkey', 'YOUR_PUBLIC_KEY')
const uploaderCtx = document.querySelector('lr-upload-ctx-provider')
uploaderCtx.updateCtxCssData()
```
You need to update it to the following:
```js
const config = document.querySelector('lr-config')
config.setAttribute('pubkey', 'YOUR_PUBLIC_KEY') // using attribute
config.pubkey = 'YOUR_PUBLIC_KEY' // or using DOM property
```
Both attributes and DOM properties are reactive, so you don't need to call
`updateCtxCssData` anymore.
### Shadow DOM and `css-src`
Shadow DOM is now enforced for all the solution blocks. It means that you need
to use `css-src` attribute to attach CSS to the block.
If you previously attached CSS to the global like this:
```html
```
You need to use `css-src` attribute instead:
```html
```
(Other attributes are omitted for brevity)
### `ctx-name` attribute
`ctx-name` attribute is required for all the blocks now, even if you have only
one block on the page. It's used to wire blocks to the `lr-config` block. For
example:
```html
```
(Other attributes are omitted for brevity)
### Replace `setUploadMetadata` with `metadata` DOM property
If you were using `setUploadMetadata` method like this:
```js
uploaderCtxProvider.setUploadMetadata({ foo: 'bar' })
```
You need to replace it with `metadata` DOM property on the `lr-config` block:
```js
const config = document.querySelector('lr-config')
config.metadata = { foo: 'bar' }
// or
config.metadata = () => Promise.resolve({ foo: 'bar' })
```
See the [configuration reference](/docs/file-uploader/options/#metadata) for more details.
### Replace `addFiles` with `addFileFromObject`
If you were using `addFiles` method like this:
```js
const file = new File(["foo"], "foo.txt", {
type: "text/plain",
});
uploaderCtxProvider.addFiles([file])
```
You need to replace it with `addFileFromObject`:
```js
const file = new File(["foo"], "foo.txt", {
type: "text/plain",
});
uploaderCtxProvider.addFileFromObject(file)
```
In case of multiple files, you need to call `addFileFromObject` for each file:
```js
const files = [
new File(["1"], "1.txt", {
type: "text/plain",
}),
new File(["2"], "2.txt", {
type: "text/plain",
}),
];
for(const file of files) {
uploaderCtxProvider.addFileFromObject(file)
}
```
See the [`addFileFromObject` reference](/docs/file-uploader/styling/#icons) for more details.
### Rename `CloudEditor` -> `CloudImageEditor`
If you were using a standalone `lr-cloud-editor` solution block, you need to rename
it to `lr-cloud-image-editor` like this:
```html
```
### Rename `CloudImageEditor` -> `CloudImageEditorActivity`
If you were using `lr-cloud-image-editor` activity block inside your custom
Symbiote.js templates, you need to rename it to `lr-cloud-image-editor-activity`
like this:
```js
FileUploaderRegular.template = /* HTML */ `
`
```
### Rename imported JS and CSS bundles
Just rename all the imports according to the following table:
| Old name | New name |
| ------------------------------- | ---------------------------------- |
| `file-uploader-regular.min.js` | `lr-file-uploader-regular.min.js` |
| `file-uploader-regular.min.css` | `lr-file-uploader-regular.min.css` |
| `file-uploader-inline.min.js` | `lr-file-uploader-inline.min.js` |
| `file-uploader-inline.min.css` | `lr-file-uploader-inline.min.css` |
| `file-uploader-minimal.min.js` | `lr-file-uploader-minimal.min.js` |
| `file-uploader-minimal.min.css` | `lr-file-uploader-minimal.min.css` |
For example:
```html
```
Became:
```html
```
### Call `registerBlocks` manually
If you have installed blocks using `min.js` bundles, you need to call
`registerBlocks` manually:
```html
```
### Rename `blocks.iife.js` to `blocks.iife.min.js`
If you previously used the `blocks.iife.js` bundle, you need to rename it to
`blocks.iife.min.js` as follows:
```html
```
### Rename `blocks-browser.min.js` to `blocks.iife.min.js`
If you were using the `connectBlocksFrom` method in conjunction with the
`blocks-browser.min.js` bundle, you need to rename it to `blocks.iife.min.js`,
as shown below:
```js
connectBlocksFrom('https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/blocks.iife.min.js').then(
(LR) => {
LR.registerBlocks(LR);
// ...
}
);
```
If you were using `blocks-browser.min.js` via a `script` tag with `type="module"`,
you need to rename it to `blocks.min.js`, as shown below:
```html
```
If you were using `blocks-browser.min.js` via a `script` tag without
`type="module"`, you need to rename it to `blocks.iife.min.js`, as shown below:
```html
```