DEV Community: YukiOnishi

Building a Production-Ready Next.js App Router Architecture: A Complete Playbook

YukiOnishi — Mon, 13 Oct 2025 14:21:27 +0000

The App Router gives us incredible primitives—Server Components, Server Actions, and explicit “use client” boundaries—but it doesn’t ship with a blueprint. After watching teams struggle with blurred layers and hydration chaos, I decided to publish the architecture we’ve battle-tested in production.

Repo: next-app-router-architecture
– System guide: docs/README.md
– Frontend playbook: frontend/docs/README.md
– Checklists: docs/checklists.md
– GitHub: github.com/YukiOnishi1129/next-app-router-architecture

The Product: Request & Approval System

Not a toy blog. A real app surface that stresses the App Router.

Persona	What they do
Requester	Draft requests, edit before submitting, track status, get notified on decisions.
Approver	See pending approvals, take action with comments, dig into history.
Everyone	Manage profile (name, email, password), change-email flow, reset password.

Under the hood: Google Identity Platform + NextAuth for auth, multi-role flows, notifications, audit-friendly DTO validation. Just enough scope to reveal real App Router problems—without drowning you.

Why App Router Needs a Playbook

Common pain points we kept hitting:

Blurred boundaries – server-only code (handlers, repositories) leaking into client components. Works in dev, blows up in prod.
Server Action sprawl – actions scattered inside random page.tsx, entangling features with routes.
Hydration regressions – a stray "use client" bubbles up; suddenly half the layout becomes client-rendered.

We wanted a blueprint that says: “put this here, never import that there, and here’s lint to enforce it.” So we wrote one.

Principle 1 — Layer with Intent

frontend/src/
├─ app/           # App Router: routes, layouts, metadata (thin)
├─ features/      # Domain bundles (auth, requests, approvals, settings)
├─ shared/        # Cross-cutting UI, layout chrome, providers, lib
└─ external/      # Server adapters (dto, handler, service, repository, client)

app/ stays thin

// frontend/src/app/requests/[requestId]/page.tsx
import { RequestDetailPageTemplate } from '@/features/requests/components/server/RequestDetailPageTemplate'
import type { PageProps } from '@/shared/types/next'

export default async function RequestDetailPage(
  props: PageProps<'/requests/[requestId]'>
) {
  const { requestId } = await props.params
  const searchParams = await props.searchParams
  const highlight =
    Array.isArray(searchParams.highlight) ? searchParams.highlight[0] : searchParams.highlight

  return (
    <RequestDetailPageTemplate
      requestId={requestId}
      highlightCommentId={highlight}
    />
  )
}

No data fetching inside the page. It forwards typed params to a feature template. That’s the rule everywhere.

features/ own orchestration

features/requests/
├─ components/
│  ├─ server/    # Server Components (page templates)
│  └─ client/    # Container / Presenter / Hook slices
├─ hooks/        # TanStack Query + client logic
├─ queries/      # Query keys + DTO helpers
├─ actions/      # Server Actions (thin wrappers)
└─ types/        # Shared types, enums

Client slices are deliberately small:

components/client/RequestList/
├─ RequestListContainer.tsx   # uses hook, passes props down
├─ RequestListPresenter.tsx   # pure JSX
├─ useRequestList.ts          # orchestrates Query + derived state
├─ RequestList.test.tsx       # co-located tests
└─ index.ts                   # barrel export

external/ is your escape hatch

external/
├─ dto/           # Zod schemas + TS types
├─ handler/       # Server entry points (command.server.ts / query.server.ts / *.action.ts)
├─ service/       # Domain services (business logic)
├─ repository/    # DB access (Drizzle or swap later)
└─ client/        # Outbound API clients

Because features never import repositories/services directly, swapping backends is painless: re-implement the service layer (e.g., point the repository to Go microservices instead of Drizzle) without touching React code. This pattern lets you move from “Next.js monolith” → “Next.js + Go backend” by rewiring services only.

Lint keeps us honest

Custom rules in frontend/eslint-local-rules:

