|
| 1 | +--- |
| 2 | +"@unpic/svelte": major |
| 3 | +"@unpic/react": major |
| 4 | +"@unpic/core": major |
| 5 | +"@unpic/angular": major |
| 6 | +"@unpic/astro": major |
| 7 | +"@unpic/lit": major |
| 8 | +"@unpic/preact": major |
| 9 | +"@unpic/qwik": major |
| 10 | +"@unpic/solid": major |
| 11 | +"@unpic/vue": major |
| 12 | +"@unpic/webc": major |
| 13 | +--- |
| 14 | + |
| 15 | +Welcome to version 1.0.0 of Unpic! 🎉 |
| 16 | + |
| 17 | +This is a major update, with changes to the API of all frameworks. This will not |
| 18 | +affect you if you are just using the components with default options, but if you |
| 19 | +are passing custom transformers or specifying the CDN then you will need to |
| 20 | +update your code. |
| 21 | + |
| 22 | +## Breaking changes |
| 23 | + |
| 24 | +* The `cdnOptions` property has been removed. Use the new [`options` property](#provider-options) |
| 25 | + instead. |
| 26 | +* The `transformer` property has been removed from the default `Image` component. Import [the base component](#base-component) and specify the transformer there instead. The type signature for the transformer has also changed. See the `unpic` library documentation for more information. |
| 27 | +* The `cdn` property has been removed. Either use the new [`fallback` property](#fallback-providers) or import [the base component](#base-component) and pass a single provider to it. |
| 28 | + |
| 29 | + |
| 30 | +## Changes |
| 31 | + |
| 32 | +Most of the changes are because of a new approach to handling individual image |
| 33 | +CDNs and providers in the base Unpic library. This is designed to make Unpic |
| 34 | +more flexible, efficient and modular. It also introduces support for |
| 35 | +type-safe custom operations and options for each provider. |
| 36 | + |
| 37 | +### Provider operations |
| 38 | + |
| 39 | +*Supported frameworks: All except `webc` and `lit`.* |
| 40 | + |
| 41 | +The new `operations` property allows you to specify custom operations for each |
| 42 | +provider. Many image CDNs support dozens of custom operations. Previously these |
| 43 | +were hard to use with Unpic. The new `operations` property gives type-safe |
| 44 | +support for all supported features of each provider. This works even if you have |
| 45 | +images from multiple providers in the same component, as you can specify options |
| 46 | +for each provider separately. |
| 47 | + |
| 48 | +```tsx |
| 49 | +<Image |
| 50 | + src="https://example.com/image.jpg" |
| 51 | + operations={{ imgix: { flip: "h" }, bunny: { flop: true } }} |
| 52 | +/> |
| 53 | +``` |
| 54 | + |
| 55 | +The operations are all type-safe, with JSDoc comments and TypeScript definitions |
| 56 | +for all supported operations. This means you can get autocompletion and type |
| 57 | +checking for all operations. |
| 58 | + |
| 59 | +### Provider options |
| 60 | + |
| 61 | +*Supported frameworks: All except `webc` and `lit`.* |
| 62 | + |
| 63 | +The new `options` property allows you to specify custom options for each |
| 64 | +provider. This is similar to the current `cdnOptions` property, but with |
| 65 | +type-safe support for all options of each provider. This allows you to specify |
| 66 | +options such as account IDs and domains for each provider. |
| 67 | + |
| 68 | +### Fallback providers |
| 69 | + |
| 70 | +*Supported frameworks: All. The `astro` and `nextjs` frameworks default to |
| 71 | +the framework's image provider as fallback.* |
| 72 | + |
| 73 | +The new `fallback` property allows you to specify a fallback provider for each |
| 74 | +image. This allows you to use auto-detection for image CDNs as now, but also |
| 75 | +specify a fallback provider for local images and images from unknown providers. |
| 76 | +This is useful if you have a mix of images from different sources, and want to |
| 77 | +ensure that all images are handled correctly. For example, you may have a |
| 78 | +Contentful blog hosted on Netlify, with images that are mostly hosted on |
| 79 | +Contentful (a supported CDN), but also some images from third-parties or your |
| 80 | +own server. You can specify Netlify as the fallback provider so that it uses the |
| 81 | +Netlify Image CDN for all images that are not from Contentful or another |
| 82 | +supported provider. This will be all handled automatically. |
| 83 | + |
| 84 | +## Base component |
| 85 | + |
| 86 | +*Supported frameworks: All except `webc`, `lit` and `angular`.* |
| 87 | + |
| 88 | +Previously, the `Image` and `Source` components always loaded support for every |
| 89 | +provider, even if you specified a single provider or custom transformer. This is |
| 90 | +fine if you are using auto-detection, but many people wanted to use the |
| 91 | +components in a more custom or modular way. The new base components allow you to |
| 92 | +use the Unpic component without any of the automatic detection and transform |
| 93 | +logic. You can provide your own transformer, or use a single, tree-shakable |
| 94 | +provider import. This is useful if you are using a single provider, or if you |
| 95 | +are building a custom component based on Unpic. |
| 96 | + |
| 97 | +```tsx |
| 98 | +// Import from the `/base` subpath |
| 99 | +import { Image } from "@unpic/react/base"; |
| 100 | +// Import the transformer for the provider you are using |
| 101 | +import { transform } from "unpic/providers/imgix"; |
| 102 | + |
| 103 | +export const Hero = () => ( |
| 104 | + <Image |
| 105 | + src="https://images.unsplash.com/photo-1734108039189-f6c123288381" |
| 106 | + transformer={transform} |
| 107 | + operations={{ sepia: 50 }} |
| 108 | + /> |
| 109 | +); |
| 110 | +``` |
| 111 | + |
| 112 | +The `operations` and `options` properties are still type-safe and inferred from |
| 113 | +the transformer, and you don't need to specify the provider name in the |
| 114 | +`operations` object. |
| 115 | + |
0 commit comments