Skip to main content
Prerequisites:
  • Bun 1.3.5 or higher
  • PostgreSQL 17 (or a Neon database account)
  • Git
Get Better Skills running locally in a few steps.

​
Clone the repository

First, clone the Better Skills repository: 
git clone https://github.com/your-org/better-skills.git
cd better-skills

​
Install dependencies

Better Skills uses Bun as its package manager and runtime. Install all dependencies: 
bun install
This project requires Bun 1.3.5. Do not use npm, pnpm, or yarn.

​
Workspace structure

The repository is organized as a Bun monorepo: 
better-skills/
├── apps/
│   ├── web/         # Frontend application (Next.js)
│   ├── server/      # Backend API (Hono, tRPC)
│   └── cli/         # Command-line interface
├── packages/
│   ├── api/         # tRPC router & business logic
│   ├── auth/        # Better Auth configuration
│   ├── db/          # Drizzle schema & migrations
│   ├── env/         # Environment variable validation
│   ├── config/      # Shared TypeScript config
│   └── markdown/    # Markdown parsing utilities

​
Set up the database

Before running the development server, configure your database. See Database Setup for detailed instructions.

​
Configure environment variables

Copy the environment variable templates and fill in your values: 
# Server environment
cp apps/server/.env.example apps/server/.env

# Web environment
cp apps/web/.env.example apps/web/.env
See Environment Variables for a complete reference.

​
Start all services

Run the development server for both web and API: 
bun run dev
This starts:
The dev script excludes the CLI. To run the CLI, use bun cli or bun run dev:cli.

​
Start individual services

You can also run services independently: 
bun run dev:web

​
Default ports

ServicePortURL
Web3001http://localhost:3001
Server3000http://localhost:3000

​
Verify your setup

Once everything is running:
1

Open the web app

Navigate to http://localhost:3001 and verify the homepage loads.
2

Check API health

The API should be accessible at http://localhost:3000.
3

Run type checking

bun run check-types
4

Run linting

bun run check

​
Next steps

Database Setup

Configure PostgreSQL and run migrations

Environment Variables

Learn about required environment configuration

Architecture

Understand the system architecture

Tech Stack

Explore the technologies used

Build docs developers (and LLMs) love

Get started for freeTalk to us