restrict-service-imports — only handlers can import external/service/**.
restrict-action-imports — client components/hooks are the only consumers of *.action.ts.
use-nextjs-helpers — enforce PageProps/LayoutProps, next/navigation, etc.

They run in CI; architecture violations fail the build.

Principle 2 — Routes & Layouts Drive Experience

Route groups map to auth states:

(guest) — login, signup, email-change flows
(authenticated) — dashboard, requests, approvals, settings
(neutral) — password reset, terms

Layouts enforce access and render shared chrome.

// frontend/src/app/(authenticated)/layout.tsx
import { AuthenticatedLayoutWrapper } from '@/shared/components/layout/server/AuthenticatedLayoutWrapper'
import type { LayoutProps } from '@/shared/types/next'

export const dynamic = 'force-dynamic'

export default function AuthenticatedLayout(props: LayoutProps<'/'>) {
  return <AuthenticatedLayoutWrapper>{props.children}</AuthenticatedLayoutWrapper>
}

AuthenticatedLayoutWrapper handles:

requireAuthServer() check
Query hydration via HydrationBoundary
Rendering the sidebar + header

// frontend/src/app/(authenticated)/requests/layout.tsx
export const metadata = {
  title: 'Request List | Request & Approval System',
  description: 'Browse, filter, and search submitted requests.',
}

Checklist for adding a route (from docs/checklists.md):

Pick route group; create layout.tsx + page.tsx.
Use LayoutProps<'/path'>; export metadata from the layout.
In the page, await props.params / props.searchParams via PageProps.
Delegate to a feature template under components/server.
Add loading.tsx / error.tsx if the route does real work.
Run pnpm typegen to refresh typed routes.

Principle 3 — Server-First Data Fetching (with TanStack Query)

We lean hard on TanStack Query—server and client.

Server templates hydrate the cache

// features/requests/components/server/RequestsPageTemplate.tsx
import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
import { RequestList } from '@/features/requests/components/client/RequestList'
import { requestKeys } from '@/features/requests/queries/keys'
import {
  ensureRequestListResponse,
  selectRequestListFetcher,
} from '@/features/requests/queries/requestList.helpers'
import { getQueryClient } from '@/shared/lib/query-client'
import {
  listAllRequestsServer,
  listAssignedRequestsServer,
  listMyRequestsServer,
} from '@/external/handler/request/query.server'
import type { RequestFilterInput, RequestsStatusTabKey } from '@/features/requests/types'

export async function RequestsPageTemplate({
  filters = {},
  activeTabKey,
}: {
  filters?: RequestFilterInput
  activeTabKey: RequestsStatusTabKey
}) {
  const queryClient = getQueryClient()

  await queryClient.prefetchQuery({
    queryKey: requestKeys.list(filters),
    queryFn: async () => {
      const fetcher = selectRequestListFetcher(filters, {
        listMine: listMyRequestsServer,
        listAssigned: listAssignedRequestsServer,
        listAll: listAllRequestsServer,
      })
      const response = await fetcher()
      return ensureRequestListResponse(response)
    },
  })

  return (
    <section className="space-y-6 px-6 py-8">
      {/* header, tabs */}
      <HydrationBoundary state={dehydrate(queryClient)}>
        <RequestList filters={filters} />
      </HydrationBoundary>
    </section>
  )
}

Takeaways

Server prefetch chooses the right handler (mine/assigned/all).
ensureRequestListResponse validates DTOs before React.
HydrationBoundary hands a warm cache to the client.

Client hook consumes the same key

// features/requests/queries/useRequestListQuery.ts
'use client'

import { useQuery } from '@tanstack/react-query'
import { requestKeys } from '@/features/requests/queries/keys'
import {
  ensureRequestListResponse,
  selectRequestListFetcher,
} from '@/features/requests/queries/requestList.helpers'
import {
  listAllRequestsAction,
  listAssignedRequestsAction,
  listMyRequestsAction,
} from '@/external/handler/request/query.action'
import type { RequestFilterInput } from '@/features/requests/types'

export const useRequestListQuery = (filters: RequestFilterInput = {}) =>
  useQuery({
    queryKey: requestKeys.list(filters),
    queryFn: async () => {
      const fetcher = selectRequestListFetcher(filters, {
        listMine: listMyRequestsAction,
        listAssigned: listAssignedRequestsAction,
        listAll: listAllRequestsAction,
      })
      const response = await fetcher()
      return ensureRequestListResponse(response)
    },
  })

