Repository pattern for data access in NextJS - Deep Dive

Overview - Repository pattern for data access

What is it?

The Repository pattern is a way to organize how your app talks to data sources like databases or APIs. It acts like a middleman that hides the details of data access from the rest of your app. This means your app can ask for data without worrying about where it comes from or how it is stored. In Next.js, it helps keep your code clean and easier to maintain.

Why it matters

Without the Repository pattern, your app code would be tangled with database or API calls everywhere. This makes it hard to change data sources or fix bugs because you have to hunt through many files. Using this pattern means you can swap or update data access in one place, making your app more flexible and reliable. It also helps teams work together by clearly separating concerns.

Where it fits

Before learning this, you should understand basic Next.js app structure, JavaScript async/await, and how to fetch data. After this, you can learn about advanced state management, caching strategies, or API design. The Repository pattern fits in the middle as a clean way to handle data fetching and storage logic.

Mental Model

Core Idea

The Repository pattern is a dedicated layer that handles all data fetching and saving, so the rest of your app doesn't need to know how data is stored or retrieved.

Think of it like...

Imagine a restaurant where you order food from a waiter instead of going into the kitchen yourself. The waiter (repository) knows how to get the food (data) from the kitchen (database or API) and brings it to you, so you don't have to worry about cooking or where ingredients come from.

App Layer
  │
  ▼
Repository Layer
  │
  ▼
Data Source (Database / API)

Each arrow means 'asks for data' or 'saves data'. The app talks only to the repository, which talks to the data source.

Build-Up - 6 Steps

1

Foundation

Understanding data access basics

Concept: Learn how Next.js fetches data and why direct data calls can cause problems.

In Next.js, you often fetch data inside API routes or server components using fetch or database clients. If you put these calls everywhere, your code becomes messy and hard to change. For example, if you want to switch from one database to another, you must update many files.

Result

You see that direct data calls spread across your app make maintenance difficult.

Understanding the pain of scattered data access motivates the need for a central place to handle it.

2

Foundation

What is the Repository pattern?

Concept: Introduce the Repository pattern as a single place to manage data operations.

The Repository pattern creates a dedicated module or class that has methods like getUser, savePost, or deleteComment. Your app calls these methods instead of talking directly to the database or API. This hides the data source details and provides a clean interface.

Result

You have a clear separation: app code calls repository methods, repository handles data fetching.

Knowing that a repository acts as a middleman helps you organize code and reduce duplication.

3

Intermediate

Implementing a basic repository in Next.js

🤔Before reading on: do you think the repository should return raw database results or clean JavaScript objects? Commit to your answer.

Concept: Create a simple repository module that fetches data from an API or database and returns clean data.

Example: Create a file userRepository.js with async functions like getUserById(id) that fetch user data from an API endpoint or database client. The repository converts raw data into plain objects your app can use easily.

Result

Your app imports userRepository and calls getUserById without knowing how data is fetched.

Understanding that repositories can transform data before returning it improves app consistency and reduces bugs.

4

Intermediate

Handling multiple data sources in repository

🤔Before reading on: do you think a repository should know about all data sources or just one? Commit to your answer.

Concept: Learn how a repository can combine data from different sources or switch between them.

Sometimes data comes from a database and sometimes from a third-party API. The repository can decide which source to use or merge data from both. For example, userRepository might fetch user profile from the database and user activity from an external API, then combine results.

Result

Your app still calls one method, but the repository handles complex data fetching logic.

Knowing that repositories can hide complex data logic lets you build flexible and scalable apps.

5

Advanced

Using dependency injection with repositories

🤔Before reading on: do you think repositories should create their own database clients or receive them from outside? Commit to your answer.

Concept: Learn to inject dependencies like database clients into repositories for better testing and flexibility.

Instead of creating a database connection inside the repository, pass it as a parameter. This allows you to swap the database client in tests or different environments. For example, pass a mock client during testing to avoid real database calls.

Result

Repositories become easier to test and configure without changing their code.

Understanding dependency injection improves code modularity and testability.

6

Expert

Optimizing repositories with caching and batching

🤔Before reading on: do you think repositories should only fetch data or also optimize how often they fetch? Commit to your answer.

Concept: Explore advanced techniques like caching results or batching multiple requests inside repositories.

Repositories can store fetched data temporarily to avoid repeated calls (caching). They can also combine multiple requests into one batch to reduce network or database load. For example, a repository might cache user data for a few minutes or batch multiple user ID requests into a single database query.

Result

Your app runs faster and uses fewer resources without changing how it calls the repository.

Knowing that repositories can optimize data access transparently leads to better performance and user experience.

Under the Hood

The repository pattern works by creating an abstraction layer that exposes simple methods for data operations. Internally, these methods use database clients, API calls, or other data sources. This layer manages connections, queries, data transformation, and error handling. The app only interacts with this layer, so it never deals directly with raw data sources or protocols.

Why designed this way?

It was designed to separate concerns: app logic should not mix with data access details. This separation makes code easier to maintain, test, and evolve. Historically, apps tightly coupled to databases were hard to change. The repository pattern emerged to provide a stable interface while allowing data sources to change underneath.

