Quick Start

Install the CLI, create a project, and deploy your first Roost application.

Tip

What you'll do: Install the Roost CLI, scaffold a project, add a route, create a database model, add authentication, and deploy — all in about 15 minutes.

Prerequisites: Bun 1.0+, a Cloudflare account (free tier), and a WorkOS account (free tier).

Step 1: Install the Roost CLI

Install the CLI globally with Bun:

bun add -g @roostjs/cli

Verify the installation:

roost --version

You should see a version number like 1.0.0. If the command isn't found, make sure Bun's global bin directory is on your PATH.

Step 2: Create Your Project

Scaffold a new Roost application:

roost new my-app
cd my-app
bun install

You should see the CLI generate a project structure and install dependencies. This takes a few seconds.

Step 3: Start the Dev Server

bun run dev

You should see output indicating the dev server is running. Open http://localhost:3000 in your browser — you'll see the Roost welcome page.

Step 4: Create Your First Route

Create a new file at src/routes/hello.tsx:

import { createFileRoute } from '@tanstack/react-router';

export const Route = createFileRoute('/hello')({
  component: HelloPage,
});

function HelloPage() {
  return (
    <div>
      <h1>Hello, Roost!</h1>
      <p>Your first route is working.</p>
    </div>
  );
}

Visit http://localhost:3000/hello. You should see "Hello, Roost!" displayed in the browser. The page appeared without restarting the server — TanStack Start picks up new route files automatically.

Step 5: Add a Database Model

Generate a model and its migration:

roost make:model Post

This creates src/models/post.ts. Edit it to define your schema columns using Drizzle's SQLite core helpers:

import { Model } from '@roostjs/orm';
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';

export const posts = sqliteTable('posts', {
  id:         integer('id').primaryKey({ autoIncrement: true }),
  title:      text('title').notNull(),
  body:       text('body').notNull(),
  created_at: text('created_at'),
  updated_at: text('updated_at'),
});

export class Post extends Model {
  static tableName = 'posts';
  static _table = posts;
}

Run the migration:

roost migrate

You should see output confirming the posts table was created in your local D1 database.

Step 6: Query Your Model

Update your hello route to read from the database:

import { createFileRoute } from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import { Post } from '../models/post';

const getPosts = createServerFn({ method: 'GET' }).handler(async () => {
  return Post.where('id', '>', 0).orderBy('created_at', 'desc').all();
});

export const Route = createFileRoute('/hello')({
  component: HelloPage,
  loader: () => getPosts(),
});

function HelloPage() {
  const posts = Route.useLoaderData();
  return (
    <div>
      <h1>Posts</h1>
      {posts.length === 0 ? (
        <p>No posts yet.</p>
      ) : (
        <ul>
          {posts.map((post) => (
            <li key={post.id}>{post.title}</li>
          ))}
        </ul>
      )}
    </div>
  );
}

Visit http://localhost:3000/hello. You should see "No posts yet." — the model is connected to D1 and the query ran successfully.

Step 7: Add Authentication

Add your WorkOS credentials to .dev.vars:

WORKOS_API_KEY=sk_test_...
WORKOS_CLIENT_ID=client_...
Tip

Never commit .dev.vars — it's in .gitignore by default.

Auth routes are available automatically once credentials are configured:

/auth/login # Redirect to WorkOS /auth/callback # Handle OAuth callback /auth/logout # Clear session

Visit http://localhost:3000/auth/login. You should be redirected to the WorkOS login page. After authenticating, you'll be redirected back to your app. To protect a route, add AuthMiddleware — see the auth guides for details.

Step 8: Deploy

roost deploy

You should see the build output followed by a live URL on *.workers.dev. Your app is now running on Cloudflare Workers at the edge. Set production secrets in your Cloudflare dashboard under Workers > Settings > Variables.

What You Built

You installed the Roost CLI, scaffolded a project, created a route, added a database model with a migration, queried it from a page, configured authentication, and deployed to Cloudflare Workers. That's a full-stack app running at the edge.

Next Steps