The container hook stays identical on first render and refetch, thanks to server hydration. No SSR/CSR divergence.

Container ➜ Hook ➜ Presenter

// features/requests/components/client/RequestList/RequestListContainer.tsx
'use client'

import { RequestListPresenter } from './RequestListPresenter'
import { useRequestList } from './useRequestList'
import type { RequestFilterInput } from '@/features/requests/types'

export function RequestListContainer({ filters }: { filters: RequestFilterInput }) {
  const { summaries, isLoading, isRefetching, errorMessage } = useRequestList({ filters })

  return (
    <RequestListPresenter
      requests={summaries}
      isLoading={isLoading}
      isRefetching={isRefetching}
      errorMessage={errorMessage}
    />
  )
}

The container memoizes filters, calls useRequestListQuery, maps DTOs to UI-friendly summaries. Presenters render what they’re given—nothing more.

When to skip hydration

Static server views (e.g., an overview header that does a Promise.all and renders summary stats) don’t need TanStack Query. If it’s static, keep it server-only.

Mutations invalidate precisely

// features/approvals/hooks/useApproveRequest.ts
return useMutation({
  mutationFn: async ({ requestId }) => {
    const result = await approveRequestAction({ requestId })
    if (!result.success) throw new Error(result.error ?? 'Failed to approve request')
    return { requestId }
  },
  onSuccess: async (_data, { requestId }) => {
    await Promise.all([
      queryClient.invalidateQueries({ queryKey: approvalKeys.pending() }),
      queryClient.invalidateQueries({ queryKey: requestKeys.detail(requestId) }),
      queryClient.invalidateQueries({ queryKey: requestKeys.all }),
      queryClient.invalidateQueries({ queryKey: requestKeys.history(requestId) }),
      queryClient.invalidateQueries({ queryKey: notificationKeys.list() }),
    ])
  },
})

Principle 4 — Quality Gates Codified

Custom ESLint rules (local)

frontend/eslint-local-rules houses architecture cops:

