Readiness: Implemented

Start

Your first project

You need uf installed and a JavaScript host such as Node.js.

Create and install

uf new my-site
cd my-site
uf install

uf new creates the directory. To use an existing directory, run uf init there instead. Both commands create files; uf install installs dependencies.

The default template is react. Use uf new my-site monorepo for an application and a shared library, or uf new my-library --lib for a library. The CLI reference also covers remote templates.

The React template writes these files, listed in the order LC_ALL=C ls lists them. Route files start with $ so that they come first in their directory:

my-site/
  .gitignore         generated files to exclude from Git
  AGENTS.md          guidance for coding agents, matched to this uf version
  app/
    $layout.js       document layout
    $page.js         home page
    $page.test.js    example test
    Counter.js       example client component
    useCounter.js    example hook
  app.js             application entry
  package.json       dependencies
  uf.config.js       project configuration and tasks

Replace the example counter, hook and test as you build your application.

Start the development server

uf dev

The server reloads as you edit. React components support Fast Refresh.

Run checks and builds

Set uf.config.js to the following to use the task workflow in this guide. This also works with older uf releases whose templates use different task names:

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

export default defineConfig({
  tasks: {
    "verify:format": { command: "uf fmt --check" },
    "verify:source": { command: "uf check" },
    verify         : { command: "uf test", dependsOn: ["verify:format", "verify:source"] },
    bundle         : { command: "uf build", dependsOn: ["verify"] },
  },
});

dependsOn lists tasks that must succeed first. uf check includes linting and type checking, so the example does not run a separate lint task. Use the same uf run bundle command locally and in CI.

You can also run built-in commands such as uf test or uf build directly. Tasks covers custom commands and caching.

uf uses app/ for routes and app.js as the entry by default. To change them, set app.router.root and app.router.entry. defineConfig provides Flow types for the configuration; see all options.

Add pages and layouts

app/$page.js defines the home page:

// @flow
export component Page() {
  return <h1>Hello</h1>;
}

app/$layout.js wraps the page in an HTML document:

// @flow
import * as React from "@uniflowed/react";

export component Layout(children: React.Node) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

The template uses children: mixed so it can be checked before dependencies are installed. After uf install, you can use React.Node as shown above.

Use named exports such as Page and Layout. The router accepts default exports too, but uf check warns on default-exported components. See Routing for nested routes, parameters and loading states.

Build for deployment

uf run bundle

The build writes prerendered HTML and client assets to dist/. To inspect bundle sizes, run uf build --size-report. Deploy a web build covers previewing and publishing the output.

Next steps

Connect your editor with IDE setup, or follow Build a reading list to add data, shared state and forms.

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