Skip to content
flexcal Documentation

Development setup

Prerequisites

Section titled “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

Section titled “Clone and install”
Terminal window
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:

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

Environment

Section titled “Environment”
Terminal window
cp .env.example .env

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

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

Quick start

Section titled “Quick start”

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

Terminal window
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

Sign in at http://localhost:3000.

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

Manual setup

Section titled “Manual setup”

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

  1. 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>.

  2. Copy .env.appStore.example to .env.appStore and paste the same DATABASE_URL into it.

  3. Apply the schema (packages/prisma/schema.prisma):

    Terminal window
    bun run --cwd packages/prisma db-migrate

  4. 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

  5. Run the dev server:

    Terminal window
    bun run dev

  6. Seed dummy users if you want them:

    Terminal window
    bun run --cwd packages/prisma db-seed

Everyday commands

Section titled “Everyday commands”
Terminal window
# 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

Section titled “Tips”

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

Terminal window
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

Section titled “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