DEV Community: Nana Okamoto

Why BFF Architecture Makes More Sense in the Age of AI-Assisted Development

Nana Okamoto — Fri, 07 Aug 2026 23:57:51 +0000

AI coding tools are getting better at generating code.

But as AI writes more of our application code, a different problem becomes increasingly important:

How much of the system does the AI need to understand before it can safely make a change?

This is where architecture starts to matter.

A Backend for Frontend (BFF) is usually introduced as a way to create APIs optimized for a specific frontend. But in AI-assisted development, it offers another interesting advantage:

A BFF creates a clear boundary where frontend requirements can be translated into explicit, testable API contracts.

That boundary can reduce the amount of context an AI coding agent needs, make generated changes easier to review, and limit the blast radius of mistakes.

In this article, I’ll explain why BFF architecture can become especially useful when AI is part of the development workflow.

What Is a Backend for Frontend?

A Backend for Frontend is a backend layer designed specifically for the needs of a particular user interface.

Instead of this:

Frontend
   ↓
Multiple backend services
   ↓
Databases / external APIs

you introduce a frontend-oriented layer:

Frontend
   ↓
BFF
   ↓
Backend modules / services
   ↓
Databases / external APIs

The BFF can handle responsibilities such as:

aggregating multiple APIs
transforming backend data into frontend-friendly responses
authentication and authorization integration
pagination
error normalization
hiding internal service structure
defining frontend-specific API contracts

The key idea is not simply "add another API."

The important part is ownership and boundaries.

The frontend communicates with an API designed around its own use cases rather than depending directly on the structure of internal systems.

Why Does This Matter for AI-Assisted Development?

AI coding agents work best when the task has clear boundaries.

For example, compare these two instructions.

Without a clear architecture

Add the user's subscription status to the dashboard.

The AI may need to discover:

where subscription data lives
which service owns it
how authentication works
whether the frontend can access the service directly
how responses are transformed
which fields are safe to expose
what happens when the service is unavailable
whether multiple frontend components already implement similar logic

The implementation space becomes very large.

Now consider the same feature with a BFF.

Dashboard
   ↓
GET /api/dashboard
   ↓
BFF
   ↓
User / Subscription modules

The task becomes much more constrained:

Add subscriptionStatus to the dashboard response.

Now the AI can focus on a much smaller path:

Subscription Service
        ↓
       BFF
        ↓
DashboardResponse
        ↓
Frontend

This is a much better environment for both humans and AI.

1. BFF Reduces the Context AI Needs to Understand

One of the hidden costs of AI-generated code is context size.

The larger the architectural surface an AI needs to understand, the more opportunities there are for incorrect assumptions.

Consider a frontend that directly consumes several services:

React / Next.js
├── User API
├── Billing API
├── CMS API
├── Search API
└── Recommendation API

A developer changing one page may need to understand all five integrations.

An AI agent faces the same problem.

With a BFF:

React / Next.js
        ↓
       BFF
        ↓
 ┌──────┼──────┐
User  Billing  CMS

the frontend only needs to understand one interface.

This creates what I think of as an AI-friendly context boundary.

The AI working on the frontend does not necessarily need to understand every downstream system.

It needs to understand the BFF contract.

That is a much smaller problem.

2. API Contracts Give AI an Explicit Source of Truth

AI-generated implementations become easier to constrain and verify when APIs are defined through machine-readable contracts.

For example:

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  subscriptionStatus: z.enum([
    "free",
    "pro",
    "enterprise",
  ]),
})

Or an OpenAPI schema:

User:
  type: object
  required:
    - id
    - name
    - subscriptionStatus
  properties:
    id:
      type: string
    name:
      type: string
    subscriptionStatus:
      type: string
      enum:
        - free
        - pro
        - enterprise

Now both developers and AI agents have an explicit definition of:

What data exists
What type it has
What values are valid
What the frontend can depend on

Without a contract, AI often has to infer these things from implementation details.

Inference is exactly where mistakes begin.

3. BFF Prevents Backend Structure From Leaking Into the UI

Suppose the frontend needs this:

type Dashboard = {
  userName: string
  plan: string
  unreadNotifications: number
}

But the data comes from three different systems:

Identity Service
Billing Service
Notification Service

Without a BFF, the frontend may end up knowing all of this.

const user = await getUser()
const billing = await getSubscription()
const notifications = await getNotifications()

return {
  userName: user.profile.display_name,
  plan: billing.subscription.product.plan_name,
  unreadNotifications: notifications.metadata.unread_count,
}

This creates coupling between the UI and backend implementation details.

A BFF can instead expose:

GET /api/dashboard

{
  "userName": "Nana",
  "plan": "pro",
  "unreadNotifications": 3
}

The frontend now depends on a product-level contract, not the internal structure of three services.

This distinction becomes even more useful when AI is modifying the codebase.

An AI agent can change the dashboard without needing to reason about the entire service topology.

4. BFF Gives AI a Safer Place for Data Aggregation

Modern interfaces frequently need data from several sources.

For example:

Product Page
├── Product Service
├── Inventory Service
├── Review Service
└── Recommendation Service

You could perform this orchestration inside the frontend.

But then UI code starts accumulating infrastructure concerns.

const [
  product,
  inventory,
  reviews,
  recommendations
] = await Promise.all([
  getProduct(id),
  getInventory(id),
  getReviews(id),
  getRecommendations(id),
])

Soon you also need:

retry policies
timeout handling
authentication
fallback behavior
response transformations
partial failure handling

That logic becomes difficult for both developers and AI to reason about.

A BFF provides a natural place for this orchestration.

app.get("/products/:id", async (c) => {
  const id = c.req.param("id")

  const [product, inventory, reviews] =
    await Promise.all([
      productService.get(id),
      inventoryService.get(id),
      reviewService.get(id),
    ])

  return c.json({
    id: product.id,
    name: product.name,
    available: inventory.quantity > 0,
    rating: reviews.average,
  })
})

The frontend receives exactly what it needs.

