#PNPM Monorepo Setup

8 messages · Page 1 of 1 (latest)

prime tokenBOT
#

Hi @sleek condor. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

To set up a pnpm monorepo with Convex, where you have an apps/web folder for your Next.js 15 project and a packages/backend folder for your Convex backend, you can follow a structure and workflow similar to the official Convex monorepo templates and community recommendations. Here’s a step-by-step guide based on the available knowledge sources:

1. Monorepo Structure

Your directory structure should look like this:

your-monorepo/
├── apps/
│   └── web/           # Your Next.js 15 app
├── packages/
│   └── backend/       # Your Convex backend
├── package.json       # Monorepo root
├── pnpm-workspace.yaml

2. Initialize the Monorepo

  • At the root, run:
    pnpm init
  • Create a pnpm-workspace.yaml file at the root with:
    packages:
  - 'apps/*'
  - 'packages/*'

3. Set Up the Next.js App

  • In apps/web, initialize your Next.js project:
    cd apps
pnpm create next-app web
  • Install dependencies as needed.

4. Set Up the Convex Backend

  • In packages/backend, initialize a package:
    cd ../../packages
mkdir backend && cd backend
pnpm init
  • Install Convex:
    pnpm add convex
  • Initialize Convex:
    npx convex dev
    This will create a convex/ directory inside packages/backend for your backend functions and schema.

5. Link Convex to Your Next.js App

  • In your Next.js app (apps/web), install the Convex client:
    pnpm add convex
  • Reference the Convex API types and generated code from packages/backend/convex/_generated in your Next.js app. You may need to set up TypeScript path aliases or use a symlink if you want to import shared types or generated API code.

6. Development Workflow

#
  • Run Convex dev server from packages/backend:
    cd packages/backend
npx convex dev
  • Run your Next.js app from apps/web:
    cd apps/web
pnpm dev

7. Deployment

For deploying with Vercel or similar, you may need to customize your build commands to ensure Convex functions are deployed before your frontend builds. For example, you might use a command like:

cd ../../packages/backend && npx convex deploy --cmd 'cd ../../apps/web && pnpm build' --cmd-url-env-var-name NEXT_PUBLIC_CONVEX_URL

This ensures your Convex backend is deployed and the correct environment variables are set for your frontend build. Adjust paths as needed for your setup Deploying Convex in a Turborepo.

8. Reference Templates

Note:

  • You may need to adjust TypeScript configurations and path aliases for smooth type sharing.
  • If you encounter issues with code generation or type sharing, see the multiple repos guide for exporting types.
#

This setup is based on community best practices and official templates. If you need more specific configuration (e.g., for authentication or advanced type sharing), refer to the linked templates and guides above.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@sleek condor Kapa.ai is still learning and improving, please let me know how I did by reacting below.

prime tokenBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

To add Postgres to your self-hosted Convex setup using Docker Compose and ensure Convex uses the locally hosted Postgres database, follow these steps:

1. Add Postgres to docker-compose.yml

Extend your docker-compose.yml to include a Postgres service. Here’s an example snippet:

services:
  backend:
    image: ghcr.io/get-convex/convex-backend:latest
    ports:
      - "3210:3210"
      - "3211:3211"
    environment:
      - POSTGRES_URL=postgresql://postgres:postgres@postgres:5432
      - DO_NOT_REQUIRE_SSL=1
    depends_on:
      - postgres
    volumes:
      - data:/convex/data

  postgres:
    image: postgres:15
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  dashboard:
    image: ghcr.io/get-convex/convex-dashboard:latest
    ports:
      - "6791:6791"
    environment:
      - NEXT_PUBLIC_DEPLOYMENT_URL=<http://localhost:3210>
    depends_on:
      backend:
        condition: service_healthy

volumes:
  data:
  pgdata:

2. Create the Database

Convex expects a database named convex_self_hosted in your Postgres instance. You can create it by running:

docker compose exec postgres psql -U postgres -c "CREATE DATABASE convex_self_hosted;"

Source: Self-hosted README

3. Set the POSTGRES_URL Environment Variable

  • The POSTGRES_URL should not include the database name. For example:
    POSTGRES_URL=postgresql://postgres:postgres@postgres:5432
  • Convex will automatically use the convex_self_hosted database.

Source: Self-hosted README

4. Start the Services

Run:

# 
docker compose up

Check the Convex backend logs for a line like Connected to Postgres to confirm the connection.

Note:

  • Make sure the backend and Postgres containers are on the same Docker network (which is the default in Compose).
  • The further your database is from your Convex backend, the slower your app will be, so local Compose is ideal for development Stack Convex Self-hosted Guide.

This setup ensures your self-hosted Convex backend uses a locally hosted Postgres database via Docker Compose, following the official documentation and recommendations.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: