react-spring

In react-spring, a target is a react reconciler (also known as a react renderer). It is a custom renderer responsible for creating, updating, and removing elements within a specific environment.

While react-spring can be used for server-side rendering, the term 'target' specifically refers to the platform-specific reconciler being used. The two primary built-in targets are:

• web: Uses react-dom to handle DOM elements.
• three: Uses react-three-fiber to handle Three.js elements.

When you use a target, you get access to a set of animated components (like animated.div for web) that are optimized for that specific reconciler.

The SpringRef is React Spring's imperative API, allowing you to control animations outside of the standard declarative React render cycle.

For functional components, the recommended way to initialize it is via the useSpringRef hook. You then pass this ref to a useSpring call to link the imperative controller to the spring animation.

For class components or environments where hooks are unavailable, you can initialize it by calling the SpringRef() function directly.

import { animated, useSpring, useSpringRef } from '@react-spring/web'

function MyComponent() {
  const api = useSpringRef()

  const props = useSpring({
    ref: api,
    from: { opacity: 0 },
    to: { opacity: 1 },
  })

  return <animated.div style={props}>Hello World</animated.div>
}

The migration uses @react-router/fs-routes to preserve existing Remix v2 flat-route file naming, ensuring URLs remain byte-identical.

Key Route Mappings:

• _index.tsx $\rightarrow$ / (Landing page)
• $.tsx $\rightarrow$ (Catch-all 404) Splat route
• docs.tsx $\rightarrow$ /docs (Pathless layout for children)
• docs._index.mdx $\rightarrow$ /docs (Docs landing)
• docs.getting-started.mdx $\rightarrow$ /docs/getting-started
• examples.tsx $\rightarrow$ /examples

Route Invariants:

• All migrated routes (except the 404 splat) must return HTTP 200.
• The flatRoutes() configuration must ignore dotfiles and CSS modules (e.g., ignoredRouteFiles: ['**/.*', '**/*.css']) to prevent them from being treated as routes.

React Spring provides both Hook-based and Component-based APIs for its animations.

• Hooks (Recommended): The library recommends using the hook version (e.g., useSpring) as it aligns better with modern React patterns.
• Components: The component version (e.g., <Spring />) is provided primarily for compatibility with older codebases or class components. It acts as a light wrapper around the hook logic and uses a render props pattern to expose the animated styles.

Fluids is a lightweight glue layer used throughout react-spring to implement an observable, event-driven system.

It allows parent nodes to send events to child nodes. For example, when a FluidObserver observes an event, it can trigger an action in its child. In the context of SpringValue, an event can trigger the _start function, which initiates the animation of the value and subsequently updates the attached animated DOM node.

React Router 7 framework mode typically requires explicit route configuration. To preserve the Remix v2 flat-file naming convention (e.g., docs.components.use-spring.mdx resolving to /docs/components/use-spring) without renaming files, use @react-router/fs-routes in your app/routes.ts file.

// docs/app/routes.ts
import { flatRoutes } from '@react-router/fs-routes'
import { type RouteConfig } from '@react-router/dev/routes'

export default flatRoutes() satisfies RouteConfig

Easings can only be used when the duration property is also provided in the config object. You can import generic easings from the easings object.

import { easings } from '@react-spring/web'

The transitions object returned by useTransition is a function that accepts a render function. This render function is used to map your data items to animated components.

The render function signature is: render(style, item, transitionState, index) => ReactNode

• style: An object containing the current spring values (e.g., opacity, transform). The values in this object correspond to the state of the animation (e.g., if the item is ENTERING, it uses the keys from the enter property of your config).
• item: The actual data item from your array (e.g., if your array is [1, 2, 3], the item will be a number).
• transitionState: Information about the current state of the transition for that item.
• index: The index of the item in the array.

transitions((style, item, transitionState, index) => (
  <animated.div style={style}>
    {item}
  </animated.div>
))

The testing infrastructure has moved from Jest + Cypress to Vitest + Playwright (Chromium).

Key changes:

• jest.config.js is now vitest.config.ts.
• The jsdom environment has been replaced by Chromium via Playwright.
• E2E tests now use Vite served programmatically with a Vitest E2E project instead of start-server-and-test + Cypress.

What remains the same:

• Animation testing helpers (advance, advanceByTime, advanceUntil, advanceUntilIdle, advanceUntilValue, getFrames, countBounces, setSkipAnimation) are unchanged and do not require rewriting.
• packages/core/test/setup.ts uses the same helpers, though they now provide Vitest globals instead of Jest globals.