const product = await api.products.get(id)

That smaller interface is easier to generate, test, review, and maintain.

Aggregation is only one use case, though.

A BFF can also be valuable when the application is not built from multiple microservices. Even in a modular monolith, it can provide a stable boundary between the frontend and domain or data-access layers.

For AI-assisted development, that boundary matters because the agent does not need to understand how every repository, database table, or external integration works. It only needs to work against the contract exposed by the BFF.

5. BFF Can Reduce the Blast Radius of AI-Generated Changes

AI makes development faster.

It can also make developers comfortable changing more code at once.

That makes architectural boundaries increasingly valuable.

Imagine an AI agent needs to modify how customer data is displayed.

Without a clear boundary:

Frontend
   ↓
Customer Service
   ↓
Shared database models

A generated change might accidentally depend on internal fields or introduce coupling with another service.

With a BFF:

Frontend
   ↓
CustomerResponse
   ↓
BFF
   ↓
Customer Service

the contract acts as a boundary.

Changes can be evaluated at each step.

Did the downstream API change?
        ↓
Does the BFF still satisfy its contract?
        ↓
Does the frontend still satisfy its tests?

This makes automated verification much easier.

6. BFF Works Well With Contract Tests and Generated Tests

One of the best ways to use AI safely is not simply:

Generate more code.

It is:

Generate code inside a system that can automatically tell us when the code is wrong.

BFF architecture also provides a natural place to introduce automated verification because the interface between the frontend and backend is explicit.

For example, a team can gradually build guardrails around that boundary:

OpenAPI / Zod Schema
        ↓
      BFF
        ↓
Schema / Contract Validation
        ↓
Frontend Types
        ↓
Integration Tests

These checks do not need to be introduced all at once.

Even starting with schema validation and type checking gives AI-generated changes a clearer definition of what is considered valid. Contract and integration tests can then strengthen that boundary over time.

7. BFF Creates Better Tasks for Coding Agents

Consider giving an AI coding agent this task:

Add a recommended schools section to the homepage.

If the system has no clear boundaries, the AI first needs to explore the repository and determine:

Where does school data come from?
Where are recommendations calculated?
Can the frontend access the database?
Does authentication matter?
What fields should be exposed?
Is there already an API?
Where should caching happen?

A well-structured system allows the task to be expressed much more precisely:

Implement:
GET /api/home/recommended-schools

Response:
{
  schools: SchoolSummary[]
}

Requirements:
- maximum 6 schools
- only active schools
- sort by recommendation score
- cache for 10 minutes

This is exactly the type of task AI agents handle well.

Architecture turns vague requirements into bounded implementation problems.

8. Frontend and AI Can Share the Same Contract

Another advantage appears when TypeScript is used across the stack.

For example:

apps/
  web/

services/
  bff/

packages/
  api-contract/

The shared contract might contain:

export const SchoolSummarySchema = z.object({
  id: z.string(),
  name: z.string(),
  city: z.string(),
  thumbnailUrl: z.string().url(),
})

export type SchoolSummary =
  z.infer<typeof SchoolSummarySchema>

Now:

Backend implementation
        ↓
Shared contract
        ↑
Frontend implementation

Both human developers and AI agents can inspect the same source of truth.

This eliminates an entire category of ambiguity.

Instead of asking:

What does this endpoint return?

the answer exists in code.

BFF Is Not Automatically "AI Architecture"

There is an important caveat.

Adding a BFF does not automatically make a system AI-friendly.

A bad BFF can easily become another monolith.

For example:

BFF
├── authentication
├── billing rules
├── recommendation engine
├── analytics logic
├── email sending
├── database access
├── admin workflows
├── batch processing
└── everything else

At that point, you have simply created another backend.

A BFF should primarily translate between:

What the UI needs
        ↕
What backend systems provide

It should not become the default location for every piece of business logic.

When BFF Might Be Overkill

A BFF is not necessary for every application.

Consider skipping it when:

your application has a single simple API
the frontend already receives exactly the data it needs
there is little server-side aggregation
introducing another service adds more operational complexity than value
your existing GraphQL architecture already provides an effective frontend-specific abstraction

The goal is not:

Every AI-powered development team needs a BFF.

The better principle is:

AI benefits from explicit architectural boundaries, and BFF is one practical way to create one between the UI and backend systems.

The Bigger Idea: Optimize Architecture for Change

For years, architecture discussions have focused on things like:

scalability
performance
reliability
team ownership
deployment independence

AI adds another dimension:

How easily can an agent understand and safely modify this system?

That does not mean designing applications specifically for LLMs.

It means that characteristics we already considered good engineering practices become even more valuable:

Clear boundaries
Explicit contracts
Small interfaces
Automated verification
Predictable ownership
Limited blast radius

A BFF happens to reinforce many of these characteristics.

Final Thoughts

The biggest advantage of a BFF in AI-assisted development is not API aggregation.

It is context control.

A good BFF gives both developers and AI agents a clear answer to three important questions:

What does the frontend need?
What contract guarantees it?
Where should the transformation happen?

When those answers are explicit, AI-generated code becomes easier to produce, easier to verify, and easier to review.

As coding agents become responsible for larger changes, I think this type of architectural clarity will matter more — not less.

AI can generate code quickly. Good architecture decides how much of the system it needs to understand before doing so.

And that may become one of the most important reasons to care about architectural boundaries in the AI era.

FAQ

Is BFF architecture useful for AI coding agents?

Yes, particularly in applications with multiple backend services or external data sources. A BFF can give coding agents a smaller, explicit API surface instead of requiring them to understand every downstream system.

Does BFF make AI-generated code safer?

Not by itself. However, combining a BFF with typed API contracts, schema validation, contract tests, and automated integration tests can significantly reduce ambiguity and make generated changes easier to verify.

Should every Next.js application use a BFF?

No. For simple applications, introducing another layer may create unnecessary complexity. BFF becomes more valuable when the frontend needs data aggregation, frontend-specific transformations, independent API evolution, or isolation from multiple downstream systems.