┌─────────────┐       ┌─────────────────────┐       ┌───────────────┐
│  App Layer  │──────▶│ Repository Layer     │──────▶│ Data Sources  │
│ (UI, Logic) │       │ (Methods: get/save) │       │ (DB, API)    │
└─────────────┘       └─────────────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does the repository pattern mean you must use classes instead of functions? Commit to yes or no.

Common Belief: Many think repositories must be classes with methods.

Reality: Repositories can be simple modules with functions or classes; the pattern is about abstraction, not syntax.

Why it matters: Believing this limits flexibility and can lead to overcomplicated code when simple functions suffice.

Quick: Do you think repositories always improve performance? Commit to yes or no.

Common Belief: Some believe using repositories automatically makes data access faster.

Reality: Repositories organize code but do not inherently improve speed; optimization requires extra work like caching.

Why it matters: Expecting performance gains without optimization can cause disappointment and misuse.

Quick: Is it true that repositories hide all data source errors from the app? Commit to yes or no.

Common Belief: People often think repositories catch and hide all errors internally.

Reality: Repositories should handle errors gracefully but also propagate meaningful errors so the app can respond properly.

Why it matters: Hiding errors completely can make debugging and user feedback difficult.

Quick: Do you think the repository pattern is only useful for large apps? Commit to yes or no.

Common Belief: Some say repositories are unnecessary for small projects.

Reality: Even small apps benefit from repositories by keeping code clean and preparing for future growth.

Why it matters: Skipping repositories early can lead to messy code and harder scaling later.

Expert Zone

1

Repositories can implement different interfaces for testing, allowing seamless swapping between real and mock data sources.

2

The pattern supports multiple repository implementations for the same data type, enabling strategies like read-only or cached repositories.

3

Repositories can be combined with Unit of Work patterns to manage transactions across multiple data operations.

When NOT to use

Avoid using repositories when your app only fetches data from a single simple API without complex logic. In such cases, direct data fetching with hooks or services is simpler and more efficient.

Production Patterns

In production Next.js apps, repositories often wrap Prisma or MongoDB clients, handle API rate limits, and integrate with caching layers like Redis. They also separate read and write operations for scalability.

Connections

Service Layer Pattern

Builds on and complements the Repository pattern by adding business logic on top of data access.

Understanding repositories helps grasp how service layers organize app logic separately from data fetching.

Dependency Injection

Repositories often use dependency injection to receive database clients or APIs, improving modularity and testability.

Knowing dependency injection clarifies how repositories stay flexible and easy to test.

Supply Chain Management

Both manage flow and access to resources through intermediaries to simplify complex systems.

Seeing repositories like supply chain middlemen helps appreciate their role in organizing and controlling data flow.

Common Pitfalls

#1 Mixing business logic inside the repository.

Wrong approach:

async function getUser(id) { const user = await db.findUser(id); if (!user.isActive) throw new Error('Inactive'); return user; }

Correct approach:

async function getUser(id) { return await db.findUser(id); } // Business logic handled elsewhere

Root cause:

Confusing data access with business rules leads to hard-to-maintain code and breaks separation of concerns.

#2 Creating a new database connection inside every repository method.

Wrong approach:

async function getUser(id) { const client = new DbClient(); await client.connect(); return client.findUser(id); }

Correct approach:

const client = new DbClient(); await client.connect(); async function getUser(id) { return client.findUser(id); }

Root cause:

Not reusing connections causes performance issues and resource waste.

#3 Returning raw database response objects directly to the app.

Wrong approach:

async function getUser(id) { return await db.query('SELECT * FROM users WHERE id = ?', [id]); }

Correct approach:

async function getUser(id) { const result = await db.query('SELECT * FROM users WHERE id = ?', [id]); return { id: result[0].id, name: result[0].name }; }

Root cause:

Exposing raw data can leak implementation details and cause bugs if the app expects a different format.

Key Takeaways

The Repository pattern creates a clear boundary between your app and data sources, making code easier to maintain and evolve.

It hides complex data fetching details and provides simple methods your app can call without worrying about storage.

Repositories improve testability by allowing you to swap real data sources with mocks or stubs.

Advanced repositories can optimize performance with caching and batching without changing app code.

Using repositories correctly requires keeping business logic separate and managing resources efficiently.

Practice

1. What is the main purpose of using the Repository pattern in a Next.js application?

easy

A. To style components with CSS modules

B. To organize data access in one place for cleaner and reusable code

C. To handle routing between pages

D. To manage component state with hooks

Solution

1. Step 1: Understand the role of the Repository pattern

   The Repository pattern centralizes data access logic, separating it from UI code.

2. Step 2: Identify benefits in Next.js context

   This separation makes code cleaner, reusable, and easier to maintain.

3. Final Answer:

   To organize data access in one place for cleaner and reusable code -> Option B

4. Quick Check:

   Repository pattern = centralized data access [OK]

Hint: Repository pattern centralizes data access, not UI or styling [OK]

Common Mistakes:

