This page provides instructions for setting up a local development environment for contributing to the memos codebase. It covers installing prerequisites, configuring the workspace, and running the application in development mode.
Scope: This guide focuses on local development setup. For production deployment, see Docker and Container Deployment. For build system details, see Project Structure and Build System. For protocol buffer development, see Protocol Buffer Development.
Memos uses a dual-stack architecture requiring separate development environments for the Go backend and React frontend. During development, the frontend runs on a Vite dev server with hot module replacement, while the backend runs as a standalone Go application.
Sources: web/package.json1-100 server/server.go1-183 go.mod1-135
| Component | Minimum Version | Notes |
|---|---|---|
| Go | 1.21+ | Backend compilation |
| Node.js | 18.0+ | Frontend development |
| pnpm | 8.0+ | JavaScript package manager |
| Git | 2.30+ | Version control |
| Protocol Buffers | 3.20+ | API code generation (optional for most development) |
The development environment works on:
Note: Windows users should use WSL2 (Windows Subsystem for Linux) for the best development experience, as some build scripts assume a Unix-like environment.
Sources: go.mod3 web/package.json94-98 README.md1-112
Linux/macOS:
macOS (Homebrew):
Windows (WSL2): Follow the Linux instructions within your WSL2 terminal.
Using Node Version Manager (nvm) - Recommended:
Install pnpm globally:
macOS (Homebrew):
Required only if modifying .proto files. See Protocol Buffer Development for details.
Sources: web/package.json94-98 go.mod1-8
memos/
├── cmd/
│ └── memos/
│ └── main.go # Backend entry point
├── server/
│ ├── server.go # HTTP server initialization
│ ├── router/ # API and frontend routes
│ └── runner/ # Background jobs
├── store/ # Database abstraction layer
├── proto/ # Protocol buffer definitions
│ ├── api/ # API service definitions
│ └── gen/ # Generated Go/TypeScript code
├── web/
│ ├── src/ # React frontend source
│ ├── package.json # Frontend dependencies
│ └── vite.config.ts # Vite build configuration
├── go.mod # Go module dependencies
└── README.md
Sources: Repository structure inferred from file paths
This downloads all dependencies declared in go.mod, including:
github.com/labstack/echo/v5)modernc.org/sqlite, github.com/go-sql-driver/mysql, github.com/lib/pq)google.golang.org/grpc, google.golang.org/protobuf)The backend will start on port 5230 by default.
Create a .env file in the repository root:
Sources: go.mod5-38 server/server.go85-109
The pnpm install command installs all dependencies from package.json, including:
The Vite dev server provides:
/api/v1/* requests to backend serverEdit web/vite.config.ts to proxy API requests to the backend:
Sources: web/package.json1-99 web/pnpm-lock.yaml1-246
Sources: web/package.json4-10
Open your browser to:
The frontend dev server proxies API requests to the backend automatically.
Sources: server/server.go59-61 web/package.json5
Frontend uses Biome (not ESLint) for linting and formatting:
This runs:
tsc --noEmit --skipLibCheckbiome check srcbiome format --write srcBackend uses standard Go tools:
Sources: web/package.json4-10
No setup required. The application automatically creates memos_dev.db in the current directory on first run.
Sources: go.mod13-21 go.mod37
| Variable | Default | Description |
|---|---|---|
MEMOS_MODE | prod | Set to dev for development mode |
MEMOS_ADDR | 0.0.0.0 | Bind address |
MEMOS_PORT | 5230 | HTTP server port |
MEMOS_DRIVER | sqlite | Database driver: sqlite, postgres, mysql |
MEMOS_DSN | ./memos_prod.db | Database connection string |
MEMOS_DATA | ./data | Data directory for file storage |
Create a .env file in the repository root:
The application loads this automatically using the godotenv library.
Sources: go.mod18 server/server.go85-98
Recommended Extensions:
golang.go) - Go language supportbiomejs.biome) - Linting and formattingzxh404.vscode-proto3) - Protocol buffer syntaxWorkspace Settings (.vscode/settings.json):
Sources: web/package.json71-92
Sources: server/server.go94-97 web/package.json1-99
After setting up your development environment:
Sources: web/package.json4-10 server/server.go1-183 go.mod1-135
Refresh this wiki