What makes a BFF AI-friendly?

The most important characteristics are:

small and explicit API contracts
schema validation
predictable ownership
limited responsibilities
generated or shared types
automated tests
clear separation from core business logic

8 Accessibility Issues We Found During a Next.js Audit

Nana Okamoto — Mon, 15 Jun 2026 18:56:39 +0000

Accessibility is often discussed as a checklist of WCAG requirements, but in real projects, the challenge is identifying issues that affect actual users and integrating fixes into an existing codebase.

Recently, I conducted an accessibility audit for a Next.js application and worked through a number of issues across multiple pages and reusable components. In this article, I'd like to share some of the most common problems we found and how we addressed them.

Why We Conducted an Accessibility Audit

Our goal was to improve the experience for keyboard users, screen reader users, and anyone who relies on assistive technologies.

To evaluate the application, we used:

Lighthouse
axe DevTools
Manual keyboard testing
Screen reader testing

While automated tools were useful, many of the most impactful issues were discovered through manual testing.

1. Incorrect Heading Structure

Problem
Some pages skipped heading levels.

<h1>Property Listings</h1>
<h3>Featured Properties</h3>

This can make page navigation difficult for screen reader users.

Solution

<h1>Property Listings</h1>
<h2>Featured Properties</h2>

Maintaining a logical heading hierarchy improves page structure and navigation.

2. Icon-Only Buttons Without Accessible Names

Problem
Some buttons relied entirely on icons.

<button>
  <SearchIcon />
</button>

Screen readers announced these as simply "button."

Solution
We added accessible labels.

<button aria-label="Search">
  <SearchIcon />
</button>

Now screen reader users understand the purpose of the control.

3. Duplicate Alternative Text

Problem
In several cards, an image and adjacent text conveyed the same information.

<img alt="English Bay Beach" />
<h2>English Bay Beach</h2>

The screen reader would announce the location name twice.

Solution
When the image was decorative or redundant, we used an empty alt attribute.

<img alt="" />

This reduced unnecessary repetition.

4. Generic "Read More" Links

Problem
Many article cards used generic link text such as:

<a href="/article/123">Read More</a>

While visually understandable, screen reader users often navigate using a list of links. Hearing multiple "Read More" links provides little context about their destination.

Solution
We preserved the existing design and added screen-reader-only text:

<a href={href}>
  Read More
  <span className="sr-only">
    about Canadian study permits
  </span>
</a>

Now screen readers announce a more descriptive link while the visual UI remains unchanged.

5. Missing Skip Navigation Link

Problem
Keyboard users had to tab through the entire header navigation on every page before reaching the main content.

Solution
We introduced a skip link.

<a href="#main-content" class="skip-link">
  Skip to main content
</a>

This allows keyboard users to jump directly to the primary content.

6. Missing Language Information

Problem
Our application supported multiple languages, but some content contained text in a different language without specifying its language.

<p>English</p>

When viewed on the Japanese version of the site, screen readers pronounced the word using Japanese pronunciation rules, making it difficult to understand.

We also found addresses and slogans written in English within otherwise Japanese pages.

Solution
We added the lang attribute to text that differed from the page's primary language.

<p lang="en">English</p>

This allows screen readers to switch pronunciation rules automatically and improves comprehension for multilingual users.

7. Focus Management After SPA Navigation

Problem
Because the application used client-side routing, page transitions did not always provide a clear indication that the content had changed.
Keyboard and screen reader users could lose track of their current position.

Solution
After navigation, focus was moved to the page heading.

<h1 tabIndex={-1}>Property Listings</h1>

The heading becomes focusable and can receive focus after route changes.
This is one of the most commonly overlooked accessibility issues in modern React applications.

8. Hover-Only Content

Problem
Additional information was displayed only on mouse hover.

<Tooltip>
  More information
</Tooltip>

Keyboard and touch users could not access the content.

Solution
We ensured that the content became visible when the trigger element received keyboard focus, not just on hover.
This allowed keyboard users to access the same information as mouse users.

Lessons Learned

One of the biggest takeaways from this audit was that accessibility issues are rarely isolated.

A missing heading, unclear link text, or improper focus management may seem minor individually, but together they can significantly impact the user experience.

Perhaps the most surprising finding was that several issues were invisible to automated tools and only became apparent during keyboard and screen reader testing.

Another important lesson was that automated tools only catch part of the problem. Keyboard navigation and screen reader testing revealed issues that Lighthouse and axe could not identify on their own.

Accessibility is not just about compliance. It improves usability, structure, and overall product quality for everyone.

Final Thoughts

If you're working on a Next.js or React application, I recommend starting with a small audit of a few critical user flows.

Focus on:

Headings
Keyboard navigation
Link text
Form labels
Focus management
Modal behavior

You may be surprised by how many issues can be discovered in just a few hours.

How I Introduce Frontend Testing in Early-Stage Next.js Projects

Nana Okamoto — Tue, 19 May 2026 18:15:04 +0000

Recently, I introduced testing into a new Next.js project.
One question always comes up at the beginning:

How much testing should we add?

Too much testing slows down development.
Too little testing eventually creates regressions.

For this project, we wanted something practical:

reasonable confidence without slowing down shipping.

This is the approach we ended up taking.

We Started With the Testing Trophy

For this project, we adopted the Testing Trophy approach.

Compared to the traditional Testing Pyramid, Testing Trophy emphasizes:
more integration tests and less E2E.

This felt much closer to how modern React applications — especially in a Next.js environment — tend to fail.

In many cases, frontend bugs don't happen in isolated functions.
They happen when:

UI
+ state
+ user interaction

come together.

Especially in React / Next.js applications, where components, state, rendering, and interaction are tightly coupled.

For an early-stage product, we wanted to balance:

confidence
vs
maintenance cost

So we decided to prioritize:

Unit Test
+ Integration Test
+ Accessibility Test

while intentionally postponing E2E.

What We Chose

Our testing stack looks like this:

Type	Tool	Purpose
Unit Test	Vitest	Pure logic
Integration Test	React Testing Library + Vitest	UI behavior
Accessibility Test	Playwright + axe-core	Accessibility validation

We intentionally skipped E2E tests for now.

Why?

Because in early-stage projects:

UI changes quickly
Requirements change often
Maintenance costs grow fast

At this stage, the cost simply felt higher than the benefit.

We'll likely introduce E2E later:

Authentication
Payment flow
Business-critical features

But not yet.

Directory Structure Matters Too

One thing that helped us keep testing practical was our directory structure.

We intentionally separate:

shared modules
vs
feature-specific modules

at the directory level.

Example:

src/
├── shared/
│   ├── components/
│   ├── hooks/
│   └── utils/
│
└── features/
    ├── auth/
    └── search/

The rule is simple:

We prioritize testing shared modules.

Because shared modules are reused across the application, regressions there tend to have wider impact.

This naturally helps keep the testing scope intentionally small.

Without a clear rule, frontend teams often end up testing too much.

For example, when components are organized purely by UI granularity (such as Atomic Design), it can become difficult to decide:

What actually deserves a dedicated test?

By separating modules based on responsibility and reuse, test decisions become much clearer.

Of course, exceptions still exist.

Even if something is not shared, we may still test it when:

logic is complex
business impact is high
regression risk is high

In our current project, we didn't have many cases where this felt necessary.

Another benefit was team alignment.

Since our team previously didn't have a strong frontend testing culture, having explicit rules made it much easier to share:

what should be tested — and what shouldn't

CI Setup

We kept CI intentionally simple:

typecheck
lint
test
accessibility test
build

The goal isn't perfect coverage.
It's to:

catch meaningful regressions early

while keeping development fast.

Final Thoughts

I don't think early-stage Next.js projects need massive testing setups.
But I also don't think:

"We'll add tests later"

works very well.

For us, the sweet spot was:

Unit Test
+ Integration Test
+ Accessibility Test

inspired by the Testing Trophy approach.

Simple enough to maintain.

Practical enough to prevent regressions.

How are you approaching testing in early-stage frontend projects?

Practical Technical SEO in Next.js: The Implementation Guide

Nana Okamoto — Sat, 18 Apr 2026 12:59:20 +0000

Modern SEO in Next.js (App Router) is not about adding meta tags.

It’s about controlling what HTML is delivered to crawlers, how it’s generated, and which pages are eligible for indexing.

This guide focuses on practical implementation patterns + why they matter.

1. Rendering Strategy Comes First

Why this matters

Rendering strategy determines:

Whether your content is visible in initial HTML
How fast your page loads (Core Web Vitals)
Whether Google treats your page as reliable

👉 In other words, this is the foundation of SEO in Next.js

Recommended strategies

Page Type	Strategy	Why
Blog / Marketing	SSG (`force-cache`)	Fast + fully indexable
Large sites	ISR	Scalable with good freshness
Personalized	SSR (`no-store`)	Needed for dynamic content
Dashboard	CSR	Not meant for indexing

Example

export default async function Page({ params }) {
  const post = await fetch(
    `https://api.example.com/posts/${params.slug}`,
    { cache: 'force-cache' }
  ).then(res => res.json())

  return <h1>{post.title}</h1>
}

👉 Wrong choice here = everything else won’t fix SEO

2. Ensure Content Exists in Initial HTML

Why this matters

Search engines primarily index server-rendered HTML.
If your content depends on client-side JavaScript:

Crawlers may not execute it fully
Indexing becomes delayed or incomplete

👉 This leads to missing or weak rankings

❌ Avoid

'use client'

useEffect(() => {
  fetch('/api/data')
}, [])

✅ Prefer

export default async function Page() {
  const data = await fetch('https://api.example.com').then(res => res.json())

  return <div>{data.title}</div>
}

Verification

curl -s https://example.com | grep "<h1>"

👉 If it’s not in HTML, it’s not reliably indexable

3. Metadata API: Full Implementation

Why this matters

Metadata controls how your page:

Appears in search results (title/description)
Avoids duplication (canonical)
Looks when shared (Open Graph)

👉 It directly impacts CTR (click-through rate) and index quality

Implementation

export async function generateMetadata({ params }) {
  const post = await getPost(params.slug)

  return {
    title: post.title,
    description: post.excerpt,

    alternates: {
      canonical: `https://example.com/blog/${post.slug}`,
    },

    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [post.image],
      type: 'article',
    },

    twitter: {
      card: 'summary_large_image',
    },
  }
}

Key rules

Always define a canonical URL
Keep metadata consistent with page content
Use dynamic metadata for dynamic routes

4. Indexing Control (robots + metadata)

Why this matters

Search engines don’t decide what should be indexed—you do.

Without proper control:

Staging environments can get indexed
Duplicate pages can appear
Sensitive routes may leak

👉 This can damage your SEO trust and rankings

robots.ts

export default function robots() {
  return {
    rules: {
      userAgent: '*',
      allow: '/',
      disallow: ['/admin'],
    },
    sitemap: 'https://example.com/sitemap.xml',
  }
}

Page-level control

const isProd = process.env.NEXT_PUBLIC_SITE_URL === 'https://example.com'

export const metadata = {
  robots: {
    index: isProd,
    follow: isProd,
  },
}

👉 Always base this on domain, not environment

5. Sitemap Generation

Why this matters

A sitemap is a signal of intent:

“These are the URLs I want indexed.”

If incorrect:

Crawlers waste time on irrelevant pages
Important pages may be ignored
Indexing becomes inconsistent

Implementation

export default async function sitemap() {
  const posts = await getPosts()

  return posts
    .filter(post => post.published)
    .map(post => ({
      url: `https://example.com/blog/${post.slug}`,
      lastModified: post.updatedAt,
    }))
}

Rules

Include only indexable pages
Match canonical URLs
Keep it clean (no duplicates)

6. Structured Data (JSON-LD)

Why this matters

