opensaas-migration

# OpenSaaS Stack Migration

Expert guidance for migrating existing projects to OpenSaaS Stack.

## When to Use This Skill

Use this skill when:

- Planning a migration from Prisma, KeystoneJS, or Next.js
- Designing access control patterns
- Configuring `opensaas.config.ts`
- Troubleshooting migration issues
- Explaining OpenSaaS Stack concepts

## Migration Process

### 1. Install Required Packages

**IMPORTANT: Always install packages before starting migration**

Detect the user's package manager (check for `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, or `bun.lockb`) and use their preferred package manager.

**Required packages:**

```bash
# Using npm
npm install --save-dev @opensaas/stack-cli
npm install @opensaas/stack-core

# Using pnpm
pnpm add -D @opensaas/stack-cli
pnpm add @opensaas/stack-core

# Using yarn
yarn add -D @opensaas/stack-cli
yarn add @opensaas/stack-core

# Using bun
bun add -D @opensaas/stack-cli
bun add @opensaas/stack-core
```

**Optional packages (based on user needs):**

- `@opensaas/stack-auth` - If the project needs authentication
- `@opensaas/stack-ui` - If the project needs the admin UI
- `@opensaas/stack-tiptap` - If the project needs rich text editing
- `@opensaas/stack-storage` - If the project needs file storage
- `@opensaas/stack-rag` - If the project needs semantic search/RAG

**Database adapters (required for Prisma 7):**

SQLite:

```bash
npm install better-sqlite3 @prisma/adapter-better-sqlite3
```

PostgreSQL:

```bash
npm install pg @prisma/adapter-pg
```

Neon (serverless PostgreSQL):

```bash
npm install @neondatabase/serverless @prisma/adapter-neon ws
```

### 2. Uninstall Old Packages (KeystoneJS Only)

**IMPORTANT: For KeystoneJS projects, uninstall KeystoneJS packages before installing OpenSaaS**

KeystoneJS migrations should preserve the existing file structure and just swap packages. Do NOT create a new project structure.

```bash
# Detect package manager and uninstall KeystoneJS packages
npm uninstall @keyst