Migrating from React

1. Remove react and react-dom from dependencies. Add @vidact/runtime.
2. Remove @vitejs/plugin-react. Add @vidact/vite and put vidact() in plugins.
3. Add @vidact/react-types and set jsx: "preserve" and jsxImportSource: "@vidact/react-types" in tsconfig.json.
4. Replace createRoot(host).render(<App />) with mountCompiled(App, host).

Leave the import { useState } from 'react' lines alone. The plugin resolves them.

Run the build. Every place Vidact cannot compile is reported with a file, line, and reason. Work through the list; the sections below cover the common ones.

Class components are not supported. Convert them to functions with hooks. The one class that has no direct hook equivalent, the error boundary, becomes a call to errorBoundary:

import { errorBoundary } from '@vidact/runtime'export function Boundary({ children }: { children: VidactNode }) {  return errorBoundary(    () => children,    (error, reset) => <ErrorFallback error={error} onRetry={reset} />,  )}

See Error handling.

There is no React element tree at runtime, so code that inspects or rewrites children has nothing to work with:

Children.toArray, cloneElement, and isValidElement exist in a bounded form for compiled values, but a component that depends on walking arbitrary children needs a different API.

React re-runs the component body, so some code relies on it: document.title = title in the body, ref.current = value assignments, mutating a module-level cache, or calling setState conditionally in render. In Vidact the body runs once and any mutation of props, outer variables, or previously rendered values in the body is a compile error (DestructiveRenderMutation).

Move the code into useEffect, useLayoutEffect, or an event handler, or compute the value directly if it is derived.

Handlers receive native DOM events. For most code this changes nothing. Look for:

• event.nativeEvent (drop the .nativeEvent)
• event.persist() (delete)
• Event handlers on a portal's DOM ancestors expecting to receive events from inside the portal (attach inside instead)
• event.currentTarget casts, which are usually no longer needed because event.target is already typed

Anything from this list is a compile error until the matching feature is on:

The error message names the flag.

Vidact compiles your application code. It also compiles packages that ship React-shaped source, such as many headless UI libraries, when their package metadata declares React and their code stays inside the supported subset. Precompiled packages that import React internals, or component libraries that depend on React.Children and cloneElement, will not work and are reported at build time.

For a package that ships compatible source but lacks React metadata, add it with the includeDependencies option. See @vidact/vite.

These will not produce errors. Know about them before you ship.

No re-renders. memo, useMemo, and useCallback are accepted but do nothing for performance. A component that relied on re-rendering to recompute something in its body will recompute only if the compiler sees the dependency in an expression. Effects and derived expressions are the reliable tools.

Synchronous updates by default. Without concurrent, every update is applied synchronously and atomically at the end of the event. There is no time slicing.

No Strict Mode double-invocation. Development mode does not run components and effects twice.

Portals bubble physically. A click inside a portal does not reach a React-style ancestor handler.

HMR resets state. Replacing a module disposes its components. Persist state in an external store if you want it to survive edits.

useId values differ from React's. They are stable between server and client but not the same strings React would generate.

Run your existing test suite. Tests that render with React Testing Library need to be pointed at Vidact's mount and act; see Testing. Snapshot tests of React element trees will not work, since there is no element tree; snapshot the DOM instead.