For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

React 19

Peer dependencies and breaking changes for React 19.

Frakment targets React 19. Most components are drop-in compatible with React 18, but a few rely on React 19 features. This page covers what changes, what breaks, and how to migrate.

Prerequisites

  • React 19.0 or newer
  • TypeScript 5.7 or newer
  • Node.js 20 or newer

Peer dependencies

Frakment components expect React 19. If you use the engine packages, add both as peers:

package.json
{
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

@frakment/ai supports React 19.

Components that require React 19

Most primitives (button, input, card, dialog) work on React 18.3. The following components require React 19:

ComponentReact 19 feature
message-animateduseOptimistic for streaming UI
traceuseTransition for collapse animation
code-blockRef cleanup function
bubbleRef as a prop (no forwardRef)

The rest compile on React 18.3 but are only tested on React 19.

Breaking changes to watch

ref as a prop

React 19 allows ref without forwardRef. Frakment components use this in new files. Old files that still use forwardRef still compile, but the wrapper is redundant.

React 18, with forwardRef:

tsx
const Button = React.forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => (
  <button ref={ref} {...props} />
));

React 19, ref as a prop:

tsx
function Button({ ref, ...props }: ButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
  return <button ref={ref} {...props} />;
}

Ref cleanup

ref callbacks can return a cleanup function. Returning a value in React 18 triggers a warning:

tsx
<div ref={(node) => {
  setup(node);
  return () => teardown(node);
}} />

The use hook

Some engine files use use(Promise) for async boundaries. It works in React 19 only.

useFormStatus and useActionState

Form primitives in Frakment use these hooks. They do not exist in React 18.

Migrating from React 18

Bump React

$ npm install react@^19 react-dom@^19

Bump types

$ npm install -D @types/react@^19 @types/react-dom@^19

Reinstall components

For every installed component, re-run:

$ npx frakment@latest add <component> --overwrite

This pulls the React 19 compatible version from the registry.

Typecheck

$ npx tsc --noEmit

Look for ref callback warnings and forwardRef removals.

Common errors

React 19 removes the deprecated forwardRef calls from the default export. Use the new ref prop style instead.

Two React copies are installed. Check npm ls react. Deduplicate by hoisting React to the root of the workspace.

Next