feat: stable release

[ascorbic]

This is a major update, with changes to the API of all frameworks. This will not affect you if you are just using the components with default options, but if you are passing custom transformers or specifying the CDN then you will need to update your code.

To try it, install the preview build from pkg.pr.new

The new provider transformers and types are implemented in ascorbic/unpic#133

Breaking changes

• The cdnOptions property has been removed. Use the new options property instead.
• The transformer property has been removed from the default Image component. Import the 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.
• The cdn property has been removed. Either use the new fallback property or import the base component and pass a single provider to it.

Changes

Most of the changes are because of a new approach to handling individual image CDNs and providers in the base Unpic library. This is designed to make Unpic more flexible, efficient and modular. It also introduces support for type-safe custom operations and options for each provider.

Provider operations

Supported frameworks: All except webc and lit.

The new operations property allows you to specify custom operations for each provider. Many image CDNs support dozens of custom operations. Previously these were hard to use with Unpic. The new operations property gives type-safe support for all supported features of each provider. This works even if you have images from multiple providers in the same component, as you can specify options for each provider separately.

<Image
  src="https://example.com/image.jpg"
  operations={{ imgix: { flip: "h" }, bunny: { flop: true } }}
/>

The operations are all type-safe, with JSDoc comments and TypeScript definitions for all supported operations. This means you can get autocompletion and type checking for all operations.

Provider options

Supported frameworks: All except webc and lit.

The new options property allows you to specify custom options for each provider. This is similar to the current cdnOptions property, but with type-safe support for all options of each provider. This allows you to specify options such as account IDs and domains for each provider.

Fallback providers

Supported frameworks: All. The astro and nextjs frameworks default to the framework's image provider as fallback.

The new fallback property allows you to specify a fallback provider for each image. This allows you to use auto-detection for image CDNs as now, but also specify a fallback provider for local images and images from unknown providers. This is useful if you have a mix of images from different sources, and want to ensure that all images are handled correctly. For example, you may have a Contentful blog hosted on Netlify, with images that are mostly hosted on Contentful (a supported CDN), but also some images from third-parties or your own server. You can specify Netlify as the fallback provider so that it uses the Netlify Image CDN for all images that are not from Contentful or another supported provider. This will be all handled automatically.

Base component

Supported frameworks: All except webc, lit and angular.

Previously, the Image and Source components always loaded support for every provider, even if you specified a single provider or custom transformer. This is fine if you are using auto-detection, but many people wanted to use the components in a more custom or modular way. The new base components allow you to use the Unpic component without any of the automatic detection and transform logic. You can provide your own transformer, or use a single, tree-shakable provider import. This is useful if you are using a single provider, or if you are building a custom component based on Unpic.

// Import from the `/base` subpath
import { Image } from "@unpic/react/base";
// Import the transformer for the provider you are using
import { transform } from "unpic/providers/imgix";

export const Hero = () => (
  <Image
    src="https://images.unsplash.com/photo-1734108039189-f6c123288381"
    transformer={transform}
    operations={{ sepia: 50 }}
  />
);

The operations and options properties are still type-safe and inferred from the transformer, and you don't need to specify the provider name in the operations object.

[changeset-bot]

🦋 Changeset detected

Latest commit: 13b27cd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@unpic/svelte	Major
@unpic/react	Major
@unpic/core	Major
@unpic/angular	Major
@unpic/astro	Major
@unpic/lit	Major
@unpic/preact	Major
@unpic/qwik	Major
@unpic/solid	Major
@unpic/vue	Major
@unpic/webc	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for unpic-docs ready!

Name	Link
🔨 Latest commit	13b27cd
🔍 Latest deploy log	https://app.netlify.com/sites/unpic-docs/deploys/678d19a9ef6689000818835a
😎 Deploy Preview	https://deploy-preview-748.preview.unpic.pics
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 99 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[netlify]

✅ Deploy Preview for unpic-angular ready!

Name	Link
🔨 Latest commit	13b27cd
🔍 Latest deploy log	https://app.netlify.com/sites/unpic-angular/deploys/678d19a9ce7afb0008ca2287
😎 Deploy Preview	https://deploy-preview-748--unpic-angular.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[netlify]

✅ Deploy Preview for unpic-next ready!

Name	Link
🔨 Latest commit	13b27cd
🔍 Latest deploy log	https://app.netlify.com/sites/unpic-next/deploys/678d19a9f9e6a0000855951b
😎 Deploy Preview	https://deploy-preview-748--unpic-next.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[benmccann]

I think it'd probably be nice to have a way to be able to set a default transformer. I haven't used CDNs much, so don't know how much of an issue it is to have to set the transformer each time you have an image, but it feels like it'd be easier to do it just once for the whole app.

[ascorbic]

@benmccann it's hard to set defaults outside of a metaframework. Even using env vars has caused issues in the places I tried it, because of platform-specific differences. In most cases the best approach is to create your own wrapper component, though obviously the syntax for that varies by framework too. That lets you import just the transformer you need.

[benmccann]

Yeah, wrapper component seems like a good solution. Might be worth explicitly suggesting that in the docs if it's not already

[ascorbic]

@benmccann I added exactly that this morning! https://deploy-preview-748.preview.unpic.pics/custom/