restrict-service-imports — prevent client code from touching external/service/**.
restrict-action-imports — ensure Server Actions are only consumed by clients/hooks.
use-nextjs-helpers — require PageProps/LayoutProps, next/navigation, and catch missing await props.params.
use-client-check, use-server-check — verify directive placement.

Run pnpm lint; violations fail fast.

DTO validation everywhere

// external/dto/request/ensureRequestListResponse.ts
import type { RequestListResponse, RequestListResult } from './types'

const DEFAULT_LIMIT = 20

export function ensureRequestListResponse(response: RequestListResponse): RequestListResult {
  if (!response.success || !response.requests) {
    throw new Error(response.error ?? 'Failed to load requests')
  }
  return {
    requests: response.requests,
    total: response.total ?? response.requests.length,
    limit: response.limit ?? DEFAULT_LIMIT,
    offset: response.offset ?? 0,
  }
}

If the backend changes shape, you know immediately.

Error boundaries per route group

Every major section has error.tsx and loading.tsx so failures surface gracefully, not as white screens.

Tests live next to subjects

Hooks, presenters, and server templates ship with co-located tests (*.test.ts(x)) using Vitest + React Testing Library. Open, run, change, repeat.

External layer = future-proof integration

Because the UI only speaks to handlers, migrating from “Next.js + Drizzle” to “Next.js + Go microservices” is flipping the implementation inside external/service/**. Features, hooks, and components stay untouched.

Lessons Learned & Scaling

Boundaries reduce mental load. When /app is routing-only, /features is orchestration, and /external is integration, PR reviews become trivial.
A warm TanStack Query cache keeps UX snappy. Server-first fetching + client hydration gives you SSR speed and CSR interactivity.
Custom lint beats tribal knowledge. Architecture decisions encoded as ESLint rules eliminate “you forgot to…” conversations.
The external adapter pattern buys growth options. Offload heavy domains to Go? Point the service layer there; React stays the same.

When should you adopt this playbook?

You’re shipping multi-role apps with significant server logic.
You rely on Server Actions and RSC but need strict separation.
You want to keep the door open for future backend refactors without touching React code.

Dive Deeper

Repo: github.com/YukiOnishi1129/next-app-router-architecture
System guide: docs/README.md
Frontend playbook: frontend/docs/README.md
Checklists: docs/checklists.md

Clone it, explore the slices, and try adding a new feature by following the checklist. Once you’ve felt the predictability, you won’t want to go back to ad-hoc App Router projects.

Appendix — .eslintrc.cjs (excerpt)

// frontend/.eslintrc.cjs
module.exports = {
  root: true,
  plugins: ['@typescript-eslint', 'react', 'react-hooks', 'eslint-plugin-local'],
  extends: ['next/core-web-vitals', 'plugin:@typescript-eslint/recommended'],
  rules: {
    'local/restrict-service-imports': 'error',
    'local/restrict-action-imports': 'error',
    'local/use-nextjs-helpers': 'error',
    'react-hooks/rules-of-hooks': 'error',
  },
  settings: {
    'import/resolver': {
      typescript: { project: './tsconfig.json' },
    },
  },
}

Appendix — Typed Next.js helpers

// shared/types/next.ts
import type { ReadonlyURLSearchParams } from 'next/navigation'

export type LayoutProps<_Path extends string> = {
  children: React.ReactNode
}

export type PageProps<_Path extends string> = {
  params: Promise<Record<string, string>>
  searchParams: Promise<ReadonlyURLSearchParams | Record<string, string | string[] | undefined>>
}

Appendix — Query client helper

// shared/lib/query-client.ts
import { QueryClient } from '@tanstack/react-query'

export function getQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: { staleTime: 30_000, refetchOnWindowFocus: false },
    },
  })
}

Benefits and Drawbacks of Adopting Clean Architecture

YukiOnishi — Sat, 19 Oct 2024 08:31:37 +0000

Clean Architecture is a design principle aimed at organizing dependencies within a system, promoting flexibility and maintainability in software development. Below are the key benefits and drawbacks of adopting Clean Architecture.

Benefits

1. Improved Maintainability

Clean Architecture separates business logic and domain-related code from infrastructure and frameworks, minimizing the impact of changes in requirements or technology. This makes the code easier to maintain over time.

2. Easier Testing

Since business logic is isolated from other parts of the system, unit tests can be written more easily. You can test the business logic without relying on infrastructure or UI components, making the test code simpler and faster to execute.

3. Increased Flexibility and Reusability

The architecture is divided into independent modules, making it easy to reuse specific components or features in other projects. Additionally, changing technology stacks (such as databases or frontend frameworks) can be done without affecting other layers of the system.

4. Independence from Technical Details

Clean Architecture uses interfaces and abstract classes to decouple business logic from technical details like databases, UI, or external APIs. This enables easier modification of underlying technologies without impacting the core logic.

5. Clear Structure

With distinct separation of responsibilities, Clean Architecture provides a clear structure, making it easier for new team members to understand the project and locate the necessary code.

Drawbacks

1. Increased Initial Development Cost

Adopting Clean Architecture requires significant upfront design work, including defining layers, interfaces, and separation of concerns. For small or short-term projects, this overhead may not be justified.

2. Increased Complexity

With multiple layers involved, the overall complexity of the project can increase. For small-scale applications, Clean Architecture might feel overly complex and lead to reduced development efficiency due to the increased back-and-forth between layers.

3. Steep Learning Curve

To implement Clean Architecture effectively, developers need to have a good understanding of concepts like abstraction and dependency inversion. This requires a certain level of experience and familiarity with architectural design patterns.

4. Risk of Over-Engineering

For small projects or simple systems, applying Clean Architecture strictly may lead to over-engineering. Adding too much abstraction or unnecessary layers could slow down development and make maintenance more complicated.

5. Potential Performance Overhead

Using multiple layers and interfaces can introduce some performance overhead. While this is usually negligible, in real-time systems or performance-critical applications, this could be a concern and should be carefully evaluated.

Conclusion

Clean Architecture is particularly effective for large-scale systems where long-term maintainability and extensibility are important. However, for smaller or short-term projects, it may introduce unnecessary complexity and cost. It's essential to carefully assess whether adopting Clean Architecture is appropriate for the specific context of your project. When used correctly, it can be a very powerful architectural approach.

How to study React to become a pro. Introduction to React.

YukiOnishi — Mon, 10 Jun 2024 02:56:34 +0000

React has by far the largest market share among JavaScript frameworks!

However, it is a framework with a high failure rate, so I would like to introduce a roadmap for learning React from my knowledge as an active front-end engineer!

Understanding React overview

First of all, what can React do? And what features does it have to make it work? Let's learn about the following!

The best framework for building SPA

One of the biggest advantages of JavaScript frameworks such as React is the ability to efficiently build single page application (SPA)!

Simply put, SPA is a technology that 'allows screen transitions to be carried out without waiting for a server response'. This feature allows for quick screen transitions.

The mechanism that makes this SPA possible is actually achieved by "making it look like a screen transition is taking place by replacing the part below the body tag in the HTML"!

With React, each time the screen URL changes, only the display part of the HTML is replaced.

So how does it change parts of the HTML?

To find out, you first need to understand something called 'components'.

The concept of 'components'

React allows HTML to be described in JavaScript, and parts can be created in units of screen components, such as buttons, headers and footers.

These component parts are called 'components', and screens are built by combining components.

Screen transitions in SPA are achieved by replacing these components.

This method of describing HTML in JavaScript is called 'jsx', and React uses this method to create component files.

In this case, the side to be introduced is called the parent component and the side to be introduced is called the child component.

Furthermore, components are created as JavaScript files, so they are introduced by importing the child component's js file into the parent component's js file.

At this point, the JavaScript function "ECMA module" is used, so make sure you have a good review of it!

Change only the parts of the data that have been updated (about the virtual DOM)

One of the advantages of using React is that "only the parts affected by the updated data are changed".

In the case of web services that do not use React, even if only a part of the data is changed, synchronous communication is used and the entire screen has to be redrawn, which is not easy to operate. (Asynchronous communication is also possible using ajax, but this tends to result in complex and poorly maintainable code.)

With React, it is possible to "redraw only the parts of the screen related to the updated data".

Therefore, this can be achieved with simple code and without redrawing via synchronous communication.

This can be achieved by differential rendering using the Virtual DOM.

The concept of the virtual DOM is a little difficult to grasp, so we would like you to have an image of it as "having screen data before and after changes, and having a function that detects the differences and updates only the changed parts".

Components have states (State and Props)

We have seen that changes to the screen UI are efficiently implemented by the virtual DOM.

So how can we determine the sign that the UI has changed?

Actually, each component can have its own data (state), and the change in state is used to determine that the UI has changed. (In React, a state is called a 'State'.)

You can define states for components using functions such as 'useState' in React Hooks.

Components can also be nested, so you can pass states defined in a parent component to a child component.

This functionality is called 'Props', and in React, States and Props are the foundation of state management, so it is necessary to have a good understanding of them.

State management is fundamental in React!

React provides a comfortable UI through state management using States and Props.

In addition to Props, there is also a function called 'Context API' for passing state within components.

There is also a function called "Redux" that enables this, as there are situations where you may want to use a common state for components that are not in a parent-child relationship. (Functions that manage state outside of components, such as Redux, are sometimes referred to as 'global state' or 'store'.)

Thus, state management is very important in React!

Since React does things in invisible areas such as the virtual DOM, it is difficult to get an image of how the state changes and the UI is actually changed behind the scenes.

Therefore, it is important to first implement an application that changes the UI by state management using only JavaScript, and understand how the UI changes based on the flow of data.

If you have never created a todo list in JavaScript, please try implementing it before learning React!

Conclusion

There are four key aspects to learning React.

The best framework for building SPA
Components
Virtual DOM
State Management

【Reducing costs】Automatically remove old docker container image using Artifact Registry cleanup policies

YukiOnishi — Sat, 01 Jun 2024 17:39:18 +0000

When dealing with docker container images in Google Cloud, Artifact Registry is used as a storage location for them.
However, as you store container images, more and more old images will remain, and you will eventually reach the capacity beyond the free quota.
This costs you more and more money.

However, Google cloud has 'cleanup policies' that automatically deletes old container images.

This article summarises how to use that cleanup policies to automatically remove old container images.

What is Artifact Registry?

Artifact Registry is a Google Cloud service that can complement and manage docker container images. You can operate and execute applications by linking the images stored here to CloudRun or CloudRun Jobs.

By integrating with services such as Cloud Build, it is also possible to automatically store container images and set up automatic deployment to services like Cloud Run.

There is also a similar service called Container Registry, but this one is deprecated and it is recommended to use Artifact Registry.

Further information.

So, Artifact Registry is required when dealing with container images in Google Cloud.

Artifact Registry pricing

As for the pricing that you may be concerned about, the configurations are categorized into the following three types.

Storage
Data transfer
Vulnerability scanning

Data transfer is free f charge within the same location.

Storage is what my be charged for here.
Up to 0.5GB of capacity is free, but beyond that it costs about $0.10 per month in 1GB increments.

Further information.

In my case, I use three kind of container images, a image's capacity is 11MB. So, all of my container image's capacity is 30~50MB. It is not over 0.5GB within free.

In my case, I run about three container images, which are about 11MB each, so all together are about 30~50MB. I never exceed the free quota of 0.5MB.

However, if Artifact Registry is not specifically configured, the old container image will remain after each reflection of the latest container image.

As these unused images accumulate, they exceed 0.5GB by leeway.

So old container images need to be deleted, but I would like to be automatic.

It is the cleanup policies that can do this.

What's cleanup policies?

Cleanup policy is a function that automatically deletes container images, etc, stored in the Artifact Registry based on pre-defined content.

Further information.

delete policy and conditional keep policy

The cleanup policy is designed to set two types.

delete policy
conditional keep policy

As the name suggests, these set the conditions for deleting and retaining images respectively.

It is important to note that if only a "condition keep policy" is set, nothing is deleted. Container images will not be performed unless a "delete policy" is set.

So, for example, "You want to saved latest two container image, delete others"

So, for example, if you want to "keep the two most recent container images and delete everything else", the setting must be set up as follows.

delete policy: Remove images with or without tags.
condition keep policy: Only the two most recent versions are retained.

I write after about especially methods.

Specific settings are described below.

Constraints

Cleanup policies have the following restrictions.

Deletions and retentions triggered by the clean-up policy are performed once per day (it is not known at what point in time they are performed).
Deletions triggered by delete policies are up to 30,000 per repository, per day
Up to 10 clean-up policies per repository

It is important to note that the clean-up policy is only executed once a day.

It is also not clear at what time of the day it is executed, so depending on the timing, container images may not be removed.

If you have automated CloudBuild or Github Actions to reflect the main repository in the ArtifactRegistry every time it is updated, and you reflect it many times a day, in some cases the container image may remain undeleted.

The policy will be executed again the next day and the image will be deleted, but be aware that if the storage capacity is squeezed while it is not deleted, the billing amount may increase.

How to set up automatically deletion

Condition of automatically deletion

In this case, the container image is set to be automatically deleted with the following content.

Only the two most recent container images are retained, all other images are deleted.

Therefore, set up a "delete policy" and "keep condition policy" with the following details.

delete policy: remove images with or without tags.
condition keep policy: only the two most recent versions are retained.

How to set up

Go to Google Cloud and navigate to the Artifact Registry page.
A list of repositories will appear, select the target repository.

Click on "EDIT REPOSITORY"

Scroll to below, select "Cleanup policies" and "Delete artifacts".

From here, set up "delete policy" and "keep condition".

Click on "ADD A CLEANUP POLICY".

First, set "delete policy".

Fill in "name" and select "Conditional delete".

Leave the "Tag state" as "Any tag state".

Finally, click on "DONE" in the bottom right-hand corner.

Second, "condition keep policy".

Click on "ADD A CLEANUP POLICY" again to create a new policy.

Fill in "name" and select "Keep most recent versions" as the policy types.

"Keep points" should be "2".

Finally, click on "DONE" in the bottom right-hand corner.

Finally, click on the "Update" button at the bottom and you are done.

The timing of when the policy is executed is random, but after some time only the two latest versions of the images in the repository will be available.

Summary.

"Cleanup policies" can now be set to automatically remove old container images.

If you use Artifact Registry, set this to avoid unnecessary charges.