Reusing Prisma Package Between Next.js and Node.js Apps in a Monorepo with Turborepo

Monorepo architecture has become increasingly popular for managing multiple related applications in a single repository. This approach offers numerous benefits, such as easier code sharing, consistent versioning, and streamlined development workflows.

In this comprehensive guide, we'll explore how to share a Prisma package between a Next.js frontend and a Node.js (Express) backend in a monorepo setup using Turborepo. By the end, you'll have a fully functional monorepo with a shared database layer that can be used across multiple applications.

Why Use Monorepos with Turborepo?

Before diving into the implementation, let's understand why monorepos, and specifically Turborepo, are beneficial for modern application development:

Benefits of Monorepos

1. Simplified Dependency Management: All projects share the same dependency versions, eliminating version conflicts.
2. Atomic Changes: You can make changes across multiple projects in a single commit.
3. Code Sharing: Easily share code between projects without publishing packages.
4. Consistent Development Environment: Every developer works with the same setup.
5. Centralized Configuration: Maintain consistent linting, testing, and build configurations.

Why Turborepo?

Turborepo is a high-performance build system for JavaScript/TypeScript monorepos that provides:

1. Intelligent Caching: Turborepo caches build outputs, dramatically speeding up subsequent builds.
2. Parallel Execution: Tasks are automatically parallelized when possible.
3. Incremental Builds: Only rebuild what changed, not the entire codebase.
4. Task Dependencies: Define dependencies between tasks to ensure correct build order.
5. Remote Caching: Share build caches across your team and CI/CD pipelines.

Why Share a Prisma Package?

Sharing a Prisma package across applications in your monorepo offers several advantages:

1. Consistent Data Access: Ensures all applications access the database in the same way.
2. Type Safety: Share TypeScript types for your database models across applications.
3. Schema Synchronization: Maintain a single source of truth for your database schema.
4. Simplified Migrations: Manage database migrations from a single location.
5. Reduced Duplication: Avoid duplicating database access code and configuration.

Step-by-Step Guide to Setting Up the Monorepo

Let's build our monorepo from scratch, focusing on sharing a Prisma package between Next.js and Express applications.

1. Create a New Turborepo

First, let's initialize a new Turborepo:

npx create-turbo@latest my-monorepo
cd my-monorepo

This creates a basic monorepo structure with placeholder applications and packages.

2. Set Up the Directory Structure

Organize your monorepo with the following structure:

my-monorepo/
├── apps/
│   ├── web/                  # Next.js frontend
│   └── api/                  # Express backend
├── packages/
│   ├── prisma/               # Shared Prisma package
│   ├── eslint-config-custom/ # Shared ESLint config
│   └── tsconfig/             # Shared TypeScript config
├── package.json
└── turbo.json

3. Create the Shared Prisma Package

Let's set up the shared Prisma package:

mkdir -p packages/prisma
cd packages/prisma

Create a

package.json

{
  "name": "@repo/prisma",
  "version": "0.0.0",
  "private": true,
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "scripts": {
    "db:generate": "prisma generate",
    "db:push": "prisma db push --skip-generate",
    "db:migrate:dev": "prisma migrate dev",
    "db:migrate:deploy": "prisma migrate deploy",
    "db:reset": "prisma migrate reset --force",
    "db:studio": "prisma studio",
    "build": "tsup src/index.ts --format cjs,esm --dts"
  },
  "devDependencies": {
    "@types/node": "^18.0.0",
    "prisma": "^5.0.0",
    "tsup": "^6.0.0",
    "typescript": "^5.0.0"
  },
  "dependencies": {
    "@prisma/client": "^5.0.0"
  }
}

4. Initialize Prisma in the Shared Package

Initialize Prisma in the shared package:

cd packages/prisma
npx prisma init

This creates a

prisma

schema.prisma

.env

5. Configure the Prisma Schema

Edit the

prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
  output   = "../src/generated/client"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Notice we've set a custom output directory for the generated Prisma Client. This is important for proper integration in the monorepo structure.

6. Set Up Environment Variables

Create a

.env

packages/prisma

DATABASE_URL="postgresql://username:password@localhost:5432/mydatabase?schema=public"

Replace the connection string with your actual database credentials.

7. Export Prisma Client and Types

