Feat: React 19 Upgrade

[kierancap]

Why

Closing #2341

What

Main changes:

• Removed all usage of forwardRef - As per the React docs, will be fully deprecated in future.
• Replaced all ref fields with the valid React Types - Any polymorphic components were set as any for the RefObject generic.
• Added valid initial values for all usages of useRef which were missing inits.
• Refactored the SpringContext to resemble a more sensible Context structure

Checklist

• Removed forwardRef
• Added correct ref fields
• Added initial values for useRef
• Refactored SpringContext

Additional Comments

This was based on this PR: #2349

As the PR and issue have been open for a good while now, it's obvious that no further development was going to happen - I'm currently blocked by this library, so I thought it'd try and help with moving this forward.

PR Diff

I'm unsure as to why the diff is heavily focused on formatting changes - I was sure to run prettier via the NPM script before submitting this PR. Happy to outline all the direct code changes if necessary.

[changeset-bot]

⚠️ No Changeset found

Latest commit: d052797

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
react-spring	✅ Ready (Inspect)	Visit Preview	Apr 20, 2025 9:41am

[thomazcapra]

👀

[abriginets]

@joshuaellis apologies for reaching out directly, but if you have some time, could you please take a look at this PR? We'd really appreciate your review when it’s convenient for you. Thanks a lot!

[johansunden]

Is @joshuaellis the only person who can review this? Would be great to get this in and not have it end up like the other attempt at upgrading to React 19

[kierancap]

Is @joshuaellis the only person who can review this? Would be great to get this in and not have it end up like the other attempt at upgrading to React 19

Yeah... I was hoping that the fact this PR passed all the tests would mean it'd get reviewed sooner rather than later. At this rate someone may as well fork this library fully and re-distribute it. Shambolic from the maintainers if I'm honest

[joshuaellis]

Hey, firstly – sorry I recently started a family & I also have a FT job so unfortunately, open-source software is taking a back seat. Secondly, thanks for the PR! Here's some follow up questions:

• Have you tried running this library with a react16|17|18 app? I'm wondering if these changes to forwardRef will mean this is a breaking change to the library?
• I think your changes to SpringContext are probably breaking changes because previously <SpringContext> was possible – now it's not? Maybe i'm misunderstanding the change though.
• "Shambolic from the maintainers if I'm honest" – how many maintainers do you think react-spring has?

Also, some other things i think we're missing from this is:

• updating the package.json of the packages to add react19 as an acceptable peer-dep
• There's a console warning about act in the useTransition test, be good to tackle that

Otherwise, this looks super promising!

[kierancap]

Appreciate the reply, great to hear from you. Congratulations on the family news!

I'd be happy to test out those changes regarding older version of React once I get the opportunity.

The context change is breaking due to the nature of changing the Provider to be separate from the instantiated context itself. It follows the Context Provider pattern; Here's an article around it - I find it to be way better for DX. If you'd prefer it to remain as it was previously, it may involve a bit more in-depth tinkering due to the type errors generated from the current approach. I'm not torn on either approach - As long as the resulting code is readable and maintainable for future development. I can take a look at refactoring the types and structure to potentially allow for a single object to safely contain all the necessary functionality.

In terms of my comment about the maintenance of this project, it's more targeted to the complete lack of communication towards the community. The main issue attached to this PR has hundreds of people waiting for this change, after you had mentioned about updating it in December. Granted I appreciate your new family changes meant you were not available, but I do think that the lack of communication severely impacted this whole process.

As I was forced to make this change due to a work dependancy on a 1st party library, I cannot guarantee that I'll have time to look at this in the short term. I'll do my best.

Hopefully I can have time next week to delve deeper into the good points you mentioned.

I'll try to keep this PR up to date with that

[joshuaellis]

The context change is breaking due to the nature of changing the Provider to be separate from the instantiated context itself. It follows the Context Provider pattern; Here's an article around it - I find it to be way better for DX. If you'd prefer it to remain as it was previously, it may involve a bit more in-depth tinkering due to the type errors generated from the current approach. I'm not torn on either approach - As long as the resulting code is readable and maintainable for future development. I can take a look at refactoring the types and structure to potentially allow for a single object to safely contain all the necessary functionality.

tbf i'm kind of happy to remove it, I don't think anyone uses it. Also it breaks everything in RCS for imo not a lot of gain...

Hopefully I can have time next week to delve deeper into the good points you mentioned.

sounds good! ✨

[kierancap]

Just had a read through some other known React 19 OSS projects - They seem to be using forwardRef still - Even though the React team has specifically mentioned it being removed in future and is currently labeled as deprecated. In that case I'll revert my forwardRef changes as it should still function for the current React 19 version - Will get to that next week 😃

[dagatsoin]

Hi, just a quick first pass. I stopped on the forwardRef as it has already a big impact. Tell me your though.

[kierancap]

Right people - I've now made these changes:

• Reverted removal of forwardRef (yuck)
• Added React 19 as a Peer Dep to all the packages
• Fixed the act() error from the tests

[DominikScholz]

Would be awesome if this could be merged in!, only thing missing for my company to move to react 19, any way I can help?

[smollweide]

@kierancap

First of all, thank you for the pull request!
However, it seems that the ref is not working as expected.

Issue
The ref should point to the DOM element so that we can access its properties like getBoundingClientRect(). Currently, it's null.

Example
Here's a minimal example to illustrate the issue. The button's width should be displayed when it's clicked:

export function RefAnimated() {
  const ref = useRef<HTMLButtonElement>(null);
  const [_, setCounter] = useState(0);
  const Button = animated('button');
  
  return (
    <Button
      ref={ref}
      onClick={() => setCounter((v) => v + 1)}
    >
      With ref (width:{' '}
      {ref.current?.getBoundingClientRect().width || 0}px)
    </Button>
  );
}

When clicking the button, the width should update, but currently it does not behave as expected.

[kierancap]

@kierancap

First of all, thank you for the pull request! However, it seems that the ref is not working as expected.

Issue The ref should point to the DOM element so that we can access its properties like getBoundingClientRect(). Currently, it's null.

Example Here's a minimal example to illustrate the issue. The button's width should be displayed when it's clicked:

export function RefAnimated() {
  const ref = useRef<HTMLButtonElement>(null);
  const [_, setCounter] = useState(0);
  const Button = animated('button');
  
  return (
    <Button
      ref={ref}
      onClick={() => setCounter((v) => v + 1)}
    >
      With ref (width:{' '}
      {ref.current?.getBoundingClientRect().width || 0}px)
    </Button>
  );
}

When clicking the button, the width should update, but currently it does not behave as expected.

Hey! Thank you for taking the time to test this - As mentioned in a comment left after you, I had missed a forwardRef on the withAnimated function. Which may have caused this issue. Would you mind retesting this with the latest commit? 8d61c6d

Thank you!

[kierancap]

Hey @joshuaellis - Apologies for the direct ping!

Just wondering of next steps for this? Are you happy to override the reviewing/approval or do I need to wait for re-review from the previous reviewers?

Thanks mate!

[joshuaellis]

I'm OOO till Tuesday, but if the CI passes we can cut a beta, people can test it and report back any issues? Give it a couple of weeks before going to stable.

[kierancap]

I'm OOO till Tuesday, but if the CI passes we can cut a beta, people can test it and report back any issues? Give it a couple of weeks before going to stable.

Sounds like a plan! The CI is currently failing early due to me not pushing an updated lock (post updating the peer deps). I'll update that today - Then on tuesday we can see about doing that beta release!

Thank you

EDIT: Have pushed that lock file fix - Hopefully will let the CI pass properly (Can't tell until we try it!)

[VincentHui]

glorious PR! I've watched and hoped for a long time and just want to say thanks. I'm checking out this branch and giving it a look just in case

[ivtpz]

Thanks for making this update!

Is there a beta version now to test with?