Setup

Arkos.js integrates seamlessly with Prisma ORM, providing auto-generated RESTful endpoints for your models, enhanced type inference, and built-in query capabilities.

Prerequisites

Before setting up Prisma with Arkos, ensure you have:

• A database connection string ready (PostgreSQL, MySQL, MongoDB, SQLite, etc.)
• Arkos.js installed in your project (see Installation)

Setting Up Prisma

1. Install Prisma Dependencies

npm install @prisma/client
npm install --save-dev prisma

pnpm add @prisma/client
pnpm add -D prisma

2. Initialize Prisma

npx prisma init

This creates:

• prisma/schema.prisma — Your database schema
• .env — Environment variables (if not exists)

2.5. Generate a Model (Optional)

Instead of manually writing Prisma models, you can use the Arkos CLI to generate one:

npx arkos generate model --module new-model-name
# or shorthand:
npx arkos g m -m new-model-name

This creates the Prisma model with basic fields common along all other existing models or simply basic one. See the Code Generation Guide for all options.

3. Configure Prisma Schema

Edit prisma/schema.prisma to point to your database and define models:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql" // or mysql, mongodb, sqlite, etc.
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

4. Configure Database Connection

Add your database connection string to .env:

DATABASE_URL="postgresql://username:password@localhost:5432/mydb"

5. Create Prisma Client Instance

Arkos requires your Prisma client to be exported as default from src/utils/prisma/index.ts (or .js for JavaScript):

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

export default prisma;

6. Generate Prisma Client and Arkos Types

npx arkos prisma generate

Database Initialization

After setup, initialize your database:

npx prisma db push

npx prisma migrate dev --name init

Next Steps

Now that Prisma is set up with Arkos:

• Create modules — Add a module directory for each model you want to customize
• Configure authentication — Set up access control for your generated routes
• Add validation — Define Zod schemas or class-validator DTOs for request bodies
• Customize queries — Use default query options to control field selection, includes, and sorting
• Intercept operations — Add before/after logic to your model endpoints

Troubleshooting

Prisma Client Not Found

If you see Cannot find module '@prisma/client', run:

npx arkos prisma generate

Database Connection Errors

Verify your DATABASE_URL in .env is correct and the database is accessible.

Type Errors in TypeScript

Make sure you've run npx arkos prisma generate after making changes to your Prisma schema.

Model Routes Not Generated

Check that:

• Your Prisma client is exported from src/utils/prisma/index.ts
• The prisma field in package.json points to the correct schema location
• You have at least one model defined in your Prisma schema