Create a

src

packages/prisma

index.ts

// packages/prisma/src/index.ts
export * from './generated/client';
export * from './client';

Create a

client.ts

// packages/prisma/src/client.ts
import { PrismaClient } from './generated/client';

// Create a singleton PrismaClient instance
let prismaClient: PrismaClient;

if (process.env.NODE_ENV === 'production') {
  prismaClient = new PrismaClient();
} else {
  // In development, use a global variable to prevent multiple instances during hot-reloading
  if (!global.prisma) {
    global.prisma = new PrismaClient();
  }
  prismaClient = global.prisma;
}

export const prisma = prismaClient;

8. Generate Prisma Client

Generate the Prisma client:

cd packages/prisma
npm run db:generate

9. Configure the Next.js App

Update the Next.js app to use the shared Prisma package:

First, add the dependency to

apps/web/package.json

{
  "dependencies": {
    "@repo/prisma": "*",
    // ...other dependencies
  }
}

Create a database utility file in

apps/web/lib/db.ts

// apps/web/lib/db.ts
import { prisma } from '@repo/prisma';

export { prisma };

Now you can use the Prisma client in your Next.js pages and API routes:

// apps/web/pages/users.tsx
import { GetServerSideProps } from 'next';
import { prisma } from '../lib/db';
import { User } from '@repo/prisma';

interface UsersPageProps {
  users: User[];
}