• Confusing repository with UI state management
• Thinking repository handles routing
• Mixing repository with styling concerns

2. Which of the following is the correct way to define a simple repository class in Next.js using TypeScript?

easy

A. class UserRepository { async getAll() { return fetch('/api/users').then(res => res.json()) } }

B. function UserRepository() { return fetch('/api/users') }

C. const UserRepository = () => fetch('/api/users').json()

D. class UserRepository { getAll() { return fetch('/api/users').json() } }

Solution

1. Step 1: Check class syntax and async usage

   class UserRepository { async getAll() { return fetch('/api/users').then(res => res.json()) } } correctly defines a class with an async method returning parsed JSON from fetch.

2. Step 2: Identify errors in other options

   function UserRepository() { return fetch('/api/users') } is a function, not a class. const UserRepository = () => fetch('/api/users').json() incorrectly calls .json() directly on fetch result without awaiting. class UserRepository { getAll() { return fetch('/api/users').json() } } misses async and awaits, causing runtime error.

3. Final Answer:

   class UserRepository { async getAll() { return fetch('/api/users').then(res => res.json()) } } -> Option A

4. Quick Check:

   Async class method with fetch and json parsing = class UserRepository { async getAll() { return fetch('/api/users').then(res => res.json()) } } [OK]

Hint: Repository methods fetching data must be async and parse JSON [OK]

Common Mistakes:

• Forgetting async keyword on methods
• Calling .json() without awaiting fetch response
• Using function instead of class for repository

3. Given this repository method in Next.js, what will console.log(users) output?

class UserRepository {
  async getAll() {
    return [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
  }
}

const repo = new UserRepository()
const users = await repo.getAll()
console.log(users)

medium

A. [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]

B. Promise { <pending> }

C. undefined

D. Error: await is only valid in async function

Solution

1. Step 1: Analyze the getAll method

   getAll returns a resolved array of user objects immediately (no fetch or delay).

2. Step 2: Understand await usage

   Await unwraps the Promise returned by async getAll, so users is the array itself.

3. Final Answer:

   [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }] -> Option A

4. Quick Check:

   Await unwraps async return value = array [OK]

Hint: Await unwraps async method result to actual data [OK]

Common Mistakes:

• Thinking users is a Promise object
• Forgetting await causes Promise logged
• Assuming undefined without return

4. Identify the error in this Next.js repository code snippet:

class ProductRepository {
  getAll() {
    const response = fetch('/api/products')
    return response.json()
  }
}

medium

A. json() method does not exist on response

B. fetch URL is incorrect

C. Missing async keyword and await for fetch and json calls

D. Class name should be lowercase

Solution

1. Step 1: Check fetch usage

   fetch returns a Promise, so response is a Promise, not the actual response object.

2. Step 2: Identify missing async/await

   To get JSON data, method must be async and await fetch and response.json() calls.

3. Final Answer:

   Missing async keyword and await for fetch and json calls -> Option C

4. Quick Check:

   Async fetch requires await to get response data [OK]

Hint: Always use async/await with fetch and response.json() [OK]

Common Mistakes:

• Not marking method async
• Not awaiting fetch or json()
• Assuming fetch returns data synchronously

5. You want to create a repository in Next.js that fetches user data and caches it to avoid repeated API calls. Which approach correctly applies the repository pattern with caching?

hard

A. class UserRepository {
async getAll() {
return fetch('/api/users').then(res => res.json())
}
}

B. function getAllUsers() {
return fetch('/api/users').then(res => res.json())
}

C. const cache = []
async function getAllUsers() {
if (cache.length) return cache
const res = await fetch('/api/users')
cache.push(...await res.json())
return cache
}

D. class UserRepository {
cache = null
async getAll() {
if (this.cache) return this.cache
const res = await fetch('/api/users')
this.cache = await res.json()
return this.cache
}
}

Solution

1. Step 1: Understand caching in repository context

   Caching should be encapsulated inside the repository class to keep data access logic together.

2. Step 2: Evaluate options for caching implementation

   class UserRepository { cache = null async getAll() { if (this.cache) return this.cache const res = await fetch('/api/users') this.cache = await res.json() return this.cache } } uses a class property to store cache and returns it if available, avoiding repeated fetch calls.

3. Step 3: Compare other options

   Options A and B do not implement caching. const cache = [] async function getAllUsers() { if (cache.length) return cache const res = await fetch('/api/users') cache.push(...await res.json()) return cache } uses an external cache variable, breaking encapsulation.

4. Final Answer:

   class UserRepository { cache = null async getAll() { if (this.cache) return this.cache const res = await fetch('/api/users') this.cache = await res.json() return this.cache } } -> Option D

5. Quick Check:

   Repository with internal cache property = class UserRepository { cache = null async getAll() { if (this.cache) return this.cache const res = await fetch('/api/users') this.cache = await res.json() return this.cache } } [OK]

Hint: Cache inside repository class to keep data logic together [OK]

Common Mistakes:

• Caching outside repository breaks encapsulation
• Not checking cache before fetching
• Using functions instead of class for caching