Services: Server-side Prisma Queries for Server Components

You implement server-only service functions that run Prisma SELECT and COUNT queries for Next.js Server Components (RSC).

These services live in

@src/services/

, are domain-scoped, have easy-to-understand names, and are re-exported via

@src/services/index.ts

. They use the Prisma type patterns defined in the prisma types skill(Prisma.validator + GetPayload) for return types.

When to use this skill

Use this skill when the user asks to:

add/refactor server-side Prisma reads used in Server Components
implement list pages with pagination, filtering, sorting, and total counts
organize server data access in a
```
services/
```
folder
ensure return types match the project’s
```
types/<domain>/...
```
patterns

Folder & naming conventions

Services live here:
```
@src/services/<domain>/...
```

File names are domain-specific and descriptive:

```
@src/services/users/get-users.ts
```

@src/services/events/get-event-previews.ts

@src/services/workspaces/get-workspace-members.ts

Exported in:
```
@src/services/index.ts
```

Each service function name is a clear verb phrase:

getUsers

getWorkspaceMembers

getEventPreviews

countUsers

Hard rules

Server-only: add
```
"use server"
```
at the top of each service file.
Read-only responsibilities: these services are for SELECT/COUNT for server rendering.
- Mutations belong in tRPC controllers (unless the user explicitly wants a server action for a mutation).
Type-safe outputs: the returned model shapes must come from the Prisma type-settings skill:
- Define reusable
```
select
```
  /
```
include
```
  objects in
```
types/<domain>/...
```
- Derive payload types via
```
Prisma.<Model>GetPayload<...>
```
Parallelize data + count: for paginated lists, fetch
```
findMany
```
and
```
count
```
in
```
Promise.all
```
.
Avoid overfetching: always use
```
select
```
(preferred) or strict
```
include
```
.
Deterministic ordering: if sorting by a non-unique field (e.g.
```
createdAt
```
), add a tie-breaker order by
```
id
```
to keep pagination stable.
Validate/whitelist sorting keys: never pass arbitrary
```
sortBy
```
directly into
```
orderBy
```
without a whitelist.
Performance-aware counts: use
```
db.<model>.count({ where })
```
for simple counts; if count becomes complex and slow, consider raw SQL read optimization per Prisma querying skill (but keep this as an exception and keep it parameterized).

Service function structure

Each service file should typically contain:

```
"use server"
```
```
db
```
import from
```
~/server/db
```
An
```
Options
```
interface (only if needed)
```
where
```
builder (search/filter)
```
orderBy
```
builder with a whitelist
```
Promise.all([findMany, count])
```
Return a typed result object

Recommended return shape for list endpoints

{
  items: T[];
  totalCount: number;
  page: number;
  pageSize: number;
  totalPages: number;
}

Use domain-appropriate names (

users

events

) if that improves clarity, but keep the structure consistent.

Typing: reference the Prisma type-settings skill

Do not hand-write response shapes for Prisma models. Instead:

1) Define a reusable select in

@src/types/<domain>/...

Example:

```
src/types/users/user.select.ts
```
```
src/types/users/user.types.ts
```

// src/types/users/user.select.ts
import { Prisma } from "@prisma/client";

export const userListSelect = Prisma.validator<Prisma.UserSelect>()({
  id: true,
  name: true,
  email: true,
  emailVerified: true,
  isAdmin: true,
  createdAt: true,
});

You can read more about this in the types skill

// src/types/users/user.types.ts
import { Prisma } from "@prisma/client";
import { userListSelect } from "./user.select";

export type UserListItem = Prisma.UserGetPayload<{
  select: typeof userListSelect;
}>;

2) Use those exports in the service and type the return

// src/services/users/get-users.ts
"use server";

import { db } from "~/server/db";
import { userListSelect } from "~/types/users/user.select";
import type { UserListItem } from "~/types/users/user.types";

interface GetUsersOptions {
  page?: number;
  pageSize?: number;
  search?: string;
  sortBy?: "createdAt" | "name" | "email"; // whitelist
  sortOrder?: "asc" | "desc";
}

type GetUsersResult = {
  users: UserListItem[];
  totalCount: number;
  page: number;
  pageSize: number;
  totalPages: number;
};

export async function getUsers(options: GetUsersOptions = {}): Promise<GetUsersResult> {
  const {
    page = 1,
    pageSize = 10,
    search = "",
    sortBy = "createdAt",
    sortOrder = "desc",
  } = options;

  const safePage = Math.max(1, page);
  const safePageSize = Math.min(Math.max(1, pageSize), 200);
  const skip = (safePage - 1) * safePageSize;

  const where = search
    ? {
        OR: [
          { name: { contains: search, mode: "insensitive" as const } },
          { email: { contains: search, mode: "insensitive" as const } },
        ],
      }
    : {};

  // Stable ordering: requested field + id tie-breaker
  const orderBy = [{ [sortBy]: sortOrder } as const, { id: "asc" as const }];

  const [users, totalCount] = await Promise.all([
    db.user.findMany({
      where,
      select: userListSelect,
      orderBy,
      skip,
      take: safePageSize,
    }),
    db.user.count({ where }),
  ]);

  return {
    users,
    totalCount,
    page: safePage,
    pageSize: safePageSize,
    totalPages: Math.ceil(totalCount / safePageSize),
  };
}

Index exports

Every domain service must be exported via

src/services/index.ts

// src/services/index.ts
export * from "./users/get-users";
export * from "./events/get-event-previews";

If you also keep per-domain

index.ts

files, export them from the root.

Usage in Next.js Server Components

In a Server Component:

tsx

import { getUsers } from "~/services";

export default async function UsersPage({ searchParams }: { searchParams: Record<string, string | string[]> }) {
  const page = Number(searchParams.page ?? 1);

  const data = await getUsers({
    page,
    pageSize: 20,
    search: typeof searchParams.q === "string" ? searchParams.q : "",
    sortBy: "createdAt",
    sortOrder: "desc",
  });

  return (
    <div>
      <div>Total: {data.totalCount}</div>
      {/* render data.users */}
    </div>
  );
}

Advanced guidance

Sorting whitelist (required)

Never do:

orderBy: { [sortBy]: sortOrder }

unless

sortBy

is a union of known keys (or validated via a whitelist map). Preferred pattern:

const SORT_KEYS = {
  createdAt: "createdAt",
  name: "name",
  email: "email",
} as const;

type SortBy = keyof typeof SORT_KEYS;

Search performance

For large tables:

Ensure indexes exist for high-selectivity filters.
Consider full-text search or trigram indexes in Postgres if
```
contains
```
search becomes slow (only if the user asks for scaling guidance).

When count is too slow

count

becomes a bottleneck (complex filters/joins), you may:

keep
```
findMany
```
in Prisma
use parameterized raw SQL for the count query (read-only) per the Prisma querying skill
document why this exception is used

Output format when implementing a new service

When asked to create a service, output:

```
types/<domain>/...
```
select + payload type (if missing)
```
services/<domain>/<service>.ts
```
implementation
```
services/index.ts
```
export
Example Server Component usage

Cross-skill references

Prisma type-settings skill: all service return shapes that include Prisma model data must be typed via
```
Prisma.validator()
```
+
```
GetPayload
```
in
```
types/<domain>/...
```
.
Prisma database-querying skill: raw SQL is acceptable for SELECT/COUNT only when Prisma cannot express the query efficiently; mutations stay in Prisma Client or tRPC controllers unless specified.

query-service

NPX Install

Tags

SKILL.md Content