export default function UsersPage({ users }: UsersPageProps) {
  return (
    <div>
      <h1>Users</h1>
      <ul>
        {users.map((user) => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}

export const getServerSideProps: GetServerSideProps = async () => {
  const users = await prisma.user.findMany();
  return {
    props: {
      users: JSON.parse(JSON.stringify(users)),
    },
  };
};

10. Configure the Express App

Similarly, set up the Express app to use the shared Prisma package:

Add the dependency to

apps/api/package.json

{
  "dependencies": {
    "@repo/prisma": "*",
    "express": "^4.18.0",
    // ...other dependencies
  }
}

Create a database utility file in

apps/api/src/db.ts

// apps/api/src/db.ts
import { prisma } from '@repo/prisma';

export { prisma };

Use the Prisma client in your Express routes:

// apps/api/src/routes/users.ts
import express from 'express';
import { prisma } from '../db';

const router = express.Router();

// Get all users
router.get('/', async (req, res) => {
  try {
    const users = await prisma.user.findMany();
    res.json(users);
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch users' });
  }
});

// Get user by ID
router.get('/:id', async (req, res) => {
  const id = parseInt(req.params.id);
  try {
    const user = await prisma.user.findUnique({
      where: { id },
    });
    if (!user) {
      return res.status(404).json({ error: 'User not found' });
    }
    res.json(user);
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch user' });
  }
});

// Create user
router.post('/', async (req, res) => {
  const { email, name } = req.body;
  try {
    const user = await prisma.user.create({
      data: { email, name },
    });
    res.status(201).json(user);
  } catch (error) {
    res.status(500).json({ error: 'Failed to create user' });
  }
});

export default router;

11. Configure Turborepo to Handle Prisma Dependencies

Update the root

turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "db:generate": {
      "cache": false
    },
    "db:push": {
      "cache": false
    },
    "db:migrate:dev": {
      "cache": false
    },
    "db:migrate:deploy": {
      "cache": false
    },
    "build": {
      "dependsOn": ["^build", "^db:generate"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "dev": {
      "dependsOn": ["^db:generate"],
      "cache": false,
      "persistent": true
    },
    "start": {
      "dependsOn": ["build"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["build"]
    }
  }
}

This configuration ensures that Prisma client generation happens before building or starting the development server.

12. Managing Environment Variables

Proper environment variable management is crucial for a monorepo setup. Here's how to handle it effectively:

Development Environment

For local development, create separate

.env

1. Shared Prisma Package:

   packages/prisma/.env

   for database connection
2. Next.js App:

   apps/web/.env.local

   for app-specific variables
3. Express App:

   apps/api/.env

   for API-specific variables

Using dotenv-cli for Prisma Commands

To ensure Prisma commands use the correct environment variables, install

dotenv-cli

npm install -g dotenv-cli

Then update your Prisma scripts in

packages/prisma/package.json

{
  "scripts": {
    "db:generate": "dotenv -e .env -- prisma generate",
    "db:push": "dotenv -e .env -- prisma db push --skip-generate",
    "db:migrate:dev": "dotenv -e .env -- prisma migrate dev",
    "db:migrate:deploy": "dotenv -e .env -- prisma migrate deploy",
    "db:studio": "dotenv -e .env -- prisma studio"
  }
}

This ensures that each Prisma command uses the environment variables from the correct

.env

Advanced Configuration and Best Practices

Managing Prisma Migrations in Production

For production environments, you'll want to handle migrations carefully:

1. Migration Strategy: Use

   prisma migrate deploy

   in your CI/CD pipeline to apply migrations safely
2. Deployment Order: Always deploy database migrations before deploying your applications
3. Downtime Consideration: Plan for potential schema changes that might require downtime

Add a migration script to your CI/CD pipeline:

# Example GitHub Actions workflow
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy-migrations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - name: Deploy migrations
        run: npx turbo run db:migrate:deploy
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
  
  deploy-apps:
    needs: deploy-migrations
    runs-on: ubuntu-latest
    steps:
      # Deployment steps for your applications

Optimizing Prisma Client Generation

For large projects, Prisma client generation can be slow. Here are some optimization strategies:

1. Custom Output Directories: Configure the output directory based on your needs
2. Selective Builds: Use Turborepo's filtering to only build affected projects
3. Caching: Leverage Turborepo's caching to avoid regenerating the client unnecessarily

Handling Multiple Environments

For projects with multiple environments (development, staging, production), consider these strategies:

1. Environment-specific .env Files: Use

   .env.development

   ,

   .env.staging

   ,

   .env.production

2. Environment Selection Script: Create a script to select the correct environment

// packages/prisma/scripts/select-env.js
const fs = require('fs');
const path = require('path');

const env = process.argv[2] || 'development';
const source = path.join(__dirname, '../.env.' + env);
const target = path.join(__dirname, '../.env');

fs.copyFileSync(source, target);
console.log(`Using environment: ${env}`);

Then update your package.json scripts:

{
  "scripts": {
    "use:dev": "node scripts/select-env.js development",
    "use:staging": "node scripts/select-env.js staging",
    "use:prod": "node scripts/select-env.js production"
  }
}

Troubleshooting Common Issues

Environment Variable Not Found

If you encounter "Environment variable not found: DATABASE_URL" errors, try:

1. Check that your

   .env

   file is in the correct location (same directory as schema.prisma)
2. Ensure there are no syntax errors in your

   .env

   file
3. Run

   npx prisma generate

   to re-establish the link between schema.prisma and .env
4. Use

   dotenv-cli

   to explicitly load environment variables:

npx dotenv -e .env -- npx prisma db push

Multiple Prisma Client Instances

When using Next.js, you might create multiple Prisma Client instances during development due to hot-reloading. Ensure you're using a singleton pattern as shown in the client.ts file above.

Type Errors Between Packages

If you encounter TypeScript errors related to Prisma types:

1. Make sure you've run

   npx prisma generate

   after any schema changes
2. Check that your build order is correct (prisma package should build before apps)
3. Verify that import paths are correct in all files

Running the Monorepo

Now that everything is set up, let's run our monorepo:

Install Dependencies

From the root directory:

npm install

Generate Prisma Client

npx turbo run db:generate

Apply Database Migrations

cd packages/prisma
npm run db:migrate:dev

Start Development Servers

From the root directory:

npx turbo run dev

This will start both the Next.js and Express development servers.

Conclusion

In this comprehensive guide, we've covered how to set up a monorepo with Turborepo to share a Prisma package between Next.js and Express applications. This approach provides a clean, efficient way to manage database access across multiple applications.

By centralizing your database schema and access patterns, you can ensure consistency across your applications while taking advantage of Prisma's type safety and powerful query capabilities.

The monorepo approach also streamlines your development workflow, making it easier to make changes that span multiple applications and ensuring that your team works with consistent dependencies and configurations.

Additional Resources

• Turborepo Documentation
• Prisma Documentation
• Next.js Documentation
• Express Documentation

With these tools and techniques, you're well-equipped to build scalable, maintainable applications using a monorepo approach.