@trycompai/db 1.1.0 → 1.1.1

package/INTEGRATION_GUIDE.md

@@ -0,0 +1,360 @@
+# Integration Guide: Using @trycompai/db in Another Turborepo
+
+This guide walks you through integrating the `@trycompai/db` package into another Turborepo-based repository.
+
+## Prerequisites
+
+- Node.js 18+ and npm/yarn/bun
+- A Turborepo-based project
+- PostgreSQL database (local or cloud)
+
+## Step 1: Install the Package
+
+In your app directory (e.g., `apps/web` or `apps/api`):
+
+```bash
+cd apps/your-app
+bun add @trycompai/db @prisma/client prisma
+```
+
+## Step 2: Set Up Environment Variables
+
+Create or update `.env` in your app directory:
+
+```env
+DATABASE_URL="postgresql://user:password@localhost:5432/your_database"
+```
+
+## Step 3: Generate Prisma Client
+
+Run from your app directory:
+
+```bash
+npx prisma generate --schema=node_modules/@trycompai/db/dist/prisma/schema.prisma
+```
+
+**Pro tip**: Add this to your app's `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "db:generate": "prisma generate --schema=node_modules/@trycompai/db/dist/prisma/schema.prisma",
+    "postinstall": "npm run db:generate"
+  }
+}
+```
+
+## Step 4: Create Database Instance
+
+Create `lib/db.ts` (or `src/lib/db.ts`) in your app:
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const db =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+  });
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = db;
+```
+
+## Step 5: Update Turborepo Configuration
+
+Add to your root `turbo.json`:
+
+```json
+{
+  "pipeline": {
+    "db:generate": {
+      "cache": false,
+      "outputs": ["node_modules/.prisma/**"]
+    }
+  }
+}
+```
+
+## Step 6: Use in Your Application
+
+### In Next.js Server Components
+
+```typescript
+import { db } from '@/lib/db';
+import type { User } from '@trycompai/db';
+
+export default async function UsersPage() {
+  const users: User[] = await db.user.findMany();
+
+  return (
+    <div>
+      {users.map(user => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### In API Routes (Next.js App Router)
+
+```typescript
+import { NextResponse } from 'next/server';
+import { db } from '@/lib/db';
+import type { Prisma } from '@trycompai/db';
+
+export async function POST(request: Request) {
+  const data = (await request.json()) as Prisma.UserCreateInput;
+
+  const user = await db.user.create({
+    data,
+  });
+
+  return NextResponse.json(user);
+}
+```
+
+### In Server Actions
+
+```typescript
+'use server';
+
+import { db } from '@/lib/db';
+import type { User, Prisma } from '@trycompai/db';
+
+export async function createUser(data: Prisma.UserCreateInput): Promise<User> {
+  return await db.user.create({ data });
+}
+```
+
+### In tRPC Procedures
+
+```typescript
+import { z } from 'zod';
+import { router, publicProcedure } from '@/server/trpc';
+import { db } from '@/lib/db';
+import type { User } from '@trycompai/db';
+
+export const userRouter = router({
+  getAll: publicProcedure.query(async (): Promise<User[]> => {
+    return await db.user.findMany();
+  }),
+
+  create: publicProcedure
+    .input(
+      z.object({
+        email: z.string().email(),
+        name: z.string(),
+      }),
+    )
+    .mutation(async ({ input }) => {
+      return await db.user.create({
+        data: input,
+      });
+    }),
+});
+```
+
+## Step 7: TypeScript Configuration
+
+Ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"],
+      "@trycompai/db": ["node_modules/@trycompai/db"]
+    }
+  }
+}
+```
+
+## Common Patterns
+
+### Type-Safe Queries
+
+```typescript
+import type { Prisma } from '@trycompai/db';
+
+// Type-safe where clauses
+const whereClause: Prisma.UserWhereInput = {
+  email: { contains: '@example.com' },
+  createdAt: { gte: new Date('2024-01-01') },
+};
+
+const users = await db.user.findMany({ where: whereClause });
+```
+
+### Including Relations
+
+```typescript
+const usersWithOrganizations = await db.user.findMany({
+  include: {
+    organization: true,
+    memberships: {
+      include: {
+        organization: true,
+      },
+    },
+  },
+});
+```
+
+### Transactions
+
+```typescript
+import type { User, Organization } from '@trycompai/db';
+
+const result = await db.$transaction(async (tx) => {
+  const org = await tx.organization.create({
+    data: { name: 'New Org' },
+  });
+
+  const user = await tx.user.create({
+    data: {
+      email: 'user@example.com',
+      name: 'John Doe',
+      organizationId: org.id,
+    },
+  });
+
+  return { user, org };
+});
+```
+
+## Turborepo-Specific Tips
+
+### 1. Workspace Dependencies
+
+In your app's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@trycompai/db": "^1.1.0"
+  }
+}
+```
+
+### 2. Development Workflow
+
+```bash
+# From root of your turborepo
+turbo run dev --filter=your-app
+
+# Run database generation across all apps
+turbo run db:generate
+```
+
+### 3. CI/CD Pipeline
+
+Add to your CI workflow:
+
+```yaml
+- name: Generate Prisma Client
+  run: turbo run db:generate
+```
+
+## Troubleshooting
+
+### "Cannot find module '@prisma/client'"
+
+Run `npx prisma generate --schema=node_modules/@trycompai/db/dist/prisma/schema.prisma` in your app directory.
+
+### "PrismaClient is unable to be run in the browser"
+
+Ensure you're only importing and using the database client in server-side code:
+
+- Server Components
+- API Routes
+- Server Actions
+- Backend services
+
+### Type errors with Prisma types
+
+1. Ensure `@prisma/client` version matches the one in `@trycompai/db`
+2. Regenerate the client: `npm run db:generate`
+3. Restart TypeScript server in your IDE
+
+### Connection issues
+
+1. Verify `DATABASE_URL` is set correctly
+2. Check database is running and accessible
+3. For SSL connections, add `?sslmode=require` to your connection string
+
+## Best Practices
+
+1. **Never import `db` in client components** - it will fail at runtime
+2. **Use type imports for client code**: `import type { User } from '@trycompai/db'`
+3. **Handle errors gracefully** - wrap database calls in try/catch
+4. **Use transactions** for operations that must succeed together
+5. **Enable query logging** only in development to avoid performance impact
+
+## Example Full Setup
+
+Here's a complete example for a Next.js app in a Turborepo:
+
+```typescript
+// apps/web/lib/db.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const db =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
+  });
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = db;
+
+// apps/web/app/users/page.tsx
+import { db } from '@/lib/db';
+import type { User } from '@trycompai/db';
+
+export default async function UsersPage() {
+  const users: User[] = await db.user.findMany({
+    orderBy: { createdAt: 'desc' },
+  });
+
+  return (
+    <div>
+      <h1>Users ({users.length})</h1>
+      {users.map(user => (
+        <div key={user.id}>
+          <h2>{user.name}</h2>
+          <p>{user.email}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Schema Information
+
+The package maintains **separate schemas for development and distribution**:
+
+**Development**: Multiple organized schema files in `prisma/schema/` for better maintainability
+**Distribution**: Single combined `dist/prisma/schema.prisma` file for consumers
+
+The build process combines:
+
+- Base configuration and datasource
+- All model definitions from the `schema/` directory
+- Proper relationships and constraints
+
+This ensures your development setup stays clean while providing consumers with a simple single-file schema.
+
+## Need Help?
+
+- Check the [Prisma documentation](https://www.prisma.io/docs)
+- Review the combined schema at `node_modules/@trycompai/db/dist/prisma/schema.prisma`
+- Look at type definitions with IDE autocomplete

package/README.md

@@ -23,7 +23,7 @@ bun add @trycompai/db @prisma/client prisma
 
 ```bash
 # Run this in your app directory after installing
-npx prisma generate --schema=node_modules/@trycompai/db/prisma/schema.prisma
+npx prisma generate --schema=node_modules/@trycompai/db/dist/prisma/schema.prisma
 ```
 
 2. **Create your database instance** (`lib/db.ts`):
@@ -77,3 +77,7 @@ To update the schema:
 2. Run migrations: `bun run db:migrate`
 3. Regenerate types: `bun run build`
 4. Update version and publish
+
+## Integration Guide
+
+For detailed instructions on using this package in another Turborepo, see [INTEGRATION_GUIDE.md](./INTEGRATION_GUIDE.md).