v7.0.0

[colbyfayock]

Includes

• Switch to Preconstruct for library building #520
• Move @tsconfig/recommended to devDeps #522
• Include NextJS test app as pnpm workspace #521
• Upgrades Util which refactors type system, removing Zod dependencies, and exporting plugins a bit differently refactor: migrate Zod to pure TS w/ JSDoc, improve type safety and simplify parsing cloudinary-util#217

Resolves

Fixes #441 - v7
Fixes #137 - "use client"
Fixes #519 - Bundle Size

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
next-cloudinary	Ready	Preview	Oct 12, 2026 8:36pm UTC

[PaulBoye-py]

Hi @eportis-cloudinary, a follow-up to my scope comment above, now that testing is done on my side.

Ready for your review

• #667: removes the deprecated onUpload callback (docs updated to onSuccess)
• #668: removes the missing icon files from the build and package exports, and makes the build fail if a download fails

Both target beta, pass CI, and aren't part of the stack, so they can be merged on their own.

Asset-Saved Settings (#663)

I tested this with a video that has a custom poster saved in the Video Player Studio. With player v4 (#665), CldVideoPlayer shows the custom poster without any further changes; with v1 it shows the first frame. Other saved settings (colors, controls) still need the switch to cloudinary.player(), which I've noted on the issue as a follow-up.

Breaking changes for the 7.0.0 release notes

I compared every public type between 6.19.3 and beta, and compiled common v6 usage against both. This is the full list I found:

1. Video Player v4: the default player appearance changes.
2. Explicit aspectRatio breaks the video poster with player v4 (details in feat: upgrade Cloudinary video player from v1 to v4 #665). Workaround: also set cropMode. A fix is possible; see the question below.
3. Package exports map: imports from paths other than next-cloudinary and next-cloudinary/dist/cld-video-player.css (for example next-cloudinary/dist/index.js) no longer resolve.
4. onUpload removed (feat!: remove deprecated onUpload callback from CldUploadWidget #667): use onSuccess. The second argument is now an options object: onSuccess={(result, { widget }) => ...}.
5. overlay (singular) removed from the types: use overlays. It was never applied at runtime in v6, so only the TypeScript error is new.
6. assetType only accepts supported values (it was any string). Unsupported values such as 'raw' already threw at runtime in v6.
7. The analytics argument no longer accepts false. In v6, false was accepted by the types but didn't actually turn analytics off.
8. CloudinaryLoaderCldOptions now requires src (from feat: add src type to CloudinaryLoaderCldOptions interface #552). This only affects code calling cloudinaryLoader directly, which isn't documented.

New options (such as displace, hue, noise and zoompan for videos) aren't breaking.

Still waiting on you

• feat: upgrade Cloudinary video player from v1 to v4 #665: unstack it and merge it into beta on its own, or keep the stack for the release?
• aspectRatio poster fix: in url-loader's getVideoPlayerOptions, or locally in CldVideoPlayer?
• The other questions in my scope comment ([Feature] CldUploadButton and CldUploadWidget refraining from stealing focus #662, [Bug] playerRef attribute is not a valid Ref  #575, supported versions).

Once these are settled, I can prepare the release notes from the list above.

[eportis-cloudinary]

#665: unstack it and merge it into beta on its own, or keep the stack for the release?

Unstack it and merge! Sorry for stacking when it didn't really make sense.

aspectRatio poster fix: in url-loader's getVideoPlayerOptions, or locally in CldVideoPlayer?

I think this is already in the latest shipped version of url-loader? cloudinary-community/cloudinary-util@c595c99

#662 (upload widget steals focus): the cause is that the widget is created as soon as the script loads. We could either create it only when it's opened, by default in v7 (a breaking change), or keep the current default and add an opt-in prop in a later minor release (non-breaking). Either is fine with me.

Are there performance implications to creating it lazily? If not, it seems like a cleaner solution than a prop/option, and a breaking/major release seems like the perfect time to ship it.

#575 (playerRef not set on mount): you mentioned the forwardRef fix belongs in v7. The contributor's #598 still targets main and has conflicts. Should we ask them to rebase onto beta, or leave this for later?

It looks like you asked @SK1965 a couple weeks ago, and they haven't responded. Could you perhaps try to rebase? And if we are able to merge this for v7 still give them credit of course.

Supported versions: peer dependencies still allow Next.js 12+ and React 17+, but CI only tests Next.js 16 and React 19. A major release is the time to raise the floor if you want to (for example Next.js 14+ and React 18+), and to add engines.node (>=20, which matches CI).

Very happy to raise floors to any still-supported versions of these dependencies.

[PaulBoye-py]

hi @eportis-cloudinary, following up on supported versions for v7, here's a proposal based on the official support status as of today:

• Next.js ^16: Next.js 15 reaches end-of-life on October 21, before v7 ships, and CI only tests Next.js 16. Users on Next.js 12–15 can stay on v6. (Next.js support policy)
• React ^18.2.0 || ^19: the same range Next.js 16 itself accepts, so we're never stricter than Next.js. (React versions)
• engines.node: ">=22": Node.js 20 reached end-of-life on April 30, 2026. The CI test matrix would move from Node 20/22 to 22/24. (Node.js release schedule)

These are breaking changes, so I'll add them to the release notes list.

One follow-up outside v7: the docs site still runs Next.js 14 and React 18, so it should be upgraded separately. It still builds, so it doesn't block the release.

If this looks right, I'll make these changes in one PR against beta.