Readiness: Implemented

Migrate

Migrating to uf

uf migrate --dry-run
uf migrate
uf install
uf check
uf lint
uf test

The command reads Babel, Flow, Prettier, ESLint, Jest and Vite configuration without executing their modules. Named package scripts become tasks; common test, lint, format and build commands become uf commands. Other task bodies stay verbatim. Basic Jest globals gain explicit imports from @uniflowed/test, preserving application imports and comments. Jest mocks, timers, custom matchers and non-default settings stay in the report for review.

.uf/migration-report.json contains the proposed edits, original contents and every setting that could not be mapped. Only a fully replaced static configuration file is removed. JavaScript configuration modules remain until you review their imports and side effects. Existing uf settings win: conflicting values are reported and retained. Install lifecycle scripts require an explicit decision before uf install accepts them.

The three CI consumers cover Flow/Babel/Jest/ESLint, Vite React and create-react-app through install, check, lint and test. Framework-specific entry points, HTML placeholders, environment variables, deployment and Next.js routes still need the steps below.

Upgrading an existing uf project

uf codemod --to 0.0.0-alpha.41 --dry-run
uf codemod --to 0.0.0-alpha.41

The previous version comes from the installed node_modules/@uniflowed/core package. Use --from 0.0.0-alpha.32 when that installation is unavailable. This catalog covers alpha releases through the installed binary's version and refuses downgrades or a newer target.

The first codemod moves env.toolchain to role-specific runtime and package manager declarations, builder.module to build.builder, pm.packageManager to the top-level key, and the object form of test.runner to runner: "uf" plus its explicit target override. Multiple runtimes, conflicting values and non-default legacy runner options require a decision and stay unchanged. Flow-parser source ranges preserve comments and unrelated formatting; applying the same migration twice is unchanged.

The 0.10.0 codemod removes the configuration keys nothing read — the list is removed keys — and any section they leave empty. jsxImportSource: "@uniflowed/jsx-runtime" goes with them, since 0.10 reads the key and refuses that value. taskRunner.allowPackageScripts: false is kept and reported: 0.10 enforces it, so a task with no command stops the run.

What you will be able to do: decide whether your application can move today, write the uf.config.js it needs, move a create-react-app, Vite or Next.js application step by step — config, scripts, imports, routes, tests and deploy — and know what still differs afterwards.

What you need first: uf installed, and the application you mean to move, with its tests passing. If it is written in TypeScript, read Flow and TypeScript first.

Where your application is covered

Read Before you start whatever you have, then the row for it:

Before you start

Four questions decide whether the move is a week of work or not possible yet. Answer them before you convert a file.

Is it TypeScript? uf transforms .js, .jsx, .mjs and .cjs. uf check does not read a .ts or .tsx file, an import of one is typed any, and the router has no $page.ts. Moving means converting the application, not adding uf beside tsc — Converting the types is what that takes.

What do your dependencies declare? uf check types a package that ships Flow, and a package that ships TypeScript declarations — its own, or an @types package's — through a Flow translation of them. What the translation cannot say is any, and the report counts it per package; a package with neither is any and named. What an import resolves to is the whole table.

Where does it deploy? uf build --adapter writes eight targets: node, bun, deno, container, edge for Cloudflare Workers, serverless for AWS Lambda, vercel (Vercel's Build Output API), and static. None of the server targets has been deployed to its real platform by uf's own pipeline yet (#956), serverless buffers a streamed response, and there is no Netlify adapter. A static host runs no route handler, middleware or server action, and a build that has one is refused rather than uploaded with a hole in it.

Are the packages you need on npm? @uniflowed/config, react, router, server, test, react-testing and vite are. @uniflowed/web — Image, Font and the Open Graph cards — is one of the packages that is not yet; Publishing status has the list.

What every migration has in common

The shape you are moving into

writes ten files in a directory beside your application, and nothing else. Make one first: it is the target of every step below, and Your first project explains each file. What you copy into it and what you delete:

uf install runs no package.json script. It says so for a script such as start or test, and refuses a manifest that declares one a package manager would run by itself during an install — postinstall, prepare and the other lifecycle hooks — before it fetches anything. Scripts has the list.

Declaring the tools

uf.config.js names the runtime and package manager each command runs on, where it is used:

// @flow
import { defineConfig } from "@uniflowed/config";

export default defineConfig({
  runtime: "node@24",
  packageManager: "pnpm@10",
  build: { runtime: "node@24", builder: "vite" },
  test: { runtime: "node@24", runner: "uf" },
  tasks: {
    dev: { command: "uf dev" },
    build: { command: "uf build" },
    check: { command: "uf check" },
    lint: { command: "uf lint" },
    fmt: { command: "uf fmt" },
    test: { command: "uf test" },
  },
});

"node@24" is the newest 24.x, resolved the first time a command needs it, locked in uf.lock and installed into a store every project on the machine shares; commit uf.lock. "node@24.14.0" is exactly that release, "node" is whichever node is on PATH, and a range such as "node@^24" is refused. A project that writes none of these keys runs on the node it finds, with the manager its lockfile names — so the lockfile you already have keeps choosing until you say otherwise. uf build --compile is the exception: it still embeds the host app.runtime.capabilityJsHost finds (#1036). Environments is the whole of it.

What carries over unchanged

• React itself. React 19: the same hooks, the same rendering model, the same react and react-dom packages. @uniflowed/react re-exports react by name, so import { useState } from "react" reaches the same module. uf's lint warns on a plain function component or hook and asks for a component or hook declaration, and the React Compiler is already running.
• JSX in .js files. Flow's parser reads it, so nothing is renamed to .jsx.
• CSS. Plain imports, .module.css, and the preprocessors Vite supports once you install one.
• public/. Served from the root and copied into the build untouched.
• .env files. .env, .env.local, .env.<mode> and .env.<mode>.local, read in that order. What reaches the browser changes; each path below says how.
• Vite plugins. plugins in uf.config.js is a list of ordinary Vite plugins, appended to uf's own — vite-plugin-svgr included.
• Your dependencies at run time. What changes is what the checker can see of them, above.

Converting the types

Rename .ts and .tsx to .js. // @flow is optional: uf check checks every file that does not say // @noflow. uf runs Flow with its TypeScript syntax on, so much of a TypeScript file is already Flow:

One rule has no TypeScript counterpart. A file with no import and no export is read as a script, where await is an ordinary identifier, so a top-level await in one is refused; export {} is enough to make it a module.

From create-react-app

The shortest distance of the three: a CRA application is a client-rendered bundle, and that is a shape uf builds.

What carries over

The components, their hooks, their CSS and public/. The shape of a Jest suite — describe, it, expect, snapshots — and the matchers @testing-library/jest-dom adds, which expect has built in. React Testing Library's render, screen, within, fireEvent, userEvent and waitFor, from @uniflowed/react-testing.

The moves

1. Make the project and copy the source. uf new ../my-app-uf, then copy src/, public/ and your .env files into it.
2. Replace package.json's tooling. Take the scaffold's package.json — @uniflowed/config, @uniflowed/react, @uniflowed/router and @uniflowed/vite at the version of the uf that wrote it, react and react-dom, and @uniflowed/test — and add your own dependencies to it. react-scripts, eslintConfig and the scripts block do not come across: start, build and test are uf dev, uf build and uf test, and anything else becomes a task. Add @uniflowed/react-testing for component tests, copy your lockfile if you want its manager to keep choosing, and run uf install.
3. Write uf.config.js — the shape above.
4. Turn public/index.html into app/$layout.js. The <html lang>, the <body> and anything in <head> move into the component; <title> and the description become metadata. <div id="root"> goes, because uf renders the whole document, and so does %PUBLIC_URL%: a file in public/ is at /.
5. Delete src/index.js. app.js, from the scaffold, is the entry: it hands app/ to the router, and nothing calls createRoot.
6. Turn each route into a directory under app/. <Route path="/users/:id"> is app/users/[id]/$page.js, and the parameter arrives as a prop; the catch-all path="*" is app/$not-found.js. <Link to> is Link from @uniflowed/router with the same to, useNavigate() is useRouter().push, and useParams() and useLocation() are useRoute()'s params, pathname and searchParams. There is no supported way to keep React Router: app.router.enabled: false makes the project a library, and nothing in uf runs <BrowserRouter> inside its own router. Even as a client component, a nested <BrowserRouter> is prerendered during uf build and fails on document is not defined, so move those routes rather than nesting routers.
7. Rename what reaches the browser. uf defines no process.env for browser code: process.env.REACT_APP_API becomes import.meta.env.REACT_APP_API, with vite: { envPrefix: "REACT_APP_" } in uf.config.js — or rename the variables to VITE_API, the prefix uf uses when you set none. A direct unit test that imports a component is not running under Vite's app entry, so pass the env-derived value into a testable child component, or guard the read.
8. Keep SVGs as components by adding vite-plugin-svgr to plugins, or move icons to uf:icon/…. A plain import url from "./logo.svg" is still a URL.
9. Move the tests — the table below.
10. Map your ESLint rules with Coming from ESLint, and write the ones you keep under lint.rules.
11. Convert the types, if the project had any. A JavaScript project is checked too, so expect uf check to have something to say about code nobody annotated.
12. Run the loop: uf fmt, uf lint, uf check, uf test, then uf build and uf preview.

A route under app/ looks like this:

// @flow
// app/users/[id]/$page.js — was <Route path="/users/:id" element={<User />} />
import * as React from "@uniflowed/react";
import { Link } from "@uniflowed/router";

export component Page(params: {| readonly id: string |}) {
  return (
    <main>
      <h1>User {params.id}</h1>
      <Link to="/users">All users</Link>
    </main>
  );
}

This path was checked end to end with uf 0.0.0-alpha.40 from a CRA 5.1.0 app using React Router 6.30.2, a REACT_APP_ environment variable and React Testing Library tests. The CRA side passed npm run build and npm test; react-router-dom@7.18.4 did not run under CRA's Jest resolver because it looked for react-router/dom, so the fixture stayed on v6.30.2. The uf target passed uf install, uf fmt --check, uf check, uf test and uf build. create-react-app printed its deprecation warning and npm audit findings, but neither changed the uf migration steps.

Moving the tests

If a route component imports Link or a router hook, render it with router context, or move the plain UI into a child component and test that child. Rendering the route component by itself fails because @uniflowed/router hooks only run inside the app router.

Deploying it

A CRA build was one index.html and a bundle. app.rendering.modes: ["csr"] is the same shape: uf build writes one shell as index.html and again as 404.html, the browser renders every route from it, and a host that serves an error document or rewrites to index.html serves the application — csr: a single-page application says what that costs. Leaving the default instead prerenders every route it can, which a static host serves as documents.

What is still different

• Mocks are not hoisted. A jest.mock anywhere in a file becomes a uft.mock above the await import(…) that reaches it. Module mocking runs on Node and on Deno 2.8 or newer, and coverage on Node only (#972 is a suite split across machines).
• Some ESLint plugin rules have no answer yet — React (#1062), hooks, including exhaustive-deps (#1063), jsx-a11y (#1064) and import (#1065).
• The addresses move. uf dev listens on 5173 and the build is dist/, not build/.

From Vite + React

You are already on the bundler uf drives — @uniflowed/vite depends on vite: "^8.2.2" — so the mechanics are small, and a TypeScript codebase makes the type conversion the whole job.

What carries over

Vite itself, and every plugin. Vite's options, under the vite key. import.meta.env, the VITE_ prefix and the .env files. import.meta.glob, ?raw, ?url, ?worker and asset imports, which uf check declares. public/, CSS Modules and preprocessors.

The moves

1. Turn vite.config.ts into uf.config.js. server.port, server.host, server.strictPort, server.allowedHosts and server.fs are dev.port, dev.host, dev.strictPort, dev.allowedHosts and dev.fs; build.outDir and build.sourcemap keep their names under build; plugins stays plugins. Everything else — resolve.alias, build.target, define — goes under vite unchanged, where objects merge key by key and arrays replace. A dev-server proxy stays there too, as vite: { server: { proxy } }, rather than under dev. root and configFile stay uf's, and so do uf's own plugins, which come first. See vite.
2. Turn index.html into app/$layout.js. Vite runs with appType: "custom" under uf: there is no HTML entry to fall back to, and the document is the layout.
3. Turn the entry into routes. src/main.tsx goes; app.js is the entry and a page under app/ is what / renders. A client-side router's routes become directories, as in step 6 above.
4. Write the tool keys into uf.config.js, as above.
5. Convert the types.
6. Move the tests from Vitest with the same table. uf test --browser is uf's browser mode.
7. Rewrite the HMR guard. if (import.meta.hot) { import.meta.hot.accept() } is a uf check error, because Flow does not refine a test on import.meta. Write import.meta.hot?.accept(); uf lint --fix-unsafe makes that change for you (Writing your own import.meta.hot).
8. Swap vite preview for uf preview, on 4173 as before. It serves the route handlers and per-request renders a static preview cannot.

This path was checked end to end with uf 0.0.0-alpha.40 from a create-vite@9.2.1 React app using Vite 8.3.0, React 19.2.8, @vitejs/plugin-react, Vitest 5.0.1, server.proxy, and a VITE_ environment variable. The Vite side passed npm run build, npm test, and vite preview; the uf target passed uf install, uf fmt --check, uf check, uf test, uf build, and uf preview. The migrated target kept the proxy under vite.server.proxy, declared runtime, packageManager, build.runtime, build.builder, test.runtime and test.runner, and kept the environment variable visible to the client. Two small moves were needed: a test that imports a route directly should render a CSS-free child component instead, and a Vite image import may need its src read when the server prerender sees an asset object.

What is still different

• The Vite version is uf's. A project that needs another one names a builder module of its own in build.builder — a directory that re-exports uf's driver beside the Vite it wants — rather than a vite dependency.
• An extension added to assetsInclude is not read by uf check, so an import of that kind is any.

From Next.js

The conventions line up closely, and most of what an App Router application does has a counterpart. What does not is listed below, and so is what uf's deployment record does not have yet.

What carries over

The moves

1. Make the project and move app/. uf new ../my-app-uf, then rename page.tsx to $page.js, layout.tsx to $layout.js and the rest by the table, converting the types as you go. Export route components by name: export component Page and export component Layout, matching what uf new writes. Put "use client" at the top of each $error.js.
2. Replace next.config.js. output is the last two rows above, and images is app.builtins.images. redirects(), rewrites() and headers() become app.router.redirects, rewrites and headers: the same sources written as data, with a rule's headers an object rather than a list of { key, value }. A rewrite to another origin is a route handler that fetches it, and a has or missing condition is a middleware that returns rewrite() or Response.redirect (Redirects, rewrites and response headers has the whole table). basePath is app.router.basePath, and a project that relied on Next.js's default redirect from /about/ to /about sets app.router.trailingSlash: "never" (A base path and a trailing slash).
3. Change the imports by the table: next/navigation to @uniflowed/router, next/headers and next/server to @uniflowed/server, next/cache to @uniflowed/server/cache, next/dynamic to React's lazy. In a $route.js, return JSON as a Response with a JSON body and content-type; Flow's DOM library does not expose Response.json() yet.
4. Keep data fetching in Server Components. A page can be an export async function Page(props: Props) that calls await fetch(...) and returns JSX. Nested async functions stream behind <Suspense>; no loader is required. A route loader remains an option when several route consumers need the same prepared data (Loading data). Keep async data fetching on the server: React does not support async Client Components. generateMetadata is read from a page, and a route that uses it waits for its data rather than streaming.
5. Split middleware.ts by directory. There is no matcher: a $middleware.js guards the directory it sits in, and middleware composes down the tree the way layouts do. Export function middleware(request: Request), return a Response to answer, or return nothing to continue — NextResponse.next() is returning nothing (Middleware).
6. Restate caching. Turn on app.rendering.cache.route, then call cacheLife({ revalidate: 60 }) and cacheTag("posts") inside the render, from @uniflowed/server/cache; export const revalidate is not read. A prerendered page that states a lifetime is served from the build and regenerated in the background once it passes, which is the behaviour ISR names, and rendering.cache.store decides where the regenerated pages are kept (Caching).
7. Rename what reaches the browser. NEXT_PUBLIC_API becomes VITE_API, or keep the name with vite: { envPrefix: "NEXT_PUBLIC_" }. Server code reads every variable through process.env, as before.
8. Swap the components. next/image and local next/font are Image and Font from @uniflowed/web, given an imported file, and an opengraph-image is a *.og.json template (Images, fonts, icons and cards). sitemap.xml and robots.txt are written by uf build once site.url is set.
9. Move the tests with the same table.
10. Choose a target. uf build lists every route that needs a server under answered by a server. uf build --adapter container writes a Dockerfile, edge a Cloudflare Worker and serverless a Lambda function; Serving a build is what each needs.

This path was checked end to end with uf 0.0.0-alpha.40 on a migrated App Router-shaped fixture: a page with a loader, a $route.js handler and a directory $middleware.js. uf install, uf fmt --check, uf check, uf test and uf build all completed. The build named /api/status and /admin/* under answered by a server, and reported the /admin guard.

What is still different

• The deployment record. No server adapter's output has been deployed to its platform by uf's own pipeline (#956), serverless buffers a streamed document, and there is no adapter for Vercel or Netlify.
• Server functions. An inline "use server" closure in a server module is callable and its captures are sealed; one written in a "use client" module is not an endpoint. A file upload does not work, and a form bound to an action passed down as a prop posts only after hydration (one bound to an imported action posts before it); an action's arguments are JSON data plus at most one form (What is not here, uf and Next.js).
• A slot is not a request boundary. It holds no $not-found.js, $route.js or $middleware.js, and an interception is always shown in a slot rather than replacing children.
• The rest of ISR and PPR. A --compile binary carries no cache and renders a partially prerendered page whole, per request; serverless refuses a partially prerendered page; and there is no experimental_ppr export or cacheComponents switch — a page is a shell with holes when it reads the request inside a <Suspense> boundary and ppr is allowed (Rendering). Function caching uses explicit cacheFunction, with a name, arguments and lifetime; the "use cache" directive is not supported.
• Middleware and request APIs. A rewrite changes the path and never the request's headers, neither a middleware's nor a config rule's proxies to another origin, and cookies() reads without writing.
• Images and fonts. An imported image is resized at build time, with no AVIF or lossy WebP there (#997). images.remotePatterns carries over as app.builtins.images.remotePatterns with the same keys, and next/image's remote src becomes Image through /__uf/image; a deployed node, container or serverless directory needs app.builtins.images.transformer to encode there. A font is self-hosted from a file you import rather than downloaded from a provider.
• Files with no counterpart: global-error.tsx, instrumentation.ts, and the icon and manifest conventions.

Estimating your own migration

The measured paths above are deliberately small, so use this arithmetic for the application in front of you. The job is four numbers you can count today:

1. Modules to convert. Mechanical, and mostly the table above.
2. Imports uf check still types any. Convert one leaf directory, run uf install and uf check, and read the list the report ends with — and, for a package typed from its TypeScript declarations, how much of it the translation could not say.
3. Tests that lean on a hoisted mock or on another runner's globals. Each one moves its mock above the import it affects.
4. Routes that need a server, against where you deploy. uf build names them.

The second number is the one that decides whether the type system pays you back, and it is also the real conversion rate for your codebase: it beats any figure this page could assert.

Where to go next

Start is next: install uf and make a project, which is the shape you are converting into — Your first project explains each file of it. What uf does not do is the list of walls, kept current with issue numbers. If the answer turns out to be "not yet", that is a supported answer — it is why the list exists.

Edit this pagedocs/app/guide/migrate/$page.mdx