Skip to content

v7.0.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 26 Oct 18:00
v7.0.0
3d2de78

Overview

Next Cloudinary 7 brings the Cloudinary Video Player v4 to CldVideoPlayer, upgrades the underlying @cloudinary-util/url-loader to v6, and updates the supported versions of Next.js, React and Node.js.

Highlights:

  • New video player. CldVideoPlayer now uses Cloudinary Video Player v4. Custom posters saved in the Video Player Studio are shown automatically.
  • Easier to use in the App Router. The client components now include 'use client', so you can use them directly in Server Components without adding 'use client' yourself. If you pass event handlers or a render function to a component, use it in a Client Component.
  • Bug fixes, including the video player not returning after navigating away and back, repeated q_auto in video URLs, and overlay text containing commas.

This is a major release with breaking changes. Start with the Requirements, then check the breaking changes for the components you use. If you can't upgrade yet, v6 remains available and continues to work as before.

Requirements

  • Next.js 16 or later (#670)
  • React 18.2 or React 19 (#670)
  • Node.js 22 or later (#670)

Next.js 15 reached end-of-life on October 21, 2026, and Node.js 20 reached end-of-life on April 30, 2026. Projects on older versions can stay on v6.

Breaking changes

CldUploadWidget, CldUploadButton

  • Removes the deprecated onUpload callback. Use onSuccess instead (#667). The second argument is now an options object:

    // Before
onUpload={(result, widget) => { widget.close(); }}

// After
onSuccess={(result, { widget }) => { widget.close(); }}

CldVideoPlayer

  • Upgrades the Cloudinary Video Player from v1.11.1 to v4.1.2 (#665). This spans three major versions of the player, so if you customize the player with your own CSS, check that it still applies.
  • The player's CSS is now Video Player v4's. If you import next-cloudinary/dist/cld-video-player.css, it updates automatically.

Package

  • The package now defines an exports map (#520). Import from the supported entry points only:

    • next-cloudinary
    • next-cloudinary/dist/cld-video-player.css (or next-cloudinary/cld-video-player.css)

    Imports of other internal paths, such as next-cloudinary/dist/index.js, no longer resolve.

CldImage, CldOgImage, getCldImageUrl, getCldOgImageUrl, getCldVideoUrl (types)

@cloudinary-util/url-loader v6 rewrites its TypeScript types. Most code compiles unchanged, but a few things that the v6 types accepted are now type errors. Most of them never worked at runtime:

  • Removes the overlay option. Use overlays (an array) instead. overlay was accepted by the types in v6 but was never applied.
  • assetType now only accepts supported values: 'image', 'images', 'video', 'videos' or 'all'. Other values such as 'raw' already threw an error at runtime.
  • The analytics argument of getCldImageUrl and getCldVideoUrl no longer accepts false. Passing false never disabled analytics in v6; remove the argument.
  • CloudinaryLoaderCldOptions now requires src (#552). This only affects code that calls cloudinaryLoader directly or uses this type.
  • If you import option types directly from @cloudinary-util/url-loader, some type names and shapes have changed.

Known limitation

CldVideoPlayer with an explicit aspectRatio: with Video Player v4, setting the aspectRatio prop makes the poster image fail to load (the video itself plays normally). As a workaround, also set a crop mode, for example cropMode="fill". Note that this also crops the video to that ratio, and cropMode isn't in the TypeScript types yet, so in TypeScript projects pass it with a cast, for example {...({ cropMode: 'fill' } as object)}. A fix is planned for a follow-up release.

New

  • Custom posters from the Video Player Studio are shown automatically in CldVideoPlayer (#665, #663). Other saved player settings aren't applied yet.
  • 'use client' is built in to CldImage, CldUploadButton, CldUploadWidget and CldVideoPlayer, so they can be used directly in App Router Server Components (#137). If you pass event handlers or a render function to a component, use it in a Client Component.
  • seed option for fillBackground: pass a number to regenerate a different generative fill result, or to return a previously generated one. In v6 it was ignored.
  • More complete TypeScript types: options that already worked at runtime but were missing from the types, such as hue and noise, are now included.
  • Improved TypeScript and ESM support in the published package (#520).

Fixes

  • CldVideoPlayer: re-initializes correctly after it's unmounted and mounted again (for example when navigating away and back), and no longer leaves old player instances behind (#669, #572)
  • CldVideoPlayer: q_auto no longer repeats in video URLs when using a transformation array (#651)
  • Overlays: text containing multiple commas no longer breaks the image URL, in CldImage, CldOgImage, getCldImageUrl and getCldOgImageUrl (#590)
  • cloudinaryLoader: removes a @ts-ignore by fixing the underlying type mismatch (#425)
  • Package: removes two broken video player icon files that previous releases shipped (#668)
  • TypeScript: compatible with React 19's types

Upgrading

  1. Check your project is on Next.js 16, React 18.2 or 19, and Node.js 22 or later.

  2. Install the new version:

    npm install next-cloudinary@7

  3. Replace any onUpload with onSuccess, as shown above.

  4. If you get new TypeScript errors, check the type changes above.

  5. If you use CldVideoPlayer with aspectRatio, check the poster (see Known limitation).

For the full upgrade guide, see Upgrade from version 6 to version 7 in the Next.js SDK docs.

Full changelog: v6.19.3...v7.0.0

Assets 2
Loading