# Install and run Forma

A full-stack Forma application uses **Node.js to build the frontend** and
**Rust to build and run the server**. Install both toolchains before creating
your first native application. The [browser lessons](/learn/) need neither.
For a browser-only UI using `@getforma/core`, Node.js and npm are enough;
Rust is needed when you build and run the native server.

## Install the prerequisites

| Tool | Required version | Purpose |
| --- | --- | --- |
| Node.js with npm | Node 22 or newer | Run the starter and build TypeScript, CSS and native page modules |
| Rust with Cargo | Rust 1.85 or newer | Compile the Rust dependencies and run your application server |

Install Node.js from the [official Node.js downloads](https://nodejs.org/en/download).
Install Rust through the [official rustup instructions](https://rust-lang.org/tools/install/);
rustup supplies both the `rustc` compiler and the `cargo` package/build tool.
**The Forma starter does not install Rust or Cargo.**

Rust also needs your platform's native build tools: Xcode Command Line Tools on
macOS, GCC or Clang with a linker on Linux, or the Visual Studio C++ build tools
for the standard Windows MSVC toolchain. The [Rust installation guide](https://doc.rust-lang.org/book/ch01-01-installation.html)
explains each platform's setup.

Open a new terminal after installation and check that all four commands work:

```sh
node --version
npm --version
rustc --version
cargo --version
```

The Node and Rust versions must meet the table above. If `cargo` is not found,
finish the rustup setup and reopen your terminal so its PATH change takes effect.

## Create the project

Run this in the directory where you want a new `my-app` folder:

```sh
npx @getforma/create-app@3.0.0 my-app --template minimal
```

`npx` downloads and runs the published generator. It creates application source,
frontend and Cargo lockfiles, and attempts to initialize a Git repository. It
does **not** install the application's dependencies or start a server.

## Build the frontend

```sh
cd my-app/admin
npm ci
npm run build:ssr
cd ..
```

`npm ci` installs the exact frontend dependencies in `admin/package-lock.json`,
including Forma core, compiler and build 3.0.0 from the npm registry. Use it for this shipped template;
`npm install` can change the lockfile. Keep the generated `.npmrc` in place.

`build:ssr` produces native FMIR page modules and their paired browser assets.
Build these before compiling Rust, which embeds the output. In this minimal
template, ordinary `npm run build` instead selects browser rendering.

## Compile and start the server

From `my-app`, where `Cargo.toml` lives:

```sh
cargo run --locked --jobs 3
```

Cargo downloads missing Rust dependencies, including `forma-ir` and
`forma-server` 3.0.0, Axum and Tokio from crates.io, compiles them and your
application, then starts the server.
These are libraries already declared in `Cargo.toml`, so you do not need a
separate `cargo install` command. npm does not install these Rust crates.
`--locked` requires the existing `Cargo.lock` resolution; `--jobs 3` limits
compilation parallelism. The first build takes longer while dependencies are
downloaded and compiled. Cargo builds your server; it does not install the
Rust toolchain or build your TypeScript. See the [Cargo build guide](https://doc.rust-lang.org/cargo/guide/working-on-an-existing-project.html)
and [run options](https://doc.rust-lang.org/cargo/commands/cargo-run.html).

## Check the result

Open **http://localhost:3000**. The initial HTML contains a counter at **7**;
its island makes Increment change it to **8**. Refresh returns to the server's
seed of 7 because this example does not save edits. `/about` renders without
executable JavaScript. Stop the local server with Ctrl+C.

The starter already includes Axum for HTTP routing and Tokio for async execution.
You can add API routes, middleware and database connections to this Rust server.
Follow [Build your backend](/docs/3.0/backend/) to add a JSON endpoint and see
which responsibilities belong to Forma, Axum and your application libraries.

Continue with the [minimal template walkthrough](/docs/3.0/minimal-template/)
or [Field Notes](/learn/full-stack/) to add validated, persistent edits.

These prerequisites and steps follow the published
[3.0.0 starter](https://github.com/getforma-dev/forma/tree/v3.0.0/packages/create-app)
and its minimal template. Both lockfiles belong in your application repository.