Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Required

  • Node.js >= 18
  • pnpm 9.0.0 (package manager)
  • Bun (runtime for server applications)
  • Git

​
Optional Services

  • Redis (for streams)
  • ClickHouse (for time-series data)
  • PostgreSQL (for application data)
Docker configurations are available in the docker/ directory for running these services locally.

​
Clone and Install

​
1. Clone the Repository

git clone <repository-url>
cd better-uptime

​
2. Install Dependencies

The project uses pnpm as the package manager: 
pnpm install
This will install all dependencies across the monorepo workspaces.

​
3. Environment Configuration

Create .env files in the appropriate locations. The project uses these environment variables:
  • PORT - Server port
  • JWT_SECRET - JWT authentication secret
  • DATABASE_URL - PostgreSQL connection string
Refer to .env.example files in individual apps for complete configuration.

​
Development Workflow

​
Start Development Servers

Run all applications in development mode: 
pnpm dev
This starts:
  • Client (Next.js) on port 3000
  • Server (Bun + tRPC) on configured port
  • Worker (background job processor)
  • Publisher (event publishing service)

​
Start Individual Apps

You can also run specific applications: 
# Client only
pnpm --filter client dev

# Server only
pnpm --filter server dev

​
Build for Production

Build all apps and packages: 
pnpm build
This runs the Turborepo build pipeline with dependency caching.

​
Code Quality

​
Linting

Run ESLint across the monorepo: 
pnpm lint

​
Type Checking

Run TypeScript type checking: 
pnpm check-types

​
Formatting

Format code with Prettier: 
pnpm format

​
Git Hooks

The project uses Husky for Git hooks: 
pnpm prepare
lint-staged automatically runs on pre-commit to:
  • Format changed files
  • Run linting
  • Check types

​
Package Scripts Reference

ScriptDescription
pnpm devStart all apps in development mode
pnpm buildBuild all apps and packages
pnpm lintRun linting across monorepo
pnpm formatFormat code with Prettier
pnpm check-typesRun TypeScript type checking
pnpm testRun all tests
pnpm test:watchRun tests in watch mode
pnpm test:coverageRun tests with coverage report

​
Development Tips

​
Turborepo Caching

Turborepo caches task outputs to speed up builds. To clear the cache: 
pnpm turbo clean

​
Bun Runtime

The server applications use Bun for faster startup and hot reload: 
bun run --hot src/bin.ts

​
Workspace Protocol

The project uses pnpm workspace protocol for internal packages: 
"dependencies": {
  "@repo/api": "workspace:*"
}
This ensures packages always reference the local workspace version.

​
Troubleshooting

​
Port Conflicts

If you encounter port conflicts, update the PORT environment variable in your .env file.

​
Dependency Issues

Clear node_modules and reinstall: 
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

​
Build Errors

Clear Turborepo cache and rebuild: 
rm -rf .turbo
pnpm build

Build docs developers (and LLMs) love

Get started for freeTalk to us