Structured data helps search engines:

Understand your content better
Display rich results (e.g., article previews)

👉 This improves visibility and CTR, even if it’s not a direct ranking factor

Implementation

const jsonLd = {
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  headline: post.title,
  image: post.image,
  datePublished: post.date,
  dateModified: post.updatedAt,
  author: {
    "@type": "Person",
    name: post.author,
  },
}

7. Performance: Optimize LCP

Why this matters

Core Web Vitals are ranking signals.

LCP (Largest Contentful Paint) = how fast main content appears
Slow LCP = worse rankings

👉 SEO is not just content—it’s performance

Example

<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  priority
  sizes="100vw"
/>

Additional tips

Keep above-the-fold content server-rendered
Avoid blocking scripts
Don’t delay main content with streaming

8. URL and Canonical Consistency

Why this matters

Search engines treat different URLs as different pages—even if content is identical.

Without consistency:

Duplicate content issues
Split ranking signals
Lower SEO performance

Ensure alignment across:

canonical
sitemap URLs
internal links

9. Scaling Dynamic Routes (ISR)

Why this matters

Large sites can’t statically generate everything.

ISR allows you to:

Keep pages fast
Update content incrementally

👉 This balances performance and freshness

Example

export const revalidate = 60

Static params

export async function generateStaticParams() {
  const posts = await getPosts()

  return posts.map(post => ({
    slug: post.slug,
  }))
}

10. Verification Checklist

Why this matters

You can’t trust what you see in the browser—JavaScript modifies it.

👉 SEO depends on raw server response

Check HTML

curl -i https://example.com/page

Confirm:

Content is present
Metadata is correct
Canonical is correct

Tools

Google Search Console (URL Inspection)
Rich Results Test

Final Checklist

◽️ Data fetched in Server Components
◽️ Correct rendering strategy selected
◽️ HTML contains full content
◽️ Metadata fully implemented
◽️ Canonical URLs consistent
◽️ Sitemap clean and accurate
◽️ Robots configured correctly
◽️ Structured data added
◽️ LCP optimized
◽️ Verified via raw HTML

Conclusion

Technical SEO in Next.js is about intentional control.

Control how pages are rendered
Control what gets indexed
Keep all signals consistent

If you get these right, SEO becomes predictable—not guesswork.

Technical SEO for Engineers: How Rendering Strategy Affects Indexing in Next.js

Nana Okamoto — Fri, 17 Apr 2026 13:20:01 +0000

When people talk about SEO, it often revolves around content, keywords, and backlinks. But if you're building with modern frameworks like Next.js, how your app renders can make or break whether your content is even seen by search engines.

This article breaks down the technical side of SEO—specifically how App Router's rendering strategies impact crawling and indexing—and how to make the right choices as an engineer.

🚨 The Core Problem: Google’s View vs. User Experience

Search engines don’t experience your site like a browser with full JavaScript execution. Google uses a two-phase indexing process:

Initial crawl: Scans the raw HTML.
Deferred rendering: JavaScript execution (happens later when resources allow).

That gap is where problems happen. If your page relies on Client-Side Rendering (CSR), the initial HTML looks like this:

<body>
  <div id="root"></div>
  <script src="bundle.js"></script>
</body>

At the initial crawl stage, there is no content. Even though Google can render JavaScript later, it is delayed, resource-limited, and not guaranteed.
👉 Result: Your page may be indexed late—or not at all.

🧠 Mapping Rendering Strategies to SEO

In the App Router, every component is a Server Component by default, which is a massive win for SEO.

1. CSR

How it works: You opt-out of server rendering using "use client". Data is fetched inside useEffect.
SEO Impact: ❌ Empty initial HTML. ❌ Depends on Google rendering JS.
When it's okay: Authenticated dashboards or internal tools where SEO doesn't matter.

2. SSR

How it works: The server renders the page on every request (e.g., when using headers() or cookies()).
SEO Impact: ✅ Content is immediately visible and reliable.

3. SSG

How it works: HTML is generated at build time. This is the default in App Router.
SEO Impact: ✅ Fastest delivery and fully indexable.

4. ISR

How it works: Static pages are regenerated in the background at a specific interval.
SEO Impact: ✅ Combines performance with freshness. Ideal for blogs and product catalogs.

🔍 Verification: What Google Actually Sees

Don’t guess—inspect the raw HTML.

The curl test: Run curl https://your-site.com. If the output doesn't contain your content, you have an SEO risk.
View Page Source: Right-click in the browser and select "View Page Source" (avoid the DevTools Elements tab).
Search Console: Use the "URL Inspection" tool to see exactly how Googlebot rendered the page.

⚡️ The Link Between Rendering and Core Web Vitals

SEO isn't just about indexing; performance is a major ranking factor.

LCP (Largest Contentful Paint): Much faster with Static/Dynamic rendering because content is in the first byte.
CLS (Cumulative Layout Shift): Server-rendered content reduces shifts that happen during client-side "hydration."
INP (Interaction to Next Paint): Server Components reduce client-side JS, leading to a leaner main thread and faster response to user inputs.

❌ Critical SEO Misconceptions

The "JS is Fine" Fallback: Thinking Google handles JS perfectly is risky. Heavy JS may be skipped or timed out, causing silent indexing failures.
The "Next.js is a Magic Bullet" Myth: Frameworks provide the tools, but using "use client" excessively for data fetching re-introduces CSR risks.

✅ Implementation Guidelines

Default to Static or ISR for blogs, landing pages, and marketing content.
Use Dynamic Rendering for frequently updated or personalized content that requires indexing.
Keep data fetching on the server. Only use Client Components for leaf-level interactivity (buttons, forms, etc.).

🧩 Final Thought

Technical SEO is about making your content accessible to crawlers as efficiently as possible. As engineers, we control the delivery.

Rendering strategy is not just an architectural decision—it’s an SEO decision. With App Router, you're in a great position to be "Server-first," ensuring your content is always ready for the crawl.

Stop Manually Managing URLSearchParams in Next.js — Use nuqs Instead

Nana Okamoto — Fri, 13 Mar 2026 14:03:48 +0000

Modern web applications often represent UI state in the URL.

For example:

search filters
pagination
sorting
tab selection
dashboard parameters

A typical URL might look like this:

/products?category=books&sort=price&page=2

Synchronizing UI state with the URL improves several things:

shareability (users can share filtered views)
bookmarking
browser navigation
predictable application state

However, implementing this in Next.js App Router often leads to repetitive and fragile code.

Recently I started using a library called nuqs, and it significantly improved the developer experience when managing URL state.

In this article I'll cover:

why managing query parameters manually is painful
why I chose nuqs
how to use it in real projects
what improved in my development workflow

The Problem: Manual URL State Management

Without a helper library, managing URL state usually requires combining:

useSearchParams
useRouter
URLSearchParams
useState
useEffect

Example:

'use client'

import { useRouter, useSearchParams } from 'next/navigation'
import { useState, useEffect } from 'react'

export default function ProductFilter() {
  const router = useRouter()
  const searchParams = useSearchParams()

  const [category, setCategory] = useState(
    searchParams.get('category') || ''
  )

  useEffect(() => {
    const params = new URLSearchParams(searchParams)
    params.set('category', category)

    router.push(`?${params.toString()}`)
  }, [category])

  return (
    <select
      value={category}
      onChange={(e) => setCategory(e.target.value)}
    >
      <option value="">All</option>
      <option value="books">Books</option>
      <option value="games">Games</option>
    </select>
  )
}

While this works, it introduces several problems.

Problems ⚡️

• Boilerplate code everywhere
• Manual parsing of URLSearchParams
• Hard to scale with multiple filters
• Easy to introduce bugs
• No built-in type safety

As applications grow (for example search pages or dashboards), this logic quickly becomes hard to maintain.

What Is nuqs?

nuqs is a lightweight library that treats URL query parameters as React state.
Instead of manually synchronizing state and the URL, you simply use a hook.
Conceptually:

URL Query <-> React State

This drastically simplifies query parameter management.

Installing nuqs

npm install nuqs

That's it.

The Same Example Using nuqs

Here is the same filter example rewritten with nuqs.

'use client'

import { useQueryState } from 'nuqs'

export default function ProductFilter() {
  const [category, setCategory] = useQueryState('category')

  return (
    <select
      value={category ?? ''}
      onChange={(e) => setCategory(e.target.value)}
    >
      <option value="">All</option>
      <option value="books">Books</option>
      <option value="games">Games</option>
    </select>
  )
}

The URL automatically updates when the state changes.

Example result:

/products?category=books

Compared to the manual implementation:

no router logic
no useEffect
no manual query parsing

Type-Safe Query Parameters

One of the most powerful features of nuqs is its parser system.
Example: pagination.

import { useQueryState, parseAsInteger } from 'nuqs'

const [page, setPage] = useQueryState(
  'page',
  parseAsInteger.withDefault(1)
)

Benefits:

page is always a number
default value is 1
invalid query values are handled safely

This prevents many runtime bugs.

Managing Multiple Query Parameters

Complex UIs usually have multiple filters.
nuqs handles this cleanly using useQueryStates.

import { useQueryStates, parseAsString } from 'nuqs'

const [filters, setFilters] = useQueryStates({
  category: parseAsString,
  sort: parseAsString
})

Updating the filters:

setFilters({
  category: 'books',
  sort: 'price'
})

Resulting URL:

?category=books&sort=price

This keeps filter logic predictable and easy to maintain.

Why I Chose nuqs

When selecting a library for URL state management, I considered several factors.

1. Developer Experience

nuqs removes the need to manually synchronize state and the URL.

Instead of managing useEffect, URLSearchParams, and router updates, query parameters behave like React state.

This dramatically reduces boilerplate and improves readability.

2. Type Safety

The parser system allows query parameters to be typed.
This ensures predictable values and reduces runtime errors in TypeScript projects.

3. Zero Dependencies and Lightweight

Another reason I chose nuqs is that it has zero runtime dependencies.
This is important for several reasons:

smaller bundle size
fewer potential security vulnerabilities
lower risk of dependency conflicts
easier long-term maintenance

In modern frontend projects, dependency trees can grow quickly.
Using focused libraries with minimal dependencies helps keep applications lean.

nuqs follows this philosophy very well.

4. Designed for Modern Next.js

nuqs integrates naturally with Next.js App Router and React hooks.
It fits well into modern React architectures without introducing additional complexity.

Real Impact in My Project

After introducing nuqs, several improvements became clear.

Less Boilerplate
Query state logic became significantly smaller and easier to understand.

Better Maintainability
Adding new filters now requires only a few lines.

Fewer Bugs
Type-safe parsing prevents invalid query states.

Better UX
Because the UI state lives in the URL:

filters can be shared
pages can be bookmarked
browser navigation works naturally

When nuqs Is Especially Useful

From my experience, nuqs works especially well for:

search/filter pages
e-commerce listings
dashboards
analytics tools
pagination systems
sorting UIs

In other words:
✨ any interface where UI state should be reflected in the URL.

Final Thoughts

Managing URL state manually in Next.js often leads to repetitive and fragile code.

nuqs provides a clean abstraction that treats query parameters as React state while keeping everything type-safe and lightweight.

For modern React and Next.js applications, it can significantly improve both:

developer experience
code maintainability

If you're building filter-heavy interfaces or dashboards, I highly recommend giving nuqs a try!

Implementing Push Notifications with Next.js and Firebase Cloud Messaging

Nana Okamoto — Mon, 28 Apr 2025 06:54:10 +0000

Push notifications are a powerful way to engage users and bring them back to your application. In this tutorial, we'll implement push notifications in a Next.js application using Firebase Cloud Messaging (FCM). We'll cover setting up Firebase, configuring permissions, and handling notifications in both foreground and background states.

Note: This guide is based on Next.js 15 or later. Ensure your project uses this version to follow along.

Prerequisites

Basic knowledge of TypeScript and Next.js
A Firebase account
Node.js installed on your machine

Step 1: Configure Firebase in Your Project

First, create a new Firebase project:

Go to the Firebase Console
Create a new project (or use an existing one)
Add a web app to your project
Install the Firebase SDK in your Next.js project:

npm install firebase

Create a firebase-config.ts file in your project to configure Firebase:

// firebase-config.ts
import { initializeApp } from "firebase/app";
import { getMessaging, getToken, onMessage } from "firebase/messaging";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
};

let messaging: ReturnType<typeof getMessaging>;

if (typeof window !== "undefined" && "navigator" in window) {
  const app = initializeApp(firebaseConfig);
  messaging = getMessaging(app);
}

export { messaging, getToken, onMessage };

Step 2: Setting Up Service Worker

Firebase Cloud Messaging requires a service worker to handle background notifications. Create a file called firebase-messaging-sw.js in your public directory:

// firebase-messaging-sw.js
importScripts(
  "https://www.gstatic.com/firebasejs/10.11.1/firebase-app-compat.js"
);
importScripts(
  "https://www.gstatic.com/firebasejs/10.11.1/firebase-messaging-compat.js"
);

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  appId: "YOUR_MESSAGING_SENDER_ID",
  messagingSenderId: "YOUR_APP_ID",
};

firebase.initializeApp(firebaseConfig);

const messaging = firebase.messaging();

messaging.onBackgroundMessage((payload) => {
  const notificationTitle = payload.notification.title;
  const notificationOptions = {
    body:
      payload.notification.body,
      icon: payload.notification.icon,
    data: { url: payload.fcmOptions?.link || "/" },
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
});

self.addEventListener("notificationclick", (event) => {
  event.notification.close();
  const targetUrl = event.notification.data?.url || "/";

  event.waitUntil(
    clients
      .matchAll({
        type: "window",
        includeUncontrolled: true,
      })
      .then((clientList) => {
        for (const client of clientList) {
          if (client.url.includes(targetUrl) && "focus" in client) {
            return client.focus();
          }
        }
        return clients.openWindow(targetUrl);
      })
  );
});

Important Note: You should not use environment variables in the service worker file as it's served directly by the browser. For production, you would need to implement a build step that replaces these values.

Step 3: Request Notification Permission

1. Requesting Permission

Request user permission for push notifications, as explicit consent is required. If needed, save the retrieved token to your database within this function.

// requestNotificationPermission.ts
import { getToken, messaging } from "./firebase";

export const requestNotificationPermission = async () => {
  try {
    const permission = await Notification.requestPermission();

    if (permission !== "granted") {
      return;
    }

    const registration = await navigator.serviceWorker.register(
      "/firebase-messaging-sw.js"
    );

    if (!registration) {
      return;
    }

    const token = await getToken(messaging, {
      vapidKey: process.env.NEXT_PUBLIC_FIREBASE_VAPID_KEY,
      serviceWorkerRegistration: registration,
    });

    if (!token) {
      return;
    }

    // Save the Token to a Database here if you need

  } catch (error) {
    console.error("Error Requesting Notification Permission:", error);
    return;
  }
};

2. Creating a Notification Component

To handle incoming notifications elegantly, create a dedicated Notification Permission component:

// components/NotificationPermission.tsx
"use client";

import { useEffect } from "react";
import { requestNotificationPermission } from "@/lib/firebase/requestNotificationPermission";

const NotificationPermission = () => {

  useEffect(() => {
    const subscribeUser = async () => {
        await requestNotificationPermission(user.id);
      };

    subscribeUser();
  }, []);

  return null;
};

export default NotificationPermission;

3. Adding the Notification Component

Integrate the Notification component into your application layout to ensure it is always active:

// layout.tsx
import NotificationPermission from "@/components/notification/NotificationPermission";
...

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <NotificationPermission/>
        {children}
      </body>
    </html>
  );
}

Step 4: Adding the firebase-admin.json

In order to send notifications from your server, you will need to integrate Firebase Admin SDK. This requires adding the firebase-admin.json configuration file to your project.

Go to the Firebase Console.
Under Project Settings > Service Accounts, generate a new private key.
Download the key file, which is named firebase-admin.json.
Place the firebase-admin.json file in your project’s root or a secure folder.

Now, you’ll need to install the firebase-admin package:

npm install firebase-admin

Finally, configure Firebase Admin SDK to use this file by adding the following code to your backend:

// firebaseAdmin.ts
import admin from "firebase-admin";
import settings from "../../../config/firebase-admin.json";

const serviceAccount = settings as admin.ServiceAccount;

if (!admin.apps.length) {
  try {
    admin.initializeApp({
      credential: admin.credential.cert(serviceAccount),
    });
    console.log("Firebase Admin Initialized Successfully");
  } catch (error) {
    console.error("Firebase Admin Initialization Failed:", error);
  }
}

export default admin;

Step 5: Sending Notifications via Firebase Admin SDK

Add the following function to handle sending notifications:

// sendNotification.ts
import admin from "@/lib/firebase/firebaseAdmin";

interface Recipient {
  endpoint: string;
}

export const sendNotification = async (
  title: string,
  body: string,
  recipients: Recipient[]
) => {
  try {
    const response = await admin.messaging().sendEachForMulticast({
      tokens: recipients.map((recipient) => recipient.endpoint),
      notification: { title, body },
    });

    console.log(
      `Notification sent! Success: ${response.successCount}, Failures: ${response.failureCount}`
    );

    if (response.failureCount > 0) {
      response.responses.forEach((res, index) => {
        if (
          !res.success &&
          res.error?.code === "messaging/registration-token-not-registered"
        ) {
          console.warn(`Invalid token found: ${recipients[index].endpoint}`);
        }
      });
    }
  } catch (error) {
    console.error("Error sending notifications:", error);
  }
};

Step 6: Creating the Notification API

To send notifications programmatically, you need an API endpoint. Create an API route in your Next.js application:

// pages/api/notifications/route.ts
import { NextRequest, NextResponse } from "next/server";
import { sendNotification } from "@/lib/firebase/sendNotification";

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();

    const { title, body, recipients } = body;

    if (!title || !body || !recipients) {
        return NextResponse.json(
          { success: false, message: "Missing required fields" },
          { status: 400 }
        );
    }

    await sendNotification(title, body, recipients);
    return res.status(200).json({ message: "Notification sent successfully" });

  } catch (error) {
    console.error("Error sending notification:", error);
    res.status(500).json({ error: "Failed to send notification" });
  }
}

To call this API, send a POST request to /api/notifications with a JSON body containing the title, body, and recipients. The title and body should be strings, and recipients should be an array of FCM tokens.

Step 7: Environment Setup

Ensure that you add the required environment variables:

// .env.local
NEXT_PUBLIC_FIREBASE_API_KEY=your-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
NEXT_PUBLIC_FIREBASE_APP_ID=your-app-id
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your-vapid-public-key

Get the first 6 variables from your Firebase Console: All of these can be found under Project Settings > General.
Get a VAPID key from the Web configuration section in Firebase Console > Project Settings > Cloud Messaging under "Web Push certificates."

⚠️ Security Considerations

When working with push notifications, always keep the following in mind:

Never expose your Firebase Admin SDK credentials in client-side code
Store environment variables securely
Implement proper validation and authentication for your notification API
Consider rate limiting to prevent abuse

Conclusion

By setting up Firebase Cloud Messaging (FCM) with Web Push notifications in Next.js, you’ve enabled an effective way to engage your users in real-time. However, always stay mindful of security best practices, keep an eye on evolving web push standards, and regularly check Firebase documentation for new updates and features.

Simplifying Authentication in React Applications with Clerk

Nana Okamoto — Fri, 29 Nov 2024 02:03:10 +0000

User authentication is essential for web applications.
While working on my personal food delivery app project , I needed a secure and easy-to-integrate solution, and that’s when I discovered Clerk. It’s a powerful, customizable authentication library that works seamlessly with React. Clerk offers simple sign-up/sign-in, OAuth, and social logins.

In this article, I’ll share how I integrated Clerk into my React application, how quickly I got it up and running, and why I believe it’s an excellent choice for authentication　for individual developers.

Why Clerk?

When I started researching authentication solutions, I was overwhelmed by the variety of options available. Many tools offered flexibility but required significant setup and maintenance. Then, I found Clerk, which stood out for its:

Ease of use: Clerk provides prebuilt components for sign-in, sign-up, and user profile management that integrate seamlessly into React.
Security: Clerk handles sensitive authentication flows, such as token management and session storage, adhering to modern security best practices.
Developer focus: Its detailed documentation and intuitive API reduce the learning curve.

Setting Up Clerk in a React App

Setting up Clerk was a breeze. Here’s a quick overview of how I added it to my React application:

Step 1: Sign up and create a Clerk project

Start by creating a new project in Clerk's dashboard.
During setup, as shown in the screenshot below, you can immediately set your service name and choose authentication methods, making customization quick and easy. Once created, you’ll get API keys and a frontend API URL for integration.

Step 2: Install Clerk package

npm install @clerk/clerk-react

After installing the package, set up the required environment variables.
The VITE_CLERK_PUBLISHABLE_KEY can be obtained from the Clerk dashboard

VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

Step 3: Configure ClerkProvider

Wrap your application with the ClerkProvider component, which provides the necessary context for authentication.

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import { ClerkProvider } from '@clerk/clerk-react'

const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

if (!PUBLISHABLE_KEY) {
  throw new Error('Add your Clerk publishable key to the .env.local file')
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/">
      <App />
    </ClerkProvider>
  </React.StrictMode>,
)

Step 4: Add Sign-In and Sign-Up Components to the Header

Let's integrate Clerk components into your app's Header.
In this example, we’ll use Clerk's <SignedIn> and <SignedOut> components.

<SignedIn> renders its children only when the user is logged in.
<SignedOut> renders its children only when no user is logged in.

import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from "@clerk/clerk-react";

const Header = () => {
  return (
    <header>
      <h1>My App</h1>
      <nav>
        <SignedIn>
          {/* Display the UserButton when logged in */}
          <UserButton />
        </SignedIn>
        <SignedOut>
          {/* Redirect to Sign-In when no user is logged in */}
          <RedirectToSignIn />
        </SignedOut>
      </nav>
    </header>
  );
};

export default Header;

Step 5: Protect Routes

You can restrict access to certain routes based on the user’s authentication status.

import { useAuth } from '@clerk/clerk-react';  
import { Navigate } from 'react-router-dom';  

const ProtectedPage = () => {  
  const { isSignedIn } = useAuth();  

  if (!isSignedIn) {  
    return <Navigate to="/sign-in" />;  
  }  

  return <div>...</div>
};  

export default ProtectedRoute;

What Else Can Clerk Do?

Clerk offers a lot more to enhance your app’s authentication system:

OAuth & Social Logins: Easily integrate logins with providers like Google, GitHub, and Twitter.
Multi-Factor Authentication (MFA): Add an extra layer of security with SMS or authentication apps.
Passwordless Authentication: Use magic links or one-time passcodes for a smoother user experience.
User Profiles: Customize and manage user profiles with additional fields.
Role-Based Access Control (RBAC): Restrict or grant access to features based on user roles.
Webhooks: Automate workflows with webhooks for events like sign-ups or profile updates.

Why Clerk for Solo Developers?

Clerk is a game-changer for solo developers. It requires minimal setup and lets you focus on building core features while handling the complexities of user authentication and security. I implemented a fully functional login system in under an hour, saving me time.

Conclusion

Clerk simplifies authentication in React applications by providing a fast, secure, and customizable solution. Whether you’re building a small app or a larger platform, Clerk offers everything you need to implement a robust authentication system without hassle.

References:

📕 Clerk Documentation