Development setup

Prerequisites

Node.js >= 20
Bun >= 1.3.14 (the only supported package manager)
PostgreSQL >= 13, or Docker for the quick-start path

Clone and install

git clone https://codefloe.com/flexcal/flexcal.git
cd flexcal
bun install

On Windows, clone from Git Bash with admin privileges so symlinks are created:

git clone -c core.symlinks=true https://codefloe.com/flexcal/flexcal.git

Environment

cp .env.example .env

Generate the two mandatory secrets and put them in .env:

# NEXTAUTH_SECRET
openssl rand -base64 32
# CALENDSO_ENCRYPTION_KEY, must be 32 bytes for AES256
openssl rand -base64 24

:::note[Windows] Replace the packages/prisma/.env symlink with a real copy, otherwise Prisma fails with unexpected character / in variable name:

rm packages/prisma/.env && cp .env packages/prisma/.env

:::

Quick start

bun run dx starts a local Postgres in Docker, applies migrations and seeds test users. It needs Docker and Docker Compose.

bun run dx

Seeded users, password equal to the username unless noted:

Email	Password	Role
`free@example.com`	`free`	Free user
`pro@example.com`	`pro`	Pro user
`trial@example.com`	`trial`	Trial user
`admin@example.com`	`ADMINadmin2022!`	Admin
`onboarding@example.com`	`onboarding`	Onboarding incomplete

Run bun run db-studio and open http://localhost:5555 to see the full list of seeded users.

Manual setup

If you already run PostgreSQL, skip dx and wire it up yourself.

Point DATABASE_URL at your database:
```
DATABASE_URL='postgresql://<user>:<pass>@<db-host>:<db-port>/<db-name>'
```
To create a local database from scratch: install PostgreSQL, run createdb <name>, then confirm the connection details with \conninfo inside psql -h localhost -U postgres -d <name>.
Copy .env.appStore.example to .env.appStore and paste the same DATABASE_URL into it.
Apply the schema (packages/prisma/schema.prisma):
Terminal window
```
bun run --cwd packages/prisma db-migrate
```
Start MailHog to catch outgoing mail. Required when E2E_TEST_MAILHOG_ENABLED is 1:
Terminal window
```
docker run -d -p 8025:8025 -p 1025:1025 mailhog/mailhog
```
Run the dev server:
Terminal window
```
bun run dev
```
Seed dummy users if you want them:
Terminal window
```
bun run --cwd packages/prisma db-seed
```

Everyday commands

# type-check the whole monorepo
bun run type-check:ci --force
# lint and format with Biome
bunx biome check --write .
# unit tests
TZ=UTC bun run test
# regenerate Prisma types after a schema change
bun run prisma generate

Tips

Give Node a bigger heap; the build is memory-hungry:

export NODE_OPTIONS="--max-old-space-size=16384"

Turn up tRPC logging with NEXT_PUBLIC_LOGGER_LEVEL in .env. See Configuration → Logging for the levels.

Project layout

Path	Contents
`apps/web`	The Next.js application
`packages/prisma`	Schema and migrations
`packages/trpc`	tRPC API layer
`packages/features`	Framework-agnostic feature code: services, repositories, types
`packages/ui`	Shared UI components
`packages/app-store`	Third-party integrations
`packages/lib`	Shared utilities
`packages/i18n`	Translation source strings