Installation & project setup

This page gets you from an empty directory to a running Ossido app.

Prerequisites

Ossido spans two runtimes, so you need toolchains for both:

• Rust toolchain - install via rustup. This gives you cargo, which compiles the Rust server.
• Node or Bun - for the JavaScript side (the client build and SSR bundle). Bun is recommended; Node works too.

Scaffold a project

The quickest start needs nothing but your JS package manager. create-ossido fetches the CLI, runs the ossido new wizard, and installs your dependencies for you - use whichever package manager you prefer:

bun create ossido my-app
npm create ossido@latest my-app
pnpm create ossido my-app
yarn create ossido my-app

Then start the dev server:

cd my-app
ossido dev

The wizard walks you through the options below. Every choice also has a flag (see Feature flags), and create-ossido forwards them - so npm create ossido@latest my-app -- --tailwind --mdx --yes scaffolds with no prompts.

Installing the CLI

create-ossido pulls the CLI in for scaffolding, but you can also install the ossido binary on its own. It ships two ways:

# npm - a prebuilt binary, no Rust needed to install the CLI itself
npm install -g @ossido-labs/ossido-cli

# Cargo - built from the ossido_cli crate
cargo install ossido_cli

Or use the install script, which checks your toolchains first:

# macOS / Linux
curl -fsSL https://ossido.dev/install.sh | bash

# Windows
irm https://ossido.dev/install.ps1 | iex

Verify it's on your PATH:

ossido --help

Feature flags

Every wizard choice has a corresponding flag, so you can preselect options or skip the prompts entirely. Combine any of these with --yes (-y) for a non-interactive scaffold:

• --template <name> (-t) - start from a named template.
• --tailwind - include Tailwind CSS.
• --mdx - include MDX support (author pages in Markdown).
• --output <static|server> - the default build output mode.
• --alias <PREFIX> - set up a src path alias, e.g. --alias @ maps @/* to ./src/*.
• --head <bool> - control the generated document head.
• --yes (-y) - accept defaults and skip the interactive prompts.

For example, a Tailwind + MDX app with the @ alias, no questions asked:

ossido new my-app --tailwind --mdx --alias @ --yes

Project layout

A scaffolded project looks roughly like this:

my-app/
├── src/
│   └── routes/          # file-based routes (pages, handlers, layouts)
├── ossido.config.ts     # framework configuration
├── Cargo.toml           # Rust dependencies (the ossido runtime)
├── package.json         # JS dependencies (the ossido npm package)
└── .ossido/             # generated code - do not edit

• src/routes/ - the heart of the app. Folders become URL segments; a page.tsx (or page.mdx) is a route's view and a page.rs is its data handler.
• ossido.config.ts - server port/host, output mode, Vite passthrough, path aliases, and more.
• Cargo.toml - pulls in the Rust runtime crate.
• package.json - pulls in the JavaScript runtime package.
• .ossido/ - generated on each build (route tree, server entry). It's machine-owned; you never edit it by hand.

Dependencies

Because Ossido is two runtimes, a project depends on two matching packages:

• The ossido crate (in Cargo.toml) - the Rust runtime.
• The @ossido-labs/ossido npm package (in package.json) - the JavaScript runtime.

Keep their versions aligned. When you upgrade one, upgrade the other to the same version so the Rust server and the JS bundle agree on the contract between them. ossido upgrade does this for you - it bumps both to the same version and refreshes the lockfiles (see The CLI).

Next: The CLI · Back to Mental model & architecture