Getting started

Migrating to uf

Three questions that mean "not yet"

Answer these before you read the rest. Each one is a wall, not a speed bump.

Where do you deploy? A build renders per request, serves route handlers and streams — through uf preview, uf start, the directory uf build --adapter node writes, or the file uf build --compile writes. What is missing is the targets: node is the only one of the seven deploy adapters implemented, so a project that needs a Cloudflare Worker or a Lambda has an entry file to write and no help writing it yet (#391). If that is you, read uf compared before you start.

Do you have TypeScript you cannot convert? uf transforms .js, .jsx, .mjs and .cjs in your project and nothing else. A .ts file is handed to Biome for formatting and is invisible to everything else uf does. Migration means converting the whole application, not adding uf beside tsc.

Do you depend on typed packages? Every dependency without a Flow libdef is any. Count them now: that number, not the file count, is what decides whether this is worth doing. Flow and TypeScript is the long version.

What every migration has in common

Files you delete

uf new my-app in a scratch directory is the fastest way to see the shape you are aiming at — nine files, and Your first project walks through them.

What stays exactly as it is

• public/. Served from the root, copied into the build untouched.
• CSS. Plain imports, .module.css, and the preprocessors Vite supports.
• Vite plugins. plugins in uf.config.js is a list of ordinary Vite plugins, appended to uf's own.
• React itself. React 19, the same hooks, the same rendering model. uf compiles component and hook declarations to plain functions and hands them to the official React Compiler.

Converting the types

Rename .ts and .tsx to .js, put // @flow on the first line, then work through the constructs. Most of them are a one-line change:

Two things that will surprise you. uf check resolves no modules yet: every import is any and the report names them, so a converted file can look clean and still be wrong across a boundary (#248). And a file with no import and no export is read as a script, where await is an ordinary identifier rather than an operator, so a top-level await in one is refused; uf decides the goal symbol from the file's own syntax (#204).

From create-react-app

The best-supported path, because CRA applications are usually a client-rendered bundle and that is what uf builds.

1. uf new ../my-app-uf, then copy src/ into it.
2. Delete react-scripts. Its scripts block goes with it — uf install refuses a manifest that declares one.
3. Move the contents of public/index.html into app/_uf.layout.js. The <div id="root"> goes away: uf renders the whole document.
4. Turn each screen into a route directory under app/. uf's file-system router is the routing uf builds against; app.router.enabled: false makes the project a library rather than an application, so it is not a way to keep React Router.
5. Convert the types, if the project had any.
6. uf fmt, then uf lint, then uf check, then uf test.

What you lose. Jest — uf test has the API and no coverage (#280), so a suite that reports coverage does not come across whole. jest.mock has a destination: uft.mock replaces a module on Node, though it is not hoisted, so a mock has to be written above the await import(…) that reaches it rather than anywhere in the file. REACT_APP_* environment variables need renaming: uf reads the same .env cascade, but the prefix that reaches the browser is VITE_ — see Environments, and vite: { envPrefix: "REACT_APP_" } if you would rather not rename them.

Cost. The route and entry work is a day's shape regardless of size; the long pole is the test suite, in proportion to how much of it reports coverage or leans on a hoisted jest.mock.

From Vite + React

The mechanics are smaller — you are already on the same bundler — and the language change is the whole job.

1. vite.config.ts becomes uf.config.js. Options uf owns (dev.port, build.outDir) have names; everything else goes under the vite key unchanged, including resolve.alias and server.warmup.
2. index.html becomes app/_uf.layout.js. Vite runs in appType: "custom" under uf: there is no HTML entry to fall back to, and the document comes from the layout.
3. Your entry module becomes app.js plus a page under app/.
4. Convert the types.
5. Replace Vitest with uf test — the describe/it/expect surface is the same, and expect has 25 matchers, .not, .resolves, .rejects and fn().

What you lose.

• vite preview. uf has no equivalent (#255).
• vite/client's types. import.meta.glob, import.meta.hot and asset imports are type errors or any under uf check — five errors in a five-line file (#264). The code still runs; the checker cannot see it.
• Choosing your Vite version. uf depends on vite: "^8.2.2".

Cost. A day for the configuration and the entry, then the type conversion, which is the part that scales with the codebase.

From Next.js

Read What uf does not do first, then this.

A Next.js application that needs a server cannot move to uf today. Server Components are analysed and never executed, so every page module ships to the browser (#252); server actions have a registry and no dispatcher; nothing streams (#254); there is no revalidation (#277); and middleware.ts has an exact counterpart in uf that is discovered, reported by uf inspect --json, and never called (#260).

What can move is an application you could already build with output: 'export' — static pages, client-side data fetching, no per-request rendering.

The conventions line up more closely than the capabilities do:

Cost. For a statically exportable site, the same as the Vite path plus the route renaming. For anything else, it is not a cost — it is a blocker, and the issues above are where to watch for it to lift.

Estimating your own migration

There is no measured migration to quote, so here is the arithmetic instead. The job is three numbers you can count today:

1. Modules to convert. Mechanical, and mostly the table above.
2. Dependencies with no Flow libdef. Each one is any at the boundary, and this is the number that decides whether the type system pays you back.
3. Tests reporting coverage. These have no destination yet. Tests using snapshots or module mocks do, though a mock has to move above the import it affects.

And one number you can produce: convert a single leaf directory, run uf check, and read the count. That is the real conversion rate for your codebase, and it beats any figure this page could assert.

Where to go next

Your first project is the shape you are converting into. 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.

Next: Flow, the modern parts →