playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / data-access-layer

data-access-layer skill

/skills/nextjs/data-access-layer

This skill enforces a secure, centralized data access layer with DTOs, server-only imports, and auth checks co-located in access functions.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill data-access-layer

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.4 KB
---
name: Next.js Data Access Layer
description: Secure, reusable data access patterns with DTOs and Taint checks.
metadata:
  labels: [nextjs, dal, architecture, security]
  triggers:
    files: ['**/lib/data.ts', '**/services/*.ts', '**/dal/**']
    keywords: [DAL, Data Access Layer, server-only, DTO]
---

# Data Access Layer (DAL)

## **Priority: P1 (HIGH)**

Centralize all data access (Database & External APIs) to ensure consistent security, authorization, and caching.

## Principles

1. **Server-Only**: Must include `import 'server-only'` to prevent Client bundling.
2. **Auth Co-location**: Auth checks (`session.role`) must be **inside** the DAL function.
3. **DTO Transformation**: Return plain objects (DTOs), never raw ORM instances.
4. **No Internal Fetch**: Call DAL functions directly. Do not `fetch('localhost/api')`.

## Implementation

| Approach              | When to use                                      | Reference                           |
| :-------------------- | :----------------------------------------------- | :---------------------------------- |
| **API Gateway (BFF)** | Enterprise apps with separated Backend (NestJS). | [Pattern A](references/patterns.md) |
| **Direct DB**         | Fullstack apps or Admin Panels.                  | [Pattern B](references/patterns.md) |

## Limitations

- **Client Components**: Cannot import DAL files. Must use Server Actions or Route Handlers as bridges.

Overview

This skill defines a secure, reusable Data Access Layer (DAL) pattern for Next.js applications using TypeScript. It enforces server-only execution, colocated authorization, DTO returns, and prevents unsafe internal HTTP calls. The result is consistent security, clearer boundaries, and safer data flows across your app.

How this skill works

DAL modules are implemented as server-only functions (import 'server-only') that encapsulate all database and external API access. Each DAL function performs authorization checks inside the function, transforms results into plain DTOs, and returns those DTOs rather than ORM instances. Server Actions or Route Handlers bridge Client components to the DAL; Client components never import DAL files directly.

When to use it

  • Centralize data access and authorization in any Next.js app to ensure consistent security.
  • Build enterprise apps that require an API Gateway or BFF to coordinate multiple backends.
  • Implement admin panels or fullstack features that need direct database access with strict checks.
  • Prevent accidental client bundling of server code and reduce surface area for data leaks.
  • Standardize patterns across teams and languages for maintainability and auditing.

Best practices

  • Always include import 'server-only' at the top of DAL files to forbid client bundling.
  • Perform auth checks (e.g., session.role) inside the DAL function, not in callers.
  • Return plain DTOs: map ORM entities to simple objects and strip methods and metadata.
  • Call DAL functions directly from server code—avoid fetch('http://localhost/...') to reach your own backend.
  • Use Server Actions or Route Handlers as the only bridges between Client components and DAL.
  • Choose API Gateway (BFF) for separated backend architectures and Direct DB for monolith/fullstack apps.

Example use cases

  • User service: DAL function validates session role, queries DB, returns a user DTO without ORM internals.
  • Billing: Server-only DAL calls external payment APIs, enforces permission checks, returns sanitized DTOs.
  • Admin dashboard: Direct DB DAL used for high-trust operations with strict server-side authorization.
  • Microservices integration: BFF DAL aggregates multiple services and returns normalized DTOs to the app.

FAQ

Can Client components import DAL files?

No. Client components must use Server Actions or Route Handlers to access DAL functions because DAL files are server-only.

Why return DTOs instead of ORM instances?

DTOs remove runtime methods and metadata, reduce accidental data exposure, and make serialization predictable across server boundaries.