DEV Community: Mahdi BEN RHOUMA

Next.js Server Actions with Supabase: Complete Production Guide

Mahdi BEN RHOUMA — Sat, 09 May 2026 10:12:45 +0000

Next.js Server Actions with Supabase: Complete Production Guide

Server Actions fundamentally changed how we build forms in Next.js. Instead of creating API routes, managing fetch calls, and handling loading states manually, you write async functions that run on the server and call them directly from components.

Combined with Supabase, Server Actions provide a powerful pattern for building type-safe, progressively enhanced applications that work without JavaScript while delivering modern UX when it's available.

This guide covers everything you need to build production-ready Server Actions with Supabase.

Prerequisites

Next.js 14+ with App Router
Supabase project configured
TypeScript (recommended)
Basic understanding of React Server Components

Why Server Actions with Supabase

Traditional approach requires three separate files:

// app/api/posts/route.ts
export async function POST(request: Request) {
  const body = await request.json()
  // validation, auth, database logic
}

// components/PostForm.tsx
async function handleSubmit(e) {
  e.preventDefault()
  const response = await fetch('/api/posts', {
    method: 'POST',
    body: JSON.stringify(data)
  })
}

Server Actions collapse this into a single function:

// actions/posts.ts
'use server'

export async function createPost(formData: FormData) {
  const supabase = createClient()
  // validation, auth, database logic
}

// components/PostForm.tsx
<form action={createPost}>

Benefits:

No API route boilerplate
Automatic serialization
Progressive enhancement (works without JS)
Type-safe by default
Simpler error handling
Built-in revalidation

Basic Server Action Setup

Create a dedicated actions directory:

// actions/posts.ts
'use server'

import { createClient } from '@/lib/supabase/server'
import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  const supabase = await createClient()

  // Extract form data
  const title = formData.get('title') as string
  const content = formData.get('content') as string

  // Get authenticated user
  const { data: { user }, error: authError } = await supabase.auth.getUser()

  if (authError || !user) {
    return { error: 'Unauthorized' }
  }

  // Insert into database
  const { data, error } = await supabase
    .from('posts')
    .insert({
      title,
      content,
      user_id: user.id
    })
    .select()
    .single()

  if (error) {
    return { error: error.message }
  }

  // Revalidate the posts page
  revalidatePath('/posts')

  return { success: true, data }
}

Use in a component:

// components/PostForm.tsx
import { createPost } from '@/actions/posts'

export function PostForm() {
  return (
    <form action={createPost}>
      <input type="text" name="title" required />
      <textarea name="content" required />
      <button type="submit">Create Post</button>
    </form>
  )
}

This works without JavaScript. When JS loads, Next.js intercepts the form submission and calls the action via fetch.

Type-Safe Validation with Zod

Never trust form data. Always validate:

// actions/posts.ts
'use server'

import { z } from 'zod'
import { createClient } from '@/lib/supabase/server'
import { revalidatePath } from 'next/cache'

const PostSchema = z.object({
  title: z.string().min(3).max(100),
  content: z.string().min(10).max(5000),
  published: z.boolean().default(false)
})

export type PostFormState = {
  errors?: {
    title?: string[]
    content?: string[]
    published?: string[]
    _form?: string[]
  }
  success?: boolean
}

export async function createPost(
  prevState: PostFormState,
  formData: FormData
): Promise<PostFormState> {
  // Parse and validate
  const validatedFields = PostSchema.safeParse({
    title: formData.get('title'),
    content: formData.get('content'),
    published: formData.get('published') === 'on'
  })

  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors
    }
  }

  const supabase = await createClient()

  const { data: { user }, error: authError } = await supabase.auth.getUser()

  if (authError || !user) {
    return {
      errors: {
        _form: ['You must be logged in to create a post']
      }
    }
  }

  const { error } = await supabase
    .from('posts')
    .insert({
      ...validatedFields.data,
      user_id: user.id
    })

  if (error) {
    return {
      errors: {
        _form: [error.message]
      }
    }
  }

  revalidatePath('/posts')
  return { success: true }
}

Display validation errors with useFormState:

// components/PostForm.tsx
'use client'

import { useFormState } from 'react-dom'
import { createPost } from '@/actions/posts'

export function PostForm() {
  const [state, formAction] = useFormState(createPost, {})

  return (
    <form action={formAction}>
      <div>
        <label htmlFor="title">Title</label>
        <input
          type="text"
          id="title"
          name="title"
          required
        />
        {state.errors?.title && (
          <p className="text-red-500">{state.errors.title[0]}</p>
        )}
      </div>

      <div>
        <label htmlFor="content">Content</label>
        <textarea
          id="content"
          name="content"
          required
        />
        {state.errors?.content && (
          <p className="text-red-500">{state.errors.content[0]}</p>
        )}
      </div>

      <div>
        <label>
          <input type="checkbox" name="published" />
          Publish immediately
        </label>
      </div>

      {state.errors?._form && (
        <p className="text-red-500">{state.errors._form[0]}</p>
      )}

      {state.success && (
        <p className="text-green-500">Post created successfully!</p>
      )}

      <button type="submit">Create Post</button>
    </form>
  )
}

Loading States and Pending UI

Use useFormStatus to show loading states:

'use client'

import { useFormState, useFormStatus } from 'react-dom'
import { createPost } from '@/actions/posts'

function SubmitButton() {
  const { pending } = useFormStatus()

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Creating...' : 'Create Post'}
    </button>
  )
}

export function PostForm() {
  const [state, formAction] = useFormState(createPost, {})

  return (
    <form action={formAction}>
      {/* form fields */}
      <SubmitButton />
    </form>
  )
}

useFormStatus must be called from a component inside the form, not the form component itself.

Optimistic Updates

Provide instant feedback with useOptimistic:

'use client'

import { useOptimistic } from 'react'
import { useFormState } from 'react-dom'
import { createPost } from '@/actions/posts'

type Post = {
  id: string
  title: string
  content: string
  created_at: string
}

export function PostList({ initialPosts }: { initialPosts: Post[] }) {
  const [optimisticPosts, addOptimisticPost] = useOptimistic(
    initialPosts,
    (state, newPost: Post) => [...state, newPost]
  )

  const [state, formAction] = useFormState(createPost, {})

  async function handleSubmit(formData: FormData) {
    // Add optimistic post immediately
    addOptimisticPost({
      id: crypto.randomUUID(),
      title: formData.get('title') as string,
      content: formData.get('content') as string,
      created_at: new Date().toISOString()
    })

    // Call server action
    await formAction(formData)
  }

  return (
    <>
      <form action={handleSubmit}>
        {/* form fields */}
      </form>

      <div>
        {optimisticPosts.map(post => (
          <article key={post.id}>
            <h2>{post.title}</h2>
            <p>{post.content}</p>
          </article>
        ))}
      </div>
    </>
  )
}

When the Server Action completes, React automatically reconciles the optimistic state with the real data.

File Uploads with Server Actions

Handle file uploads to Supabase Storage:

// actions/uploads.ts
'use server'

import { createClient } from '@/lib/supabase/server'
import { revalidatePath } from 'next/cache'

export async function uploadAvatar(formData: FormData) {
  const supabase = await createClient()

  const { data: { user }, error: authError } = await supabase.auth.getUser()

  if (authError || !user) {
    return { error: 'Unauthorized' }
  }

  const file = formData.get('avatar') as File

  if (!file || file.size === 0) {
    return { error: 'No file provided' }
  }

  // Validate file type
  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp']
  if (!allowedTypes.includes(file.type)) {
    return { error: 'Invalid file type. Use JPEG, PNG, or WebP' }
  }

  // Validate file size (5MB max)
  if (file.size > 5 * 1024 * 1024) {
    return { error: 'File too large. Maximum size is 5MB' }
  }

  // Generate unique filename
  const fileExt = file.name.split('.').pop()
  const fileName = `${user.id}-${Date.now()}.${fileExt}`

  // Upload to Supabase Storage
  const { error: uploadError } = await supabase.storage
    .from('avatars')
    .upload(fileName, file, {
      cacheControl: '3600',
      upsert: false
    })

  if (uploadError) {
    return { error: uploadError.message }
  }

  // Get public URL
  const { data: { publicUrl } } = supabase.storage
    .from('avatars')
    .getPublicUrl(fileName)

  // Update user profile
  const { error: updateError } = await supabase
    .from('profiles')
    .update({ avatar_url: publicUrl })
    .eq('id', user.id)

  if (updateError) {
    return { error: updateError.message }
  }

  revalidatePath('/profile')
  return { success: true, url: publicUrl }
}

Form component:

'use client'

import { useFormState } from 'react-dom'
import { uploadAvatar } from '@/actions/uploads'

export function AvatarUploadForm() {
  const [state, formAction] = useFormState(uploadAvatar, {})

  return (
    <form action={formAction}>
      <input
        type="file"
        name="avatar"
        accept="image/jpeg,image/png,image/webp"
        required
      />

      {state.error && (
        <p className="text-red-500">{state.error}</p>
      )}

      {state.success && (
        <p className="text-green-500">Avatar uploaded successfully!</p>
      )}

      <button type="submit">Upload Avatar</button>
    </form>
  )
}

Revalidation Strategies

Server Actions can trigger cache revalidation:

import { revalidatePath, revalidateTag } from 'next/cache'

// Revalidate specific path
revalidatePath('/posts')

// Revalidate all posts pages
revalidatePath('/posts', 'layout')

// Revalidate by cache tag
revalidateTag('posts')

Use tags for fine-grained control:

// Fetch with cache tag
const { data } = await supabase
  .from('posts')
  .select()
  .then(res => {
    // Tag this data
    return res
  })

// In Server Action
revalidateTag('posts')

Error Handling Patterns

Structured error handling:

type ActionResult<T> = 
  | { success: true; data: T }
  | { success: false; error: string; field?: string }

export async function createPost(
  formData: FormData
): Promise<ActionResult<Post>> {
  try {
    const supabase = await createClient()

    // Validation
    const title = formData.get('title') as string
    if (!title || title.length < 3) {
      return {
        success: false,
        error: 'Title must be at least 3 characters',
        field: 'title'
      }
    }

    // Auth check
    const { data: { user }, error: authError } = await supabase.auth.getUser()
    if (authError || !user) {
      return {
        success: false,
        error: 'You must be logged in'
      }
    }

    // Database operation
    const { data, error } = await supabase
      .from('posts')
      .insert({ title, user_id: user.id })
      .select()
      .single()

    if (error) {
      // Handle specific Postgres errors
      if (error.code === '23505') {
        return {
          success: false,
          error: 'A post with this title already exists',
          field: 'title'
        }
      }

      return {
        success: false,
        error: 'Failed to create post'
      }
    }

    revalidatePath('/posts')
    return { success: true, data }

  } catch (error) {
    console.error('Unexpected error:', error)
    return {
      success: false,
      error: 'An unexpected error occurred'
    }
  }
}

Common Pitfalls

1. Forgetting 'use server' Directive

Server Actions must have 'use server' at the top of the file or function:

// ❌ Missing directive
export async function createPost(formData: FormData) {
  // This won't work
}

// ✅ File-level directive
'use server'

export async function createPost(formData: FormData) {
  // Works
}

// ✅ Function-level directive
export async function createPost(formData: FormData) {
  'use server'
  // Works
}

2. Using Client-Only APIs

Server Actions run on the server. No window, localStorage, or browser APIs:

// ❌ Won't work
export async function saveData(formData: FormData) {
  'use server'
  localStorage.setItem('key', 'value') // Error!
}

3. Not Handling Race Conditions

Multiple rapid submissions can cause issues:

'use client'

import { useFormState } from 'react-dom'
import { useState, useTransition } from 'react'

export function PostForm() {
  const [isPending, startTransition] = useTransition()
  const [state, formAction] = useFormState(createPost, {})

  function handleSubmit(formData: FormData) {
    startTransition(() => {
      formAction(formData)
    })
  }

  return (
    <form action={handleSubmit}>
      {/* fields */}
      <button type="submit" disabled={isPending}>
        {isPending ? 'Submitting...' : 'Submit'}
      </button>
    </form>
  )
}

4. Returning Non-Serializable Data

Server Actions can only return JSON-serializable data:

// ❌ Can't return Date objects
export async function getPost() {
  'use server'
  return {
    created_at: new Date() // Error!
  }
}

// ✅ Return ISO strings
export async function getPost() {
  'use server'
  return {
    created_at: new Date().toISOString()
  }
}

5. Missing Revalidation

Changes won't appear without revalidation:

export async function updatePost(id: string, formData: FormData) {
  'use server'

  const supabase = await createClient()
  await supabase.from('posts').update(data).eq('id', id)

  // ❌ Forgot to revalidate
  return { success: true }
}

// ✅ Always revalidate
export async function updatePost(id: string, formData: FormData) {
  'use server'

  const supabase = await createClient()
  await supabase.from('posts').update(data).eq('id', id)

  revalidatePath(`/posts/${id}`)
  revalidatePath('/posts')

  return { success: true }
}

Production Patterns

Rate Limiting

Protect Server Actions from abuse:

// lib/rate-limit.ts
import { createClient } from '@/lib/supabase/server'

export async function checkRateLimit(
  userId: string,
  action: string,
  limit: number,
  windowMs: number
): Promise<boolean> {
  const supabase = await createClient()

  const windowStart = new Date(Date.now() - windowMs)

  const { count } = await supabase
    .from('rate_limits')
    .select('*', { count: 'exact', head: true })
    .eq('user_id', userId)
    .eq('action', action)
    .gte('created_at', windowStart.toISOString())

  if (count && count >= limit) {
    return false
  }

  await supabase.from('rate_limits').insert({
    user_id: userId,
    action,
    created_at: new Date().toISOString()
  })

  return true
}

// actions/posts.ts
export async function createPost(formData: FormData) {
  'use server'

  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return { error: 'Unauthorized' }
  }

  // 5 posts per hour
  const allowed = await checkRateLimit(user.id, 'create_post', 5, 60 * 60 * 1000)

  if (!allowed) {
    return { error: 'Rate limit exceeded. Try again later.' }
  }

  // Continue with post creation
}

Audit Logging

Track all mutations:

async function logAction(
  userId: string,
  action: string,
  resourceType: string,
  resourceId: string,
  metadata?: Record<string, any>
) {
  const supabase = await createClient()

  await supabase.from('audit_logs').insert({
    user_id: userId,
    action,
    resource_type: resourceType,
    resource_id: resourceId,
    metadata,
    created_at: new Date().toISOString()
  })
}

export async function deletePost(postId: string) {
  'use server'

  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return { error: 'Unauthorized' }
  }

  const { error } = await supabase
    .from('posts')
    .delete()
    .eq('id', postId)
    .eq('user_id', user.id)

  if (error) {
    return { error: error.message }
  }

  await logAction(user.id, 'delete', 'post', postId)

  revalidatePath('/posts')
  return { success: true }
}

Summary

Server Actions with Supabase provide a powerful pattern for building modern web applications:

Eliminate API route boilerplate
Type-safe by default with TypeScript
Progressive enhancement works without JavaScript
Built-in form handling and validation
Optimistic updates for instant feedback
Automatic cache revalidation

Start with basic Server Actions for simple forms, then add validation, optimistic updates, and production patterns as your application grows.

[INTERNAL LINK: nextjs-app-router-complete-guide]
[INTERNAL LINK: supabase-authentication-authorization]
[INTERNAL LINK: nextjs-supabase-security-best-practices]

Originally published at https://iloveblogs.blog

Next.js Performance Optimization for Indie Developers

Mahdi BEN RHOUMA — Fri, 08 May 2026 10:43:57 +0000

Next.js Performance Optimization for Indie Developers

Performance isn't just about speed—it's about user experience, SEO rankings, and conversion rates. A 1-second delay in page load time can reduce conversions by 7%. This comprehensive guide teaches you how to optimize Next.js applications for maximum performance.

Why Performance Matters

User Experience:

53% of mobile users abandon sites that take longer than 3 seconds to load
Fast sites feel more professional and trustworthy
Better performance = better user retention

SEO Impact:

Core Web Vitals are ranking factors
Faster sites get crawled more frequently
Better performance = higher search rankings

Business Metrics:

Amazon found every 100ms of latency cost them 1% in sales
Google found 500ms delay reduced traffic by 20%
Performance directly impacts revenue

1. Understanding Core Web Vitals

The Three Key Metrics

Largest Contentful Paint (LCP)

Measures loading performance
Target: < 2.5 seconds
Largest visible element in viewport

First Input Delay (FID) / Interaction to Next Paint (INP)

Measures interactivity
Target: < 100ms (FID) or < 200ms (INP)
Time from user interaction to response

Cumulative Layout Shift (CLS)

Measures visual stability
Target: < 0.1
Unexpected layout shifts

Measuring Performance

// lib/web-vitals.ts
import { onCLS, onFID, onLCP, onINP } from 'web-vitals'

export function reportWebVitals() {
  onCLS(console.log)
  onFID(console.log)
  onLCP(console.log)
  onINP(console.log)
}

// app/layout.tsx
'use client'

import { useEffect } from 'react'
import { reportWebVitals } from '@/lib/web-vitals'

export default function RootLayout({ children }) {
  useEffect(() => {
    reportWebVitals()
  }, [])

  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

2. Image Optimization

Next.js Image Component

import Image from 'next/image'

export function OptimizedImage() {
  return (
    <Image
      src="/hero.jpg"
      alt="Hero image"
      width={1200}
      height={600}
      priority // Load immediately for above-fold images
      placeholder="blur"
      blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..." // Low-quality placeholder
    />
  )
}

Responsive Images

<Image
  src="/hero.jpg"
  alt="Hero image"
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  style={{ objectFit: 'cover' }}
/>

Image Formats

// next.config.mjs
export default {
  images: {
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

External Image Optimization

// next.config.mjs
export default {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'your-cdn.com',
        port: '',
        pathname: '/images/**',
      },
    ],
  },
}

Related: Next.js Image Component Optimization Complete Guide, Implement Image Compression Before Supabase Upload

3. Code Splitting and Bundling

Dynamic Imports

// Lazy load heavy components
import dynamic from 'next/dynamic'

const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <p>Loading chart...</p>,
  ssr: false, // Disable server-side rendering if not needed
})

export function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <HeavyChart />
    </div>
  )
}

Route-Based Code Splitting

Next.js automatically code-splits by route:

app/
  dashboard/
    page.tsx      # Only loaded when visiting /dashboard
  settings/
    page.tsx      # Only loaded when visiting /settings

Component-Level Code Splitting

'use client'

import { lazy, Suspense } from 'react'

const VideoPlayer = lazy(() => import('@/components/VideoPlayer'))

export function VideoSection() {
  return (
    <Suspense fallback={<div>Loading video...</div>}>
      <VideoPlayer src="/video.mp4" />
    </Suspense>
  )
}

Bundle Analysis

## Install bundle analyzer
npm install @next/bundle-analyzer

## Analyze bundle
ANALYZE=true npm run build

// next.config.mjs
import bundleAnalyzer from '@next/bundle-analyzer'

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})

export default withBundleAnalyzer({
  // Your Next.js config
})

Related: Optimize Next.js Bundle Size Under 100KB Guide, Next.js 15 Server Components Performance Best Practices

4. Server-Side Rendering Optimization

Server Components (Default)

// app/posts/page.tsx
// This is a Server Component by default
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    cache: 'force-cache', // Cache indefinitely
  })
  return res.json()
}

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

  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>{post.title}</article>
      ))}
    </div>
  )
}

Client Components (When Needed)

'use client'

import { useState } from 'react'

export function InteractiveButton() {
  const [count, setCount] = useState(0)

  return (
    <button onClick={() => setCount(count + 1)}>
      Clicked {count} times
    </button>
  )
}

Streaming with Suspense

import { Suspense } from 'react'

async function SlowComponent() {
  await new Promise(resolve => setTimeout(resolve, 3000))
  return <div>Slow content loaded!</div>
}

export default function Page() {
  return (
    <div>
      <h1>Fast content</h1>
      <Suspense fallback={<div>Loading slow content...</div>}>
        <SlowComponent />
      </Suspense>
    </div>
  )
}

Parallel Data Fetching

// ❌ Sequential (slow)
async function SequentialPage() {
  const user = await fetchUser()
  const posts = await fetchPosts()
  return <div>{/* ... */}</div>
}

// ✅ Parallel (fast)
async function ParallelPage() {
  const [user, posts] = await Promise.all([
    fetchUser(),
    fetchPosts(),
  ])
  return <div>{/* ... */}</div>
}

Related: Next.js 15 Server Components Performance Best Practices, Fix Next.js Slow Page Load Times Step by Step

5. Static Generation and ISR

Static Site Generation (SSG)

// app/posts/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(res => res.json())

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

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

  return <article>{post.content}</article>
}

Incremental Static Regeneration (ISR)

// Revalidate every 60 seconds
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 60 }
  })
  return res.json()
}

export default async function PostsPage() {
  const posts = await getPosts()
  return <div>{/* ... */}</div>
}

On-Demand Revalidation

// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache'
import { NextRequest } from 'next/server'

export async function POST(request: NextRequest) {
  const path = request.nextUrl.searchParams.get('path')

  if (path) {
    revalidatePath(path)
    return Response.json({ revalidated: true, now: Date.now() })
  }

  return Response.json({ revalidated: false, now: Date.now() })
}

Related: Implement Next.js Incremental Static Regeneration ISR, Next.js Edge Runtime vs Node Runtime When to Use

6. Caching Strategies

Fetch Caching

// Cache indefinitely
fetch('https://api.example.com/data', {
  cache: 'force-cache'
})

// Never cache
fetch('https://api.example.com/data', {
  cache: 'no-store'
})

// Revalidate after 60 seconds
fetch('https://api.example.com/data', {
  next: { revalidate: 60 }
})

React Cache

import { cache } from 'react'

export const getUser = cache(async (id: string) => {
  const user = await db.user.findUnique({ where: { id } })
  return user
})

// Called multiple times but only executes once per request
const user1 = await getUser('123')
const user2 = await getUser('123') // Uses cached result

Memoization

import { unstable_cache } from 'next/cache'

const getCachedPosts = unstable_cache(
  async () => {
    return await db.post.findMany()
  },
  ['posts'],
  {
    revalidate: 3600, // 1 hour
    tags: ['posts'],
  }
)

7. Database Query Optimization

Efficient Queries

// ❌ N+1 query problem
const posts = await db.post.findMany()
for (const post of posts) {
  const author = await db.user.findUnique({ where: { id: post.authorId } })
}

// ✅ Single query with join
const posts = await db.post.findMany({
  include: {
    author: true,
  },
})

Pagination

// Cursor-based pagination (efficient)
const posts = await db.post.findMany({
  take: 10,
  skip: 1,
  cursor: {
    id: lastPostId,
  },
  orderBy: {
    createdAt: 'desc',
  },
})

Indexing

-- Add indexes for frequently queried columns
CREATE INDEX idx_posts_author_id ON posts(author_id);
CREATE INDEX idx_posts_created_at ON posts(created_at DESC);
CREATE INDEX idx_posts_slug ON posts(slug);

Related: Supabase Database Query Optimization, Supabase Database Indexing Strategies

8. Font Optimization

Next.js Font Optimization

import { Inter, Roboto_Mono } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
})

const robotoMono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-roboto-mono',
})

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
      <body>{children}</body>
    </html>
  )
}

Custom Fonts

import localFont from 'next/font/local'

const myFont = localFont({
  src: './my-font.woff2',
  display: 'swap',
  variable: '--font-my-font',
})

9. Reducing First Contentful Paint (FCP)

Critical CSS

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <style dangerouslySetInnerHTML={{
          __html: `
            /* Critical CSS for above-the-fold content */
            body { margin: 0; font-family: system-ui; }
            .hero { min-height: 100vh; }
          `
        }} />
      </head>
      <body>{children}</body>
    </html>
  )
}

Preload Critical Resources

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <link
          rel="preload"
          href="/fonts/inter.woff2"
          as="font"
          type="font/woff2"
          crossOrigin="anonymous"
        />
      </head>
      <body>{children}</body>
    </html>
  )
}

Remove Render-Blocking Resources

// next.config.mjs
export default {
  compiler: {
    removeConsole: process.env.NODE_ENV === 'production',
  },
}

Related: Reduce Next.js First Contentful Paint FCP, Next.js Bundle Size Optimization

10. Monitoring and Measuring Performance

Real User Monitoring (RUM)

// app/layout.tsx
'use client'

import { useReportWebVitals } from 'next/web-vitals'

export function WebVitals() {
  useReportWebVitals((metric) => {
    // Send to analytics
    fetch('/api/analytics', {
      method: 'POST',
      body: JSON.stringify(metric),
    })
  })

  return null
}

Performance API

if (typeof window !== 'undefined') {
  const perfData = window.performance.getEntriesByType('navigation')[0]
  console.log('DNS lookup:', perfData.domainLookupEnd - perfData.domainLookupStart)
  console.log('TCP connection:', perfData.connectEnd - perfData.connectStart)
  console.log('Request time:', perfData.responseStart - perfData.requestStart)
  console.log('Response time:', perfData.responseEnd - perfData.responseStart)
  console.log('DOM processing:', perfData.domComplete - perfData.domLoading)
}

Lighthouse CI

## .github/workflows/lighthouse.yml
name: Lighthouse CI
on: [push]
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run build
      - run: npm install -g @lhci/cli
      - run: lhci autorun

Related: Monitor Next.js Application Performance in Production, Next.js Performance Optimization Complete Guide

11. Edge Runtime Optimization

Edge Functions

// app/api/edge/route.ts
export const runtime = 'edge'

export async function GET(request: Request) {
  return new Response('Hello from the edge!', {
    headers: {
      'content-type': 'text/plain',
    },
  })
}

Edge Middleware

// middleware.ts
export const config = {
  matcher: '/api/:path*',
}

export function middleware(request: Request) {
  const country = request.geo?.country || 'US'

  return new Response(JSON.stringify({ country }), {
    headers: {
      'content-type': 'application/json',
    },
  })
}

Related: Next.js Edge Runtime vs Node Runtime When to Use, Deploy Next.js Supabase App to Vercel Production

12. Common Performance Pitfalls

Avoid Client-Side Data Fetching

// ❌ Bad: Client-side fetching
'use client'
import { useEffect, useState } from 'react'

export function Posts() {
  const [posts, setPosts] = useState([])

  useEffect(() => {
    fetch('/api/posts')
      .then(res => res.json())
      .then(setPosts)
  }, [])

  return <div>{/* ... */}</div>
}

// ✅ Good: Server-side fetching
async function getPosts() {
  const res = await fetch('https://api.example.com/posts')
  return res.json()
}

export default async function Posts() {
  const posts = await getPosts()
  return <div>{/* ... */}</div>
}

Avoid Large Client Bundles

// ❌ Bad: Import entire library
import _ from 'lodash'

// ✅ Good: Import only what you need
import debounce from 'lodash/debounce'

Avoid Layout Shifts

// ❌ Bad: No dimensions
<img src="/image.jpg" alt="Image" />

// ✅ Good: Explicit dimensions
<Image
  src="/image.jpg"
  alt="Image"
  width={800}
  height={600}
/>

Complete Guide to Building SaaS with Next.js and Supabase
Deploying Next.js + Supabase to Production
Next.js 15 Server Components Performance Best Practices
Optimize Next.js Bundle Size Under 100KB Guide

Conclusion

Performance optimization is an ongoing process. Start with the basics—optimize images, reduce bundle size, and leverage server components. Then move to advanced techniques like ISR, edge functions, and fine-tuned caching strategies.

Remember: measure first, optimize second. Use tools like Lighthouse and Web Vitals to identify bottlenecks, then apply targeted optimizations.

Fast sites win. Start optimizing today.

Originally published at https://iloveblogs.blog

Resolve Next.js Hydration Mismatch Errors Complete Guide

Mahdi BEN RHOUMA — Thu, 07 May 2026 11:13:30 +0000

Resolve Next.js Hydration Mismatch Errors Complete Guide

Hydration mismatch errors are one of the most common and frustrating issues in Next.js applications. You see warnings like "Text content does not match server-rendered HTML" or "Hydration failed because the initial UI does not match what was rendered on the server." This comprehensive guide explains why these happen and provides 8 proven solutions.

This article is part of our comprehensive Deploying Next.js + Supabase to Production guide.

What is Hydration?

Hydration is the process where React attaches event listeners to server-rendered HTML:

Server renders HTML - Next.js generates static HTML on the server
Browser receives HTML - User sees content immediately (fast!)
React hydrates - JavaScript makes the page interactive
Mismatch detected - If HTML doesn't match, React throws an error

Common Error Messages

## Error 1: Text content mismatch
Warning: Text content did not match. Server: "Hello" Client: "Hi"

## Error 2: Prop mismatch
Warning: Prop `className` did not match. Server: "dark" Client: "light"

## Error 3: Extra/missing elements
Warning: Expected server HTML to contain a matching <div> in <div>

## Error 4: Hydration failed
Error: Hydration failed because the initial UI does not match

Solution 1: Fix Date/Time Rendering

The #1 cause of hydration errors:

Problem: Server and Client Timezones Differ

// ❌ BAD: Server and client render different times
export function PostDate({ date }: { date: Date }) {
  return <time>{date.toLocaleString()}</time>
  // Server (UTC): "2/16/2026, 10:00:00 AM"
  // Client (PST): "2/16/2026, 2:00:00 AM"
  // ❌ Hydration mismatch!
}

Solution: Use suppressHydrationWarning

// ✅ GOOD: Suppress warning for time elements
export function PostDate({ date }: { date: Date }) {
  return (
    <time suppressHydrationWarning>
      {date.toLocaleString()}
    </time>
  )
}

Solution: Client-Side Only Rendering

'use client'

import { useEffect, useState } from 'react'

export function PostDate({ date }: { date: Date }) {
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
  }, [])

  if (!mounted) {
    // Return server-safe fallback
    return <time>{date.toISOString().split('T')[0]}</time>
  }

  // Client-side rendering
  return <time>{date.toLocaleString()}</time>
}

Solution: Use UTC Consistently

// ✅ BEST: Format in UTC on both server and client
export function PostDate({ date }: { date: Date }) {
  const formatted = new Intl.DateTimeFormat('en-US', {
    timeZone: 'UTC',
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  }).format(date)

  return <time>{formatted}</time>
}

Solution 2: Fix localStorage/sessionStorage Access

Browser APIs don't exist on the server:

Problem: Accessing localStorage During Render

// ❌ BAD: localStorage accessed during render
export function ThemeToggle() {
  const theme = localStorage.getItem('theme') || 'light'
  // ❌ ReferenceError: localStorage is not defined (server)

  return <button>{theme}</button>
}

Solution: Use useEffect Hook

'use client'

import { useEffect, useState } from 'react'

export function ThemeToggle() {
  const [theme, setTheme] = useState('light')  // Default value

  useEffect(() => {
    // Only runs on client
    const savedTheme = localStorage.getItem('theme') || 'light'
    setTheme(savedTheme)
  }, [])

  return <button>{theme}</button>
}

Solution: Create Custom Hook

// hooks/useLocalStorage.ts
'use client'

import { useEffect, useState } from 'react'

export function useLocalStorage<T>(key: string, initialValue: T) {
  const [value, setValue] = useState<T>(initialValue)
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
    try {
      const item = window.localStorage.getItem(key)
      if (item) {
        setValue(JSON.parse(item))
      }
    } catch (error) {
      console.error(`Error reading localStorage key "${key}":`, error)
    }
  }, [key])

  const setStoredValue = (newValue: T) => {
    try {
      setValue(newValue)
      window.localStorage.setItem(key, JSON.stringify(newValue))
    } catch (error) {
      console.error(`Error setting localStorage key "${key}":`, error)
    }
  }

  return [mounted ? value : initialValue, setStoredValue] as const
}

// Usage
export function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage('theme', 'light')

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      {theme}
    </button>
  )
}

Solution 3: Fix Random Values

Random values differ between server and client:

Problem: Math.random() or uuid()

// ❌ BAD: Random ID generated on server and client
export function RandomComponent() {
  const id = Math.random().toString(36)
  // Server: "0.abc123"
  // Client: "0.xyz789"
  // ❌ Hydration mismatch!

  return <div id={id}>Content</div>
}

Solution: Generate ID on Client Only

'use client'

import { useId } from 'react'

export function RandomComponent() {
  // React's useId generates consistent IDs
  const id = useId()

  return <div id={id}>Content</div>
}

Solution: Pass ID as Prop

// Generate ID on server, pass as prop
export function ParentComponent() {
  const id = crypto.randomUUID()

  return <RandomComponent id={id} />
}

export function RandomComponent({ id }: { id: string }) {
  return <div id={id}>Content</div>
}

Solution 4: Fix Conditional Rendering

Different conditions on server vs client:

Problem: window Object Checks

// ❌ BAD: window check causes mismatch
export function ResponsiveComponent() {
  const isMobile = typeof window !== 'undefined' && window.innerWidth < 768
  // Server: false (window undefined)
  // Client: true (if mobile)
  // ❌ Hydration mismatch!

  return <div>{isMobile ? 'Mobile' : 'Desktop'}</div>
}

Solution: Use CSS Media Queries

// ✅ GOOD: CSS handles responsiveness
export function ResponsiveComponent() {
  return (
    <>
      <div className="block md:hidden">Mobile</div>
      <div className="hidden md:block">Desktop</div>
    </>
  )
}

Solution: Client-Side Detection

'use client'

import { useEffect, useState } from 'react'

export function ResponsiveComponent() {
  const [isMobile, setIsMobile] = useState(false)

  useEffect(() => {
    const checkMobile = () => setIsMobile(window.innerWidth < 768)
    checkMobile()
    window.addEventListener('resize', checkMobile)
    return () => window.removeEventListener('resize', checkMobile)
  }, [])

  // Render same content on server and initial client render
  return <div>{isMobile ? 'Mobile' : 'Desktop'}</div>
}

Solution 5: Fix Third-Party Libraries

Some libraries cause hydration issues:

Problem: Libraries with Browser-Only Code

// ❌ BAD: Chart library runs on server
import Chart from 'some-chart-library'

export function ChartComponent() {
  return <Chart data={data} />
  // ❌ May cause hydration errors
}

Solution: Dynamic Import with ssr: false

import dynamic from 'next/dynamic'

// ✅ GOOD: Load only on client
const Chart = dynamic(() => import('some-chart-library'), {
  ssr: false,
  loading: () => <div>Loading chart...</div>,
})

export function ChartComponent() {
  return <Chart data={data} />
}

Solution: Wrap in Client Component

// components/ChartWrapper.tsx
'use client'

import Chart from 'some-chart-library'

export function ChartWrapper({ data }) {
  return <Chart data={data} />
}

// page.tsx (Server Component)
import { ChartWrapper } from '@/components/ChartWrapper'

export default function Page() {
  return <ChartWrapper data={data} />
}

Solution 6: Fix HTML Structure Issues

Invalid HTML nesting causes hydration errors:

Problem: Invalid Nesting

// ❌ BAD: <p> cannot contain <div>
export function BadNesting() {
  return (
    <p>
      <div>This is invalid HTML</div>
    </p>
  )
}

// ❌ BAD: <button> cannot contain <button>
export function NestedButtons() {
  return (
    <button>
      <button>Click</button>
    </button>
  )
}

Solution: Fix HTML Structure

// ✅ GOOD: Valid HTML nesting
export function GoodNesting() {
  return (
    <div>
      <p>Paragraph text</p>
      <div>Div content</div>
    </div>
  )
}

// ✅ GOOD: No nested buttons
export function NoNestedButtons() {
  return (
    <div>
      <button onClick={handleClick}>Click</button>
    </div>
  )
}

Solution 7: Fix Browser Extension Interference

Browser extensions can modify HTML:

Problem: Extensions Inject Code

// Extensions like Grammarly, LastPass, etc. inject HTML
// This causes hydration mismatches

Solution: Add suppressHydrationWarning to Root

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body suppressHydrationWarning>{children}</body>
    </html>
  )
}

Solution: Detect and Handle Extensions

'use client'

import { useEffect, useState } from 'react'

export function ExtensionSafeComponent() {
  const [isClient, setIsClient] = useState(false)

  useEffect(() => {
    setIsClient(true)
  }, [])

  if (!isClient) {
    return <div>Loading...</div>
  }

  return <div>Content safe from extensions</div>
}

Solution 8: Debug Hydration Errors

Find the exact source of errors:

Enable Detailed Errors

// next.config.mjs
const nextConfig = {
  reactStrictMode: true,  // Shows hydration errors in development
}

Use React DevTools

## Install React DevTools browser extension
## Enable "Highlight updates" to see hydration issues

Add Error Boundaries

'use client'

import { Component, ReactNode } from 'react'

export class HydrationErrorBoundary extends Component<
  { children: ReactNode },
  { hasError: boolean }
> {
  constructor(props) {
    super(props)
    this.state = { hasError: false }
  }

  static getDerivedStateFromError() {
    return { hasError: true }
  }

  componentDidCatch(error, errorInfo) {
    console.error('Hydration error:', error, errorInfo)
  }

  render() {
    if (this.state.hasError) {
      return <div>Something went wrong. Please refresh.</div>
    }

    return this.props.children
  }
}

Common Mistakes

Mistake #1: Ignoring warnings - Hydration warnings indicate real bugs
Mistake #2: Using suppressHydrationWarning everywhere - Only use for unavoidable cases
Mistake #3: Not testing with extensions disabled - Extensions can hide real issues
Mistake #4: Accessing window during render - Use useEffect for browser APIs
Mistake #5: Different server/client logic - Keep rendering logic consistent

FAQ

Are hydration warnings serious?

Yes! They indicate your app's HTML doesn't match between server and client, which can cause bugs, poor performance, and SEO issues.

Can I just suppress all warnings?

No. suppressHydrationWarning should only be used for unavoidable cases like timestamps. Fix the root cause instead.

Why do hydration errors only appear sometimes?

They depend on timing, browser extensions, and environment differences. Test thoroughly in production-like environments.

Do hydration errors affect SEO?

Yes. Search engines see the server-rendered HTML, but users might see different content after hydration, confusing search engines.

How do I test for hydration errors?

Enable React Strict Mode, test with different timezones, disable browser extensions, and test on different devices.

Next.js Turbopack Stuck on Compiling How to Fix
Fix Next.js Build Error Module Not Found After Deploy
Deploy Next.js 15 to Vercel Without Environment Variable Errors
Next.js Performance Optimization: 10 Essential Techniques

Conclusion

Hydration mismatch errors occur when server-rendered HTML doesn't match client-rendered HTML. The most common causes are date/time formatting, localStorage access, random values, and conditional rendering based on browser APIs.

Fix these by using suppressHydrationWarning sparingly, moving browser API access to useEffect, using consistent UTC formatting for dates, and ensuring HTML structure is valid. Always test with React Strict Mode enabled and browser extensions disabled.

Remember: hydration warnings are not just cosmetic issues—they indicate real bugs that can affect user experience, performance, and SEO. Take the time to fix them properly rather than suppressing them.

Solution 2: Fix localStorage/sessionStorage Access

Browser APIs don't exist on the server:

// ❌ BAD: localStorage doesn't exist on server
export function UserPreferences() {
  const theme = localStorage.getItem('theme')
  return <div className={theme}>Content</div>
}

// ✅ GOOD: Check if window exists
export function UserPreferences() {
  const theme = typeof window !== 'undefined' 
    ? localStorage.getItem('theme') 
    : 'light'
  return <div className={theme}>Content</div>
}

// ✅ BETTER: Use useEffect
'use client'

import { useEffect, useState } from 'react'

export function UserPreferences() {
  const [theme, setTheme] = useState('light')

  useEffect(() => {
    setTheme(localStorage.getItem('theme') || 'light')
  }, [])

  return <div className={theme}>Content</div>
}

Solution 3: Fix Random Values

Never use Math.random() in render:

// ❌ BAD: Different random on server vs client
export function RandomId() {
  return <div id={Math.random()}>Content</div>
}

// ✅ GOOD: Generate ID in useEffect
'use client'

import { useEffect, useState } from 'react'

export function RandomId() {
  const [id, setId] = useState('')

  useEffect(() => {
    setId(Math.random().toString(36).substr(2, 9))
  }, [])

  return <div id={id}>Content</div>
}

// ✅ BETTER: Use a library
import { useId } from 'react'

export function RandomId() {
  const id = useId()
  return <div id={id}>Content</div>
}

Solution 4: Fix Conditional Rendering

Ensure same content renders on server and client:

// ❌ BAD: Different rendering based on client state
export function ThemeToggle() {
  const [isDark, setIsDark] = useState(false)

  return (
    <div>
      {isDark ? '🌙 Dark' : '☀️ Light'}
    </div>
  )
}
// Server renders: ☀️ Light
// Client renders: 🌙 Dark (from state)
// ❌ Mismatch!

// ✅ GOOD: Render same on server and client
export function ThemeToggle() {
  const [isDark, setIsDark] = useState(false)
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setIsDark(localStorage.getItem('theme') === 'dark')
    setMounted(true)
  }, [])

  if (!mounted) {
    return <div>☀️ Light</div>  // Server renders this
  }

  return (
    <div>
      {isDark ? '🌙 Dark' : '☀️ Light'}
    </div>
  )
}

Solution 5: Fix Browser-Only APIs

Never use window/document in Server Components:

// ❌ BAD: window doesn't exist on server
export function UserAgent() {
  return <div>{window.navigator.userAgent}</div>
}

// ✅ GOOD: Use 'use client' directive
'use client'

export function UserAgent() {
  return <div>{window.navigator.userAgent}</div>
}

// ✅ BETTER: Use useEffect
'use client'

import { useEffect, useState } from 'react'

export function UserAgent() {
  const [userAgent, setUserAgent] = useState('')

  useEffect(() => {
    setUserAgent(window.navigator.userAgent)
  }, [])

  return <div>{userAgent}</div>
}

Solution 6: Fix Prop Serialization

Props must be serializable (no functions, dates, etc.):

// ❌ BAD: Non-serializable props
export function Component({ callback }: { callback: () => void }) {
  return <button onClick={callback}>Click</button>
}

// ✅ GOOD: Serialize dates to strings
export function Component({ date }: { date: string }) {
  return <div>{date}</div>
}

// ✅ GOOD: Use server actions for callbacks
'use client'

export function Component({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
  return (
    <form action={onSubmit}>
      <button type="submit">Submit</button>
    </form>
  )
}

Solution 7: Fix Inline Functions

Never pass inline functions as props:

// ❌ BAD: Inline function changes on every render
export function Component() {
  return (
    <Child onClick={() => console.log('clicked')} />
  )
}

// ✅ GOOD: Define function outside
const handleClick = () => console.log('clicked')

export function Component() {
  return <Child onClick={handleClick} />
}

// ✅ GOOD: Use useCallback
'use client'

import { useCallback } from 'react'

export function Component() {
  const handleClick = useCallback(() => {
    console.log('clicked')
  }, [])

  return <Child onClick={handleClick} />
}

Solution 8: Use Dynamic Imports

For components that can't be hydrated:

import dynamic from 'next/dynamic'

// Load component without SSR
const ClientOnlyComponent = dynamic(
  () => import('@/components/ClientOnly'),
  { ssr: false }
)

export default function Page() {
  return (
    <div>
      <h1>Server Content</h1>
      <ClientOnlyComponent />
    </div>
  )
}

Advanced Debugging

Enable React Strict Mode

// next.config.mjs
const nextConfig = {
  reactStrictMode: true,
}

export default nextConfig

Add Hydration Monitoring

'use client'

import { useEffect } from 'react'

export function HydrationMonitor() {
  useEffect(() => {
    console.log('✅ Hydration complete')

    // Monitor for mismatches
    const observer = new MutationObserver(() => {
      console.warn('⚠️ DOM changed after hydration')
    })

    observer.observe(document.body, {
      childList: true,
      subtree: true,
    })

    return () => observer.disconnect()
  }, [])

  return null
}

Test Hydration Locally

# Build for production
npm run build

# Start production server
npm run start

# Test in different browsers
# Test with different timezones
# Test with browser extensions disabled

Prevention Checklist

Before committing code:

□ No direct window/document access in Server Components
□ No Math.random() in render
□ No new Date() in render (use useEffect)
□ No localStorage/sessionStorage without useEffect
□ All conditional rendering is consistent
□ All props are serializable
□ No inline functions in props
□ No circular references in state
□ React Strict Mode enabled
□ Tested in production build

Common Mistakes

Mistake #1: Using suppressHydrationWarning everywhere - Only use for unavoidable cases like timestamps
Mistake #2: Not testing production builds - Hydration errors often only appear in production
Mistake #3: Ignoring timezone differences - Server and client may be in different timezones
Mistake #4: Passing functions as props - Functions aren't serializable
Mistake #5: Not using useEffect for client-only code - Browser APIs must be accessed in useEffect

FAQ

Are hydration warnings serious?

Yes! They indicate your app HTML does not match between server and client, which can cause bugs, poor performance, and SEO issues.

Can I just suppress all warnings?

No. suppressHydrationWarning should only be used for unavoidable cases like timestamps. Fix the root cause instead.

Why do hydration errors only appear sometimes?

They depend on timing, browser extensions, and environment differences. Test thoroughly in production-like environments.

Do hydration errors affect SEO?

Yes. Search engines see the server-rendered HTML, but users might see different content after hydration, confusing search engines.

How do I test for hydration errors?

Enable React Strict Mode, test with different timezones, disable browser extensions, and test on different devices.

Conclusion

Hydration mismatch errors are usually caused by inconsistent rendering between server and client. The most common causes are date/time differences, browser API access, and random values.

The key to preventing these errors is ensuring your server and client render identical HTML. Use useEffect for client-only code, suppressHydrationWarning only for unavoidable cases, and always test your production builds.

With these solutions in place, you'll eliminate hydration errors and have a more stable, performant Next.js application.

Originally published at https://iloveblogs.blog

Fix Next.js Build Error Module Not Found After Deploy

Mahdi BEN RHOUMA — Wed, 06 May 2026 11:11:04 +0000

Fix Next.js Build Error Module Not Found After Deploy

"Module not found" errors that only appear after deployment are among the most confusing Next.js issues. Your app works perfectly in development, builds successfully locally, but fails in production with cryptic module errors. This comprehensive guide covers every cause and provides battle-tested solutions.

This article is part of our comprehensive Deploying Next.js + Supabase to Production guide.

Why Module Errors Only Happen in Production

Development and production environments differ in critical ways:

Case Sensitivity - Production servers (Linux) are case-sensitive, Windows/Mac aren't
Path Resolution - Different module resolution algorithms
Build Optimization - Tree-shaking removes "unused" imports
Environment Variables - Missing or incorrect env vars
Dependencies - devDependencies not installed in production

Common Error Messages

## Error 1: Cannot find module
Error: Cannot find module '@/components/Header'

## Error 2: Module not found (Webpack)
Module not found: Can't resolve './components/header'

## Error 3: Dynamic import failure
Error: Cannot find module './pages/dashboard'

## Error 4: Package not found
Module not found: Can't resolve 'some-package'

Solution 1: Fix Case Sensitivity Issues

The #1 cause of production-only module errors:

Identify Case Mismatches

// BAD: Import doesn't match actual filename
// File: components/Header.tsx
import { Header } from '@/components/header'  // ❌ lowercase 'h'

// File: lib/utils.ts
import { formatDate } from './Utils'  // ❌ Capital 'U'

// GOOD: Exact case match
// File: components/Header.tsx
import { Header } from '@/components/Header'  // ✅ Capital 'H'

// File: lib/utils.ts
import { formatDate } from './utils'  // ✅ lowercase 'u'

Find All Case Mismatches

## Install case-sensitive-paths-webpack-plugin
npm install --save-dev case-sensitive-paths-webpack-plugin

## Add to next.config.mjs
import CaseSensitivePathsPlugin from 'case-sensitive-paths-webpack-plugin'

const nextConfig = {
  webpack: (config, { isServer }) => {
    config.plugins.push(new CaseSensitivePathsPlugin())
    return config
  },
}

export default nextConfig

Automated Fix Script

// scripts/fix-case-sensitivity.js
const fs = require('fs')
const path = require('path')
const glob = require('glob')

// Find all TypeScript/JavaScript files
const files = glob.sync('**/*.{ts,tsx,js,jsx}', {
  ignore: ['node_modules/**', '.next/**'],
})

files.forEach(file => {
  let content = fs.readFileSync(file, 'utf8')
  let modified = false

  // Check each import statement
  const importRegex = /from ['"](.+)['"]/g
  let match

  while ((match = importRegex.exec(content)) !== null) {
    const importPath = match[1]

    // Skip node_modules and absolute paths
    if (!importPath.startsWith('.') && !importPath.startsWith('@/')) {
      continue
    }

    // Resolve actual file path
    const resolvedPath = path.resolve(path.dirname(file), importPath)

    // Check if file exists with different case
    if (fs.existsSync(resolvedPath)) {
      const actualPath = fs.realpathSync(resolvedPath)
      if (actualPath !== resolvedPath) {
        console.log(`Case mismatch in ${file}:`)
        console.log(`  Import: ${importPath}`)
        console.log(`  Actual: ${actualPath}`)
        modified = true
      }
    }
  }

  if (modified) {
    console.log(`Fixed: ${file}`)
  }
})

Solution 2: Fix Path Alias Configuration

Incorrect tsconfig.json or jsconfig.json paths:

Verify Path Aliases

// tsconfig.json or jsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],           // ✅ Correct
      "@/components/*": ["./src/components/*"],  // ✅ Specific paths
      "@/lib/*": ["./src/lib/*"],
      "~/*": ["./*"]                // ✅ Root alias
    }
  }
}

Common Path Alias Mistakes

// ❌ WRONG: Missing baseUrl
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]  // Won't work without baseUrl
    }
  }
}

// ❌ WRONG: Incorrect path format
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]  // Missing ./
    }
  }
}

// ✅ CORRECT
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Update Next.js Config

// next.config.mjs
const nextConfig = {
  // Ensure webpack resolves aliases correctly
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@': path.resolve(__dirname, 'src'),
    }
    return config
  },
}

Solution 3: Fix Dynamic Imports

Dynamic imports can fail in production:

Incorrect Dynamic Import

// ❌ BAD: Variable path
const pageName = 'dashboard'
const Page = dynamic(() => import(`./pages/${pageName}`))

// ❌ BAD: Computed path
const getComponent = (name) => dynamic(() => import(`@/components/${name}`))

Correct Dynamic Import

// ✅ GOOD: Static path with dynamic loading
const DashboardPage = dynamic(() => import('./pages/dashboard'))

// ✅ GOOD: Explicit imports with conditional rendering
const components = {
  dashboard: dynamic(() => import('@/components/Dashboard')),
  profile: dynamic(() => import('@/components/Profile')),
  settings: dynamic(() => import('@/components/Settings')),
}

function MyComponent({ type }) {
  const Component = components[type]
  return <Component />
}

// ✅ GOOD: Use webpack magic comments
const DynamicComponent = dynamic(() => 
  import(
    /* webpackChunkName: "dashboard" */
    /* webpackMode: "lazy" */
    './pages/dashboard'
  )
)

Solution 4: Fix Missing Dependencies

Dependencies in wrong section of package.json:

Check Dependency Location

// package.json

// ❌ WRONG: Build-time dependency in devDependencies
{
  "devDependencies": {
    "@supabase/supabase-js": "^2.38.0",  // Used in production!
    "next": "15.0.0"  // Should be in dependencies!
  }
}

// ✅ CORRECT: Production deps in dependencies
{
  "dependencies": {
    "@supabase/supabase-js": "^2.38.0",
    "next": "15.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@types/react": "^18.2.0",
    "typescript": "^5.0.0"
  }
}

Move Dependencies

## Move package from devDependencies to dependencies
npm install --save some-package
npm uninstall --save-dev some-package

## Or manually edit package.json and run:
npm install

Solution 5: Fix Environment-Specific Imports

Some imports only work in specific environments:

Server-Only Imports

// ❌ BAD: Server-only import in client component
'use client'

import fs from 'fs'  // ❌ fs doesn't exist in browser

export function MyComponent() {
  // ...
}

// ✅ GOOD: Use server actions or API routes
'use client'

export function MyComponent() {
  async function handleAction() {
    const response = await fetch('/api/read-file')
    const data = await response.json()
  }

  return <button onClick={handleAction}>Read File</button>
}

// app/api/read-file/route.ts
import fs from 'fs'  // ✅ OK in API route

export async function GET() {
  const data = fs.readFileSync('file.txt', 'utf8')
  return Response.json({ data })
}

Solution 6: Fix Vercel-Specific Issues

Vercel has specific requirements:

Output File Tracing

// next.config.mjs
const nextConfig = {
  // Ensure all dependencies are traced
  experimental: {
    outputFileTracingIncludes: {
      '/api/**/*': ['./node_modules/**/*.wasm', './node_modules/**/*.node'],
    },
  },

  // Exclude unnecessary files
  experimental: {
    outputFileTracingExcludes: {
      '*': [
        'node_modules/@swc/core-linux-x64-gnu',
        'node_modules/@swc/core-linux-x64-musl',
        'node_modules/@esbuild/linux-x64',
      ],
    },
  },
}

Vercel Build Command

// package.json
{
  "scripts": {
    "build": "next build",
    "vercel-build": "next build"  // Vercel uses this if present
  }
}

Solution 7: Debug Build Locally

Test production build locally:

## Build for production
npm run build

## Start production server
npm run start

## Or use Vercel CLI
npm install -g vercel
vercel build
vercel dev --prod

Enable Build Debugging

// next.config.mjs
const nextConfig = {
  // Show detailed build info
  productionBrowserSourceMaps: true,

  // Log webpack build
  webpack: (config, { dev, isServer }) => {
    if (!dev) {
      console.log('Production build for:', isServer ? 'server' : 'client')
    }
    return config
  },
}

Common Mistakes

Mistake #1: Inconsistent file naming - Use consistent casing across all files
Mistake #2: Wrong dependency section - Runtime deps must be in dependencies
Mistake #3: Dynamic imports with variables - Use static imports or explicit mapping
Mistake #4: Not testing production builds - Always test with npm run build && npm run start
Mistake #5: Ignoring TypeScript errors - Fix all TS errors before deploying

FAQ

Why does it work locally but not in production?

Local development (Windows/Mac) is case-insensitive, production (Linux) is case-sensitive. Also, dev mode doesn't optimize/tree-shake like production builds.

How do I find which module is missing?

Check the full error stack trace in your deployment logs. The error shows the exact import path that failed.

Can I make production case-insensitive?

No, but you can add case-sensitive-paths-webpack-plugin to catch issues during development.

Why do dynamic imports fail?

Webpack needs to know possible import paths at build time. Variable paths prevent this. Use static imports or explicit mapping.

Should I use relative or absolute imports?

Both work, but absolute imports (@/) are cleaner and easier to refactor. Just ensure tsconfig.json is configured correctly.

Advanced Debugging Strategies

Using Build Analysis Tools

## Analyze what's included in your build
npm install --save-dev @next/bundle-analyzer

## Add to next.config.mjs
import bundleAnalyzer from '@next/bundle-analyzer'

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
})

export default withBundleAnalyzer(nextConfig)

## Run analysis
ANALYZE=true npm run build

Debugging Import Resolution

// Create a debug script to trace imports
// scripts/debug-imports.js
const fs = require('fs')
const path = require('path')
const glob = require('glob')

const files = glob.sync('**/*.{ts,tsx,js,jsx}', {
  ignore: ['node_modules/**', '.next/**'],
})

files.forEach(file => {
  const content = fs.readFileSync(file, 'utf8')
  const importRegex = /from ['"](.+)['"]/g
  let match

  while ((match = importRegex.exec(content)) !== null) {
    const importPath = match[1]

    // Check if file exists
    const resolvedPath = path.resolve(path.dirname(file), importPath)
    if (!fs.existsSync(resolvedPath)) {
      console.log(`❌ Missing: ${importPath} in ${file}`)
    }
  }
})

Production Build Simulation

## Build and test locally before deploying
npm run build

## Start production server
npm run start

## Test critical routes
curl http://localhost:3000/
curl http://localhost:3000/api/health

## Check for errors in console

Environment-Specific Module Issues

Handling Platform-Specific Modules

// ❌ BAD: Platform-specific import in client code
import fs from 'fs'  // Only works on server

// ✅ GOOD: Use dynamic imports with ssr: false
import dynamic from 'next/dynamic'

const FileReader = dynamic(
  () => import('@/components/FileReader'),
  { ssr: false }
)

// ✅ GOOD: Use server actions
'use server'

export async function readFile(path: string) {
  const fs = await import('fs')
  return fs.readFileSync(path, 'utf8')
}

Conditional Imports Based on Environment

// lib/platform-specific.ts
let platformModule: any

if (typeof window === 'undefined') {
  // Server-side only
  platformModule = require('fs')
} else {
  // Client-side only
  platformModule = require('browser-storage')
}

export default platformModule

Monorepo-Specific Issues

Handling Monorepo Module Resolution

// tsconfig.json in monorepo root
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["apps/app/src/*"],
      "@api/*": ["apps/api/src/*"],
      "@shared/*": ["packages/shared/src/*"],
      "@ui/*": ["packages/ui/src/*"]
    }
  }
}

Monorepo Build Configuration

// next.config.mjs in monorepo app
const nextConfig = {
  webpack: (config, { isServer }) => {
    // Ensure monorepo packages are resolved
    config.resolve.alias = {
      ...config.resolve.alias,
      '@shared': path.resolve(__dirname, '../../packages/shared/src'),
      '@ui': path.resolve(__dirname, '../../packages/ui/src'),
    }
    return config
  },
}

Performance Optimization for Large Projects

Lazy Load Heavy Dependencies

// ❌ BAD: Import everything upfront
import * as lodash from 'lodash'

// ✅ GOOD: Lazy load only what you need
import { debounce } from 'lodash'

// ✅ BETTER: Use dynamic imports
const { debounce } = await import('lodash')

Tree-Shaking Configuration

// next.config.mjs
const nextConfig = {
  // Ensure tree-shaking works
  webpack: (config) => {
    config.optimization.usedExports = true
    config.optimization.sideEffects = true
    return config
  },

  // Mark packages as side-effect free
  modularizeImports: {
    'lodash': {
      transform: 'lodash/{{member}}',
    },
    '@mui/material': {
      transform: '@mui/material/{{member}}',
    },
  },
}

Testing Module Resolution

Create a Module Resolution Test

// __tests__/module-resolution.test.ts
import { describe, it, expect } from 'vitest'

describe('Module Resolution', () => {
  it('should resolve all path aliases', async () => {
    const modules = [
      '@/components/Button',
      '@/lib/utils',
      '@/types/index',
      '@/hooks/useAuth',
    ]

    for (const modulePath of modules) {
      const module = await import(modulePath)
      expect(module).toBeDefined()
    }
  })

  it('should not have circular dependencies', async () => {
    // Use madge to check
    const madge = require('madge')
    const result = await madge('src')
    expect(result.circular()).toHaveLength(0)
  })
})

Deployment Platform-Specific Fixes

Vercel-Specific Configuration

// next.config.mjs for Vercel
const nextConfig = {
  // Ensure all files are traced
  experimental: {
    outputFileTracingIncludes: {
      '/api/**/*': ['./node_modules/**/*.wasm'],
    },
  },

  // Exclude unnecessary files
  experimental: {
    outputFileTracingExcludes: {
      '*': [
        'node_modules/@swc/core-linux-x64-gnu',
        'node_modules/@swc/core-linux-x64-musl',
      ],
    },
  },
}

export default nextConfig

AWS Lambda/Netlify Configuration

// next.config.mjs for serverless
const nextConfig = {
  // Optimize for serverless
  experimental: {
    isrMemoryCacheSize: 0, // Disable ISR cache for serverless
  },

  // Ensure dependencies are bundled
  webpack: (config) => {
    config.externals = []
    return config
  },
}

export default nextConfig

Conclusion

Module not found errors in production are usually caused by case sensitivity mismatches, incorrect path aliases, or dependencies in the wrong package.json section. The fastest fix is ensuring all imports match exact file names (including case) and moving runtime dependencies to the dependencies section.

Always test production builds locally with npm run build && npm run start before deploying. Use case-sensitive-paths-webpack-plugin during development to catch issues early.

For Vercel deployments, check output file tracing configuration and ensure all necessary files are included in the build. Monitor deployment logs carefully to identify the exact module causing issues.

Originally published at https://iloveblogs.blog

How to Structure Your Next.js App Router Project for Scale

Mahdi BEN RHOUMA — Tue, 05 May 2026 10:51:13 +0000

import { Callout } from '@/components/mdx'

Introduction

Next.js App Router gives you unparalleled freedom. Aside from the mandatory routing conventions (page.tsx, layout.tsx), Next.js doesn't enforce how you should organize your UI components, hooks, utilities, or database calls.

For small projects, a simple components and lib folder works perfectly. But at scale—when your repository hits dozens of routes and millions of lines of code—the "flat folder" approach collapses into a tangled web of circular dependencies and unmaintainable code.

In 2026, the enterprise standard for Next.js organization is an adaptation of Feature-Sliced Design (FSD) natively integrated with App Router capabilities.

The "Everything in Components" Problem

The most common Next.js beginner folder structure looks like this:

/app
  /dashboard
    page.tsx
/components
  Button.tsx
  DashboardSidebar.tsx
  UserProfileCard.tsx
  DatePicker.tsx
/lib
  supabase.ts
  utils.ts

Why does this fail at scale? Because Button.tsx (a generic UI component) lives right next to DashboardSidebar.tsx (a highly specific, domain-coupled component that likely fetches data). When a new developer joins the team, they have no idea which components are universally safe to reuse and which are deeply tied to specific pages.

The Feature-Centric Approach

Instead of grouping files by their type (e.g., "all hooks go in a /hooks folder"), group files by their feature or domain.

Here is the ideal scalable structure:

/src
  /app                     # only routing logic
    /dashboard
      page.tsx
      layout.tsx

  /components              # purely generic, reusable UI (Design System)
    /ui
      Button.tsx
      Input.tsx
      Dialog.tsx

  /features                # Domain-specific modules
    /auth                  # "Auth" feature bundle
      /components
        LoginForm.tsx
      /actions
        login.ts
      /hooks
        useAuth.ts

    /billing               # "Billing" feature bundle
      /components
        PricingTable.tsx
      /actions
        checkout.ts
      /queries
        get-subscription.ts

  /lib                     # truly global utilities
    supabase.ts
    utils.ts

1. The `app` Directory (Routing Only)

Your app directory should be surprisingly thin. It should act purely as the router and entry point.

A typical page.tsx should just parse search params, run authorization checks, and render a high-level feature component:

// app/dashboard/billing/page.tsx
import { BillingDashboard } from '@/features/billing/components/BillingDashboard'
import { getSubscriptionStatus } from '@/features/billing/queries/get-subscription'

export default async function Page() {
  const status = await getSubscriptionStatus()

  return <BillingDashboard initialStatus={status} />
}

2. The `components/ui` Directory (Design System)

This directory should only contain dumb, stateless UI components. These components should never fetch their own data or know anything about your business logic.

If you use shadcn/ui, this is where those components live securely decoupled from your domain.

3. The `features` Directory (The Core)

This is where the magic happens. A "Feature" is a self-contained slice of domain logic. By isolating auth, billing, and projects into their own directories, you enforce strict architectural boundaries.

A file inside /features/billing is absolutely forbidden from importing from /features/auth/internal.

The index.ts rule: Every feature folder should have an index.ts file that exports only what other features are allowed to use. This creates a clear public API for your modules.

// src/features/billing/index.ts
export { PricingTable } from './components/PricingTable'
export { getSubscriptionStatus } from './queries/get-subscription'
export type { SubscriptionPlan } from './types'

4. Server Actions vs Data Queries

Notice how inside a feature folder we split /actions and /queries:

/queries: Read operations. These are standard async functions that fetch data (usually wrapped in Next.js cache).
/actions: Write operations. These files have the 'use server' directive at the top and handle mutations from the client.

By keeping these separate, you prevent accidentally exposing sensitive database query logic to the client side.

Why This Architecture Wins

Delete-ability: If you decide to remove a feature (e.g., a "Referral" system), you just delete the /features/referrals folder, rather than hunting for scattered hooks, components, and API routes across ten global folders.
Onboarding: New developers know exactly where to look. Need to fix a bug in billing? You don't scour the global components folder; you go straight to features/billing.
Colocation: Tests live right next to the code they test. Server actions live right next to the components that call them.

Adopting a feature-centric structure early feels like overkill, but by the time your Next.js app hits production, it will be the only thing keeping your codebase sane.

Originally published at https://iloveblogs.blog

Next.js App Router Complete Guide: From Basics to Advanced Patterns

Mahdi BEN RHOUMA — Mon, 04 May 2026 11:10:01 +0000

Next.js App Router Complete Guide: From Basics to Advanced Patterns

The Next.js App Router represents a fundamental shift in how we build React applications. This comprehensive guide will take you from the basics to advanced patterns, helping you master modern Next.js development.

Understanding the App Router
File-Based Routing
Layouts and Templates
Server and Client Components
Data Fetching Strategies
Route Handlers (API Routes)
Advanced Patterns

Understanding the App Router

The App Router is built on React Server Components and introduces new conventions for building applications with improved performance and developer experience.

Key Benefits

Server-First Architecture: Components render on the server by default
Streaming and Suspense: Progressive rendering for better UX
Nested Layouts: Share UI across routes efficiently
Colocation: Keep related files together
Improved Data Fetching: Fetch data where you need it

File-Based Routing

Basic Route Structure

app/
├── page.js                 # / route
├── about/
│   └── page.js            # /about route
├── blog/
│   ├── page.js            # /blog route
│   └── [slug]/
│       └── page.js        # /blog/[slug] dynamic route
└── dashboard/
    ├── layout.js          # Dashboard layout
    ├── page.js            # /dashboard route
    └── settings/
        └── page.js        # /dashboard/settings route

Dynamic Routes

// app/blog/[slug]/page.js
export default function BlogPost({ params }) {
  return <h1>Post: {params.slug}</h1>
}

// Generate static params at build time
export async function generateStaticParams() {
  const posts = await getPosts()
  return posts.map((post) => ({
    slug: post.slug,
  }))
}

Catch-All Routes

// app/docs/[...slug]/page.js
export default function Docs({ params }) {
  // params.slug will be an array: ['getting-started', 'installation']
  return <div>Docs: {params.slug.join('/')}</div>
}

Layouts and Templates

Root Layout (Required)

// app/layout.js
export const metadata = {
  title: 'My App',
  description: 'Welcome to my app',
}

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <header>
          <nav>{/* Navigation */}</nav>
        </header>
        <main>{children}</main>
        <footer>{/* Footer */}</footer>
      </body>
    </html>
  )
}

Nested Layouts

// app/dashboard/layout.js
export default function DashboardLayout({ children }) {
  return (
    <div className="dashboard">
      <aside>
        <DashboardNav />
      </aside>
      <section>{children}</section>
    </div>
  )
}

Templates (Re-render on Navigation)

// app/template.js
export default function Template({ children }) {
  return <div className="animate-fade-in">{children}</div>
}

Server and Client Components

Server Components (Default)

// app/posts/page.js - Server Component
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    cache: 'no-store', // Dynamic data
  })
  return res.json()
}

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

  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  )
}

Client Components

'use client'

import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  )
}

Composition Pattern

// app/page.js - Server Component
import ClientComponent from './ClientComponent'

async function getData() {
  const data = await fetch('...')
  return data.json()
}

export default async function Page() {
  const data = await getData()

  return (
    <div>
      <h1>Server-rendered content</h1>
      <ClientComponent initialData={data} />
    </div>
  )
}

Data Fetching Strategies

Static Data (Default)

// Cached by default
async function getStaticData() {
  const res = await fetch('https://api.example.com/data')
  return res.json()
}

Dynamic Data

// Opt out of caching
async function getDynamicData() {
  const res = await fetch('https://api.example.com/data', {
    cache: 'no-store'
  })
  return res.json()
}

Revalidated Data

// Revalidate every 60 seconds
async function getRevalidatedData() {
  const res = await fetch('https://api.example.com/data', {
    next: { revalidate: 60 }
  })
  return res.json()
}

Parallel Data Fetching

export default async function Page() {
  // Fetch in parallel
  const [posts, users] = await Promise.all([
    getPosts(),
    getUsers()
  ])

  return (
    <div>
      <Posts data={posts} />
      <Users data={users} />
    </div>
  )
}

Sequential Data Fetching

export default async function Page() {
  const user = await getUser()
  const posts = await getUserPosts(user.id) // Waits for user

  return <UserPosts user={user} posts={posts} />
}

Route Handlers

Basic API Route

// app/api/posts/route.js
export async function GET(request) {
  const posts = await getPosts()
  return Response.json(posts)
}

export async function POST(request) {
  const body = await request.json()
  const post = await createPost(body)
  return Response.json(post, { status: 201 })
}

Dynamic Route Handlers

// app/api/posts/[id]/route.js
export async function GET(request, { params }) {
  const post = await getPost(params.id)

  if (!post) {
    return Response.json({ error: 'Not found' }, { status: 404 })
  }

  return Response.json(post)
}

export async function PATCH(request, { params }) {
  const body = await request.json()
  const post = await updatePost(params.id, body)
  return Response.json(post)
}

export async function DELETE(request, { params }) {
  await deletePost(params.id)
  return new Response(null, { status: 204 })
}

Middleware Integration

// app/api/protected/route.js
import { auth } from '@/lib/auth'

export async function GET(request) {
  const session = await auth(request)

  if (!session) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const data = await getProtectedData(session.userId)
  return Response.json(data)
}

Advanced Patterns

Loading States

// app/dashboard/loading.js
export default function Loading() {
  return <div className="spinner">Loading...</div>
}

Error Handling

// app/dashboard/error.js
'use client'

export default function Error({ error, reset }) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Not Found Pages

// app/blog/[slug]/not-found.js
export default function NotFound() {
  return (
    <div>
      <h2>Post Not Found</h2>
      <p>Could not find the requested post.</p>
    </div>
  )
}

// Trigger not-found
import { notFound } from 'next/navigation'

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

  if (!post) {
    notFound()
  }

  return <Post data={post} />
}

Streaming with Suspense

import { Suspense } from 'react'

async function SlowComponent() {
  await new Promise(resolve => setTimeout(resolve, 3000))
  return <div>Slow content loaded!</div>
}

export default function Page() {
  return (
    <div>
      <h1>Fast content</h1>
      <Suspense fallback={<div>Loading slow content...</div>}>
        <SlowComponent />
      </Suspense>
    </div>
  )
}

Route Groups

app/
├── (marketing)/
│   ├── layout.js          # Marketing layout
│   ├── page.js            # / route
│   └── about/
│       └── page.js        # /about route
└── (shop)/
    ├── layout.js          # Shop layout
    ├── products/
    │   └── page.js        # /products route
    └── cart/
        └── page.js        # /cart route

Parallel Routes

app/
└── dashboard/
    ├── @analytics/
    │   └── page.js
    ├── @team/
    │   └── page.js
    └── layout.js

// app/dashboard/layout.js
export default function Layout({ children, analytics, team }) {
  return (
    <div>
      {children}
      <div className="grid grid-cols-2">
        {analytics}
        {team}
      </div>
    </div>
  )
}

Intercepting Routes

app/
└── photos/
    ├── [id]/
    │   └── page.js        # /photos/123
    └── (..)photos/
        └── [id]/
            └── page.js    # Intercepts /photos/123 when navigating from same level

Best Practices

1. Server Components by Default

Use server components unless you need interactivity, browser APIs, or state.

2. Fetch Data Where You Need It

Don't prop drill - fetch data in the component that needs it.

3. Use Streaming for Better UX

Wrap slow components in Suspense to stream content progressively.

4. Optimize Images

import Image from 'next/image'

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

5. Implement Proper Error Boundaries

Create error.js files at appropriate levels in your route hierarchy.

6. Use Metadata API

export const metadata = {
  title: 'My Page',
  description: 'Page description',
  openGraph: {
    title: 'My Page',
    description: 'Page description',
    images: ['/og-image.jpg'],
  },
}

Performance Optimization

Code Splitting

import dynamic from 'next/dynamic'

const DynamicComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <p>Loading...</p>,
  ssr: false, // Disable SSR if needed
})

Font Optimization

import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  )
}

Route Prefetching

Next.js automatically prefetches routes in the viewport using <Link>.

Conclusion

The Next.js App Router provides a powerful foundation for building modern web applications. By understanding these patterns and best practices, you can create fast, scalable, and maintainable applications.

Key Takeaways

Server Components are the default and provide better performance
Use Client Components only when needed for interactivity
Leverage streaming and Suspense for better UX
Fetch data where you need it, not at the top level
Use proper error handling and loading states
Optimize images, fonts, and code splitting

Next Steps

Explore the Next.js documentation
Build a project using the App Router
Experiment with advanced patterns like parallel routes
Learn about deployment optimization

Related Guides:

Originally published at https://iloveblogs.blog

Next.js 15 vs Next.js 14: Performance Comparison and Migration Guide 2026

Mahdi BEN RHOUMA — Sun, 03 May 2026 10:11:46 +0000

Next.js 15 dropped with some game-changing performance improvements and new features. But should you upgrade from Next.js 14? Let's compare them head-to-head with real benchmarks and migration guidance.

Quick Comparison Table

Feature	Next.js 14	Next.js 15
React Version	React 18	React 19 RC
Turbopack	Dev only (beta)	Dev + Build (stable)
Build Speed	Baseline	2-3x faster
Bundle Size	Baseline	10-15% smaller
Server Actions	Stable	Enhanced with validation
Partial Prerendering	Experimental	Stable
Caching	Aggressive default	Opt-in (breaking change)
Async Request APIs	Sync	Async (breaking change)
Hydration Errors	Basic messages	Detailed with source
Image Optimization	Good	Better (AVIF support)
Minimum Node.js	18.17	18.18

Performance Benchmarks

Build Time Comparison

I tested both versions on a medium-sized Next.js app (50 pages, 200 components):

Next.js 14:

✓ Compiled successfully in 45.2s
✓ Linting and checking validity of types...
✓ Creating an optimized production build...
✓ Collecting page data...
✓ Generating static pages (50/50)
✓ Finalizing page optimization...

Total build time: 2m 15s

Next.js 15 (with Turbopack):

✓ Compiled successfully in 18.7s
✓ Linting and checking validity of types...
✓ Creating an optimized production build...
✓ Collecting page data...
✓ Generating static pages (50/50)
✓ Finalizing page optimization...

Total build time: 52s

Result: 2.6x faster builds 🚀

Bundle Size Comparison

Same app, production build:

Next.js 14:

First Load JS: 89.2 kB
Total bundle size: 1.2 MB
Largest chunk: 245 kB

Next.js 15:

First Load JS: 76.8 kB (14% smaller)
Total bundle size: 1.05 MB (12.5% smaller)
Largest chunk: 218 kB (11% smaller)

Result: 12-14% smaller bundles 📦

Runtime Performance

Lighthouse scores on the same production app:

Metric	Next.js 14	Next.js 15	Improvement
Performance	92	96	+4 points
FCP	1.2s	1.0s	16% faster
LCP	2.1s	1.8s	14% faster
TBT	180ms	120ms	33% faster
CLS	0.05	0.03	40% better
TTI	3.2s	2.7s	15% faster

Major New Features in Next.js 15

1. Turbopack Stable for Production

Next.js 15 makes Turbopack stable for production builds:

# Enable Turbopack in next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbo: {
      // Turbopack-specific options
    }
  }
}

module.exports = nextConfig

Benefits:

2-3x faster builds
5-10x faster HMR (Hot Module Replacement)
Lower memory usage
Better error messages

2. Partial Prerendering (PPR) Stable

PPR combines static and dynamic rendering in the same page:

// app/product/[id]/page.tsx
import { Suspense } from 'react';

export default async function ProductPage({ params }) {
  // This part is static (prerendered)
  const product = await getProduct(params.id);

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>

      {/* This part is dynamic (rendered on request) */}
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={params.id} />
      </Suspense>
    </div>
  );
}

Benefits:

Best of both worlds: static speed + dynamic data
Automatic optimization
Better user experience

3. Enhanced Server Actions

Server Actions now have built-in validation and better error handling:

'use server'

import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8)
});

export async function createUser(formData: FormData) {
  // Automatic validation
  const validatedFields = schema.safeParse({
    email: formData.get('email'),
    password: formData.get('password')
  });

  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
    };
  }

  // Create user...
}

4. Better Hydration Error Messages

Next.js 15 shows exactly where hydration mismatches occur:

Next.js 14:

Error: Hydration failed because the initial UI does not match what was rendered on the server.

Next.js 15:

Error: Hydration failed in <div> at line 42 in app/page.tsx

Expected server HTML:
  <div class="container">Hello</div>

Received client HTML:
  <div class="container">Hi</div>

Likely caused by:
  - Using Date.now() or Math.random()
  - Browser extensions modifying HTML
  - Conditional rendering based on window

5. Async Request APIs (Breaking Change)

Request APIs are now async in Next.js 15:

Next.js 14:

import { cookies, headers } from 'next/headers';

export default function Page() {
  const cookieStore = cookies();
  const headersList = headers();

  const theme = cookieStore.get('theme');
  const userAgent = headersList.get('user-agent');
}

Next.js 15:

import { cookies, headers } from 'next/headers';

export default async function Page() {
  const cookieStore = await cookies();
  const headersList = await headers();

  const theme = cookieStore.get('theme');
  const userAgent = headersList.get('user-agent');
}

6. Opt-in Caching (Breaking Change)

Caching is now opt-in instead of opt-out:

Next.js 14 (aggressive caching by default):

// Cached by default
const data = await fetch('https://api.example.com/data');

Next.js 15 (opt-in caching):

// Not cached by default
const data = await fetch('https://api.example.com/data');

// Explicitly cache
const cachedData = await fetch('https://api.example.com/data', {
  cache: 'force-cache'
});

// Revalidate every 60 seconds
const revalidatedData = await fetch('https://api.example.com/data', {
  next: { revalidate: 60 }
});

Breaking Changes and Migration

1. Update Dependencies

npm install next@15 react@19 react-dom@19
# or
yarn add next@15 react@19 react-dom@19
# or
pnpm add next@15 react@19 react-dom@19

2. Make Request APIs Async

Use codemod to automatically update:

npx @next/codemod@latest next-async-request-api .

Or manually update:

// Before
const cookieStore = cookies();

// After
const cookieStore = await cookies();

3. Update Caching Strategy

Review all fetch calls and add explicit caching:

// Before (Next.js 14 - cached by default)
const posts = await fetch('https://api.example.com/posts');

// After (Next.js 15 - opt-in caching)
const posts = await fetch('https://api.example.com/posts', {
  cache: 'force-cache', // or 'no-store' for dynamic data
  next: { revalidate: 3600 } // revalidate every hour
});

4. Update Minimum Node.js Version

Ensure you're running Node.js 18.18 or higher:

node --version
# Should be >= 18.18.0

5. Test Thoroughly

Run your test suite and check for:

Hydration errors
Caching behavior changes
Server Action validation
Build errors

Should You Upgrade?

✅ Upgrade to Next.js 15 if:

You want faster builds
- 2-3x faster with Turbopack
- Especially beneficial for large apps
You need better performance
- 12-15% smaller bundles
- Faster Core Web Vitals
You're starting a new project
- Get the latest features
- Future-proof your app
You have good test coverage
- Breaking changes are manageable
- Codemods help with migration
You want better DX
- Better error messages
- Improved debugging

⏸️ Wait on Next.js 14 if:

You have a large production app
- Test thoroughly first
- Breaking changes need careful review
You rely heavily on caching
- Caching behavior changed significantly
- Need to review all fetch calls
You use third-party libraries
- Some may not support React 19 yet
- Check compatibility first
You have tight deadlines
- Migration takes time
- Stick with stable version
You're on Node.js < 18.18
- Upgrade Node.js first
- Then upgrade Next.js

Migration Checklist

- [ ] Update Node.js to 18.18+
- [ ] Update dependencies (next@15, react@19, react-dom@19)
- [ ] Run async request API codemod
- [ ] Review and update all fetch calls (caching)
- [ ] Update any custom server code
- [ ] Test all pages and API routes
- [ ] Check for hydration errors
- [ ] Review Server Actions
- [ ] Update CI/CD pipeline
- [ ] Test in staging environment
- [ ] Monitor performance after deployment
- [ ] Update documentation

Real-World Migration Example

Here's how I migrated a production app:

Step 1: Update Dependencies

npm install next@15 react@19 react-dom@19

Step 2: Run Codemods

npx @next/codemod@latest next-async-request-api .

Step 3: Update Fetch Calls

// Before
async function getPosts() {
  const res = await fetch('https://api.example.com/posts');
  return res.json();
}

// After
async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 } // Cache for 1 hour
  });
  return res.json();
}

Step 4: Test Everything

npm run build
npm run start
# Test all critical paths

Step 5: Deploy to Staging

git checkout -b upgrade-nextjs-15
git add .
git commit -m "Upgrade to Next.js 15"
git push origin upgrade-nextjs-15
# Deploy to staging

Step 6: Monitor and Deploy

Monitor staging for 24-48 hours
Check error logs
Review performance metrics
Deploy to production

Total migration time: 4 hours

Performance Tips for Next.js 15

1. Use Turbopack

# Development
npm run dev --turbo

# Production build
npm run build --turbo

2. Leverage Partial Prerendering

export const experimental_ppr = true;

export default async function Page() {
  return (
    <div>
      <StaticContent />
      <Suspense fallback={<Loading />}>
        <DynamicContent />
      </Suspense>
    </div>
  );
}

3. Optimize Caching

// Static data (cache indefinitely)
const staticData = await fetch('https://api.example.com/config', {
  cache: 'force-cache'
});

// Dynamic data (no cache)
const userData = await fetch('https://api.example.com/user', {
  cache: 'no-store'
});

// Revalidated data (cache with TTL)
const posts = await fetch('https://api.example.com/posts', {
  next: { revalidate: 60 } // Revalidate every 60 seconds
});

4. Use Server Actions

'use server'

export async function createPost(formData: FormData) {
  const title = formData.get('title');
  const content = formData.get('content');

  // Direct database access (no API route needed)
  await db.post.create({
    data: { title, content }
  });

  revalidatePath('/posts');
}

Conclusion

Next.js 15 is a significant upgrade with real performance improvements:

2-3x faster builds with Turbopack
12-15% smaller bundles
Better Core Web Vitals
Improved developer experience

The breaking changes are manageable with codemods and careful testing. For new projects, use Next.js 15. For existing apps, plan a migration when you have time to test thoroughly.

FAQ

Is Next.js 15 production-ready?

Yes, Next.js 15 is stable and production-ready. Vercel uses it for their own applications.

Will my Next.js 14 app break if I upgrade?

Not necessarily, but there are breaking changes. Use codemods and test thoroughly before deploying.

How long does migration take?

For a small app: 1-2 hours. For a medium app: 4-8 hours. For a large app: 1-2 days.

Can I use Next.js 15 with React 18?

No, Next.js 15 requires React 19. They're designed to work together.

Is Turbopack faster than Webpack?

Yes, significantly. Turbopack is 2-3x faster for builds and 5-10x faster for HMR in development.

Should I upgrade my production app immediately?

Test in staging first. If everything works well, upgrade. Otherwise, wait for your next sprint.

Originally published at https://iloveblogs.blog

Next.js 15 Caching Explained: Why Your Data Keeps Showing as Stale

Mahdi BEN RHOUMA — Sat, 02 May 2026 10:04:02 +0000

Next.js 15 Caching Explained: Why Your Data Keeps Showing as Stale

If you upgraded from Next.js 14 to 15 and your pages suddenly stopped refreshing — or started hitting your database on every request — you are not alone. The caching model changed fundamentally. This is the guide I wish existed when I spent a day debugging it.

What Changed in Next.js 15

In Next.js 14, fetch() inside Server Components was cached by default:

// Next.js 14: this was CACHED (force-cache)
const data = await fetch('https://api.example.com/posts');

In Next.js 15, the default flipped:

// Next.js 15: this is NOT cached (no-store)
const data = await fetch('https://api.example.com/posts');

This single change affects every Server Component in your app that uses fetch(). If you were relying on the default cache behavior, your routes are now fully dynamic — which means a database call on every render.

The Next.js team made this change because force-cache silently caused stale data bugs that were hard to debug. The new default is safer but more explicit.

The Four Caching Layers You Need to Understand

Next.js 15 has four distinct caching mechanisms. Understanding which one applies to your situation is everything.

1. Request Memoization (per-render)

The same fetch() URL called multiple times in a single render tree is deduplicated automatically. This is not persistent — it resets on every request.

// Both calls return the same data, only one HTTP request is made
async function UserName() {
  const user = await fetch('/api/user/123');
  return user.name;
}

async function UserAvatar() {
  const user = await fetch('/api/user/123'); // deduplicated
  return <img src={user.avatar} />;
}

You cannot configure this. It is always on, always per-request.

2. Data Cache (persistent, fetch-level)

This is what changed in Next.js 15. Control it with the cache option on fetch():

// Never cache — always fetch live data
const res = await fetch('/api/posts', { cache: 'no-store' });

// Cache indefinitely until manually revalidated
const res = await fetch('/api/posts', { cache: 'force-cache' });

// Cache for 60 seconds, then revalidate in the background
const res = await fetch('/api/posts', { next: { revalidate: 60 } });

// Tag this cache entry so you can invalidate it by name
const res = await fetch('/api/posts', { next: { tags: ['posts'] } });

3. Full Route Cache (build-time static rendering)

If Next.js can determine at build time that a route has no dynamic data, it renders it once and serves the HTML statically. This is ISR (Incremental Static Regeneration) in the App Router.

Control it at the route level:

// page.js

// Revalidate this entire route every 5 minutes
export const revalidate = 300;

// Never cache this route (always server-render)
export const dynamic = 'force-dynamic';

// Always use cached version (opt in to static)
export const dynamic = 'force-static';

4. Router Cache (client-side, per-session)

Next.js caches visited routes in the browser for the duration of the session. This is why navigating back to a page feels instant — but also why a user might see stale data after you push an update.

This cache has a 30-second TTL for dynamic routes and 5 minutes for static routes. You can invalidate it with router.refresh() from a Client Component.

The Real Problem: Supabase and Database Queries

Here is where most indie hackers get burned. When you use Supabase (or any database client), you are not using fetch(). You are calling the Supabase SDK directly — which means none of the fetch() caching rules apply at all.

// This is NOT cached by Next.js — it runs on every render
const { data } = await supabase.from('posts').select('*');

If you want to cache a Supabase query, use unstable_cache:

import { unstable_cache } from 'next/cache';
import { createClient } from '@/lib/supabase/server';

const getCachedPosts = unstable_cache(
  async () => {
    const supabase = createClient();
    const { data } = await supabase.from('posts').select('*');
    return data;
  },
  ['all-posts'],          // cache key
  {
    revalidate: 300,      // revalidate every 5 minutes
    tags: ['posts'],      // tag for manual invalidation
  }
);

export default async function PostsPage() {
  const posts = await getCachedPosts();
  return <PostList posts={posts} />;
}

The first argument is the function. The second is the cache key array (like React Query's queryKey). The third is the options object.

Invalidating Cache After Mutations

The most important pattern: when a user creates, updates, or deletes data, you need to invalidate the relevant cache so the next page load sees fresh data.

// app/actions.ts
'use server';

import { revalidatePath, revalidateTag } from 'next/cache';
import { createClient } from '@/lib/supabase/server';

export async function createPost(formData: FormData) {
  const supabase = createClient();

  const { error } = await supabase.from('posts').insert({
    title: formData.get('title'),
    content: formData.get('content'),
  });

  if (error) throw new Error(error.message);

  // Invalidate the posts tag — all unstable_cache entries tagged 'posts' are cleared
  revalidateTag('posts');

  // Also invalidate the posts listing page URL
  revalidatePath('/posts');
}

Use revalidateTag when the same data appears on multiple pages. Use revalidatePath when you know exactly which URL to clear.

Debugging Cache Issues

When you are not sure what is being cached, add this to any Server Component:

export const dynamic = 'force-dynamic';

This forces the route to always server-render with no caching. If your data problem goes away, it was a cache issue. If not, your problem is elsewhere (wrong query, wrong env variable, etc.).

To see what Next.js is caching during development, run:

next build && next start

The build output shows which routes are static (○), dynamic (λ), or ISR (~). Development mode (next dev) always runs dynamically — you will not see caching behavior in dev.

Quick Reference

Situation	Solution
Page shows stale data after DB update	Call `revalidateTag()` or `revalidatePath()` in your Server Action
Supabase query not caching	Wrap with `unstable_cache()`
Route hits DB on every request	Add `export const revalidate = 60` to the page
Need real-time live data	Use `export const dynamic = 'force-dynamic'`
Data cached too long	Lower `revalidate` value or add cache tags
After upgrading from Next.js 14	Audit all `fetch()` calls — add explicit `cache` options

The Pattern That Works in Production

For a typical Next.js 15 + Supabase app:

// lib/queries.ts
import { unstable_cache } from 'next/cache';
import { createClient } from '@/lib/supabase/server';

export const getPosts = unstable_cache(
  async (limit = 10) => {
    const supabase = createClient();
    const { data, error } = await supabase
      .from('posts')
      .select('id, title, slug, excerpt, created_at')
      .order('created_at', { ascending: false })
      .limit(limit);

    if (error) throw error;
    return data ?? [];
  },
  ['posts-list'],
  { revalidate: 60, tags: ['posts'] }
);

export const getPostBySlug = unstable_cache(
  async (slug: string) => {
    const supabase = createClient();
    const { data, error } = await supabase
      .from('posts')
      .select('*')
      .eq('slug', slug)
      .single();

    if (error) return null;
    return data;
  },
  ['post-by-slug'],
  { revalidate: 300, tags: ['posts'] }
);

Then in your Server Actions, always call revalidateTag('posts') after any write. One tag clears all related cached queries at once.

This pattern gives you fast page loads (cached data), fresh data after mutations (tag invalidation), and automatic background refresh every 60–300 seconds as a safety net.

Originally published at https://iloveblogs.blog

Mindfulness for Stress Management: What Works

Mahdi BEN RHOUMA — Fri, 01 May 2026 10:27:13 +0000

Mindfulness for Stress Management: What Works

Mindfulness has been packaged and sold as everything from a productivity hack to spiritual enlightenment. Here's what the science actually says about using mindfulness for stress management—and how to make it work in real life.

Related reading: Explore our guides on deep work and focus and digital detox retreats for complementary wellness strategies.

Separating Science from Marketing

What Mindfulness Actually Is

Clinical definition: The practice of purposeful, non-judgmental awareness of the present moment
Not: A cure-all, spiritual practice, or way to eliminate all negative emotions
Core components: Attention regulation, present-moment awareness, acceptance of experience

The Research Reality

What studies show:

8-week mindfulness programs reduce anxiety by 20-30% on average
Stress hormone (cortisol) levels decrease with regular practice
Brain imaging shows changes in areas related to emotional regulation
Effects are modest but consistent across diverse populations

What studies don't show:

Mindfulness as superior to other evidence-based treatments
Universal effectiveness for all types of stress or mental health conditions
Immediate or dramatic results from short-term practice

Understanding Stress: The Foundation

The Stress Response System

Acute stress: Short-term activation helpful for dealing with immediate challenges
Chronic stress: Prolonged activation that becomes harmful to physical and mental health
Stress perception: How we interpret and respond to potentially stressful situations

Where Mindfulness Fits

Primary intervention: Changing our relationship to stressful thoughts and sensations
Secondary benefits: Improved emotional regulation and reduced reactivity
Tertiary effects: Better sleep, relationships, and overall well-being

Key insight: Mindfulness doesn't eliminate stress—it changes how we experience and respond to it.

Evidence-Based Mindfulness Approaches

Mindfulness-Based Stress Reduction (MBSR)

Structure: 8-week program with weekly 2.5-hour sessions
Components: Body scan, sitting meditation, mindful yoga, informal practices
Homework: 45 minutes daily practice with guided audio
Evidence: Most researched mindfulness intervention with consistent positive results

Mindfulness-Based Cognitive Therapy (MBCT)

Target: Preventing depression relapse and managing anxiety
Approach: Combines mindfulness with cognitive therapy techniques
Focus: Recognizing and changing patterns of negative thinking
Evidence: Reduces depression relapse rates by 40-50%

Acceptance and Commitment Therapy (ACT)

Philosophy: Psychological flexibility through acceptance and value-based action
Mindfulness component: Defusion from thoughts and present-moment awareness
Goal: Living according to values despite difficult thoughts and emotions
Evidence: Effective for anxiety, depression, chronic pain, and workplace stress

Practical Mindfulness Techniques

Foundational Practices

Breath awareness:

Focus attention on natural breathing
Notice when mind wanders, gently return to breath
Start with 5-10 minutes, gradually increase
Can be done anywhere, anytime

Body scan:

Systematic attention to different body parts
Notice sensations without trying to change them
Helps develop body awareness and relaxation
Particularly effective for physical tension

Mindful observation:

Choose an object (candle, plant, artwork)
Observe with full attention for 5-10 minutes
Notice details, colors, textures, changes
Trains sustained attention and present-moment awareness

Informal Mindfulness

Mindful daily activities:

Eating: Full attention to taste, texture, smell
Walking: Awareness of movement and surroundings
Listening: Complete focus on sounds without planning responses
Waiting: Using delays as opportunities for brief mindfulness

The STOP technique:

Stop what you're doing
Take a breath
Observe thoughts, feelings, sensations
Proceed with awareness

Advanced Practices

Loving-kindness meditation:

Cultivating compassion for self and others
Reduces self-criticism and interpersonal stress
Particularly helpful for relationship difficulties
Starts with self, extends to others gradually

Open monitoring:

Awareness of whatever arises in consciousness
No specific focus object
Develops meta-cognitive awareness
Helps with rumination and worry

Common Obstacles and Solutions

"I Can't Stop Thinking"

The misconception: Mindfulness means having no thoughts
The reality: Noticing thoughts without getting caught up in them
The practice: Observing thoughts like clouds passing in the sky
The solution: Expect thoughts, practice returning attention gently

"I Don't Have Time"

The challenge: Busy schedules and competing priorities
The reframe: Mindfulness as efficiency tool, not time burden
Micro-practices: 30-second breathing spaces throughout the day
Integration: Mindful versions of existing activities

"It's Not Working"

Unrealistic expectations: Immediate calm or elimination of stress
Realistic timeline: Noticeable changes after 2-4 weeks of regular practice
Subtle benefits: Increased awareness often comes before emotional changes
Measurement: Track stress levels, sleep quality, reactivity over time

Physical Discomfort

Common issues: Restlessness, fidgeting, physical pain during sitting
Adaptations: Walking meditation, chair practice, shorter sessions
Acceptance: Discomfort as part of the practice, not failure
Modifications: Adjust posture, use cushions, try different positions

Integrating Mindfulness with Other Stress Management

Complementary Approaches

Exercise: Physical activity enhances mindfulness benefits
Sleep hygiene: Mindfulness improves sleep quality and duration
Social support: Mindful communication strengthens relationships
Time management: Mindful prioritization reduces overwhelm

Professional Treatment

When to seek help:

Severe anxiety or depression
Trauma-related stress
Substance use concerns
Thoughts of self-harm

Mindfulness as adjunct: Enhances therapy but doesn't replace professional treatment
Integrated approaches: Many therapists incorporate mindfulness techniques

Workplace Mindfulness

Practical Applications

Meeting mindfulness: Brief centering before important meetings
Email awareness: Mindful checking rather than compulsive monitoring
Transition practices: Brief mindfulness between tasks or meetings
Stress response: Using mindfulness during difficult conversations

Organizational Benefits

Reduced burnout: Lower emotional exhaustion and cynicism
Improved focus: Better attention and decision-making
Enhanced creativity: Increased openness to new ideas
Better relationships: More empathetic and effective communication

Implementation Strategies

Start small: Brief practices rather than lengthy programs
Leadership modeling: Managers demonstrating mindful practices
Environmental support: Quiet spaces and time for practice
Training programs: Structured learning with ongoing support

Technology and Mindfulness

Helpful Apps and Tools

Guided meditations: Headspace, Calm, Insight Timer, Ten Percent Happier
Tracking features: Progress monitoring and streak maintenance
Variety: Different teachers, lengths, and focus areas
Accessibility: Practice anywhere with smartphone

Potential Pitfalls

Over-reliance: Apps as crutch rather than developing independent practice
Gamification: Focus on streaks rather than quality of attention
Distraction: Notifications and features that interrupt practice
Commercialization: Marketing that overpromises results

Balanced Approach

Apps as training wheels: Use initially, gradually develop independent practice
Quality over quantity: Focus on attention quality rather than time logged
Offline practice: Regular sessions without technology
Critical evaluation: Choose evidence-based content over trendy features

Mindfulness for Specific Stressors

Work Stress

Deadline pressure: Brief breathing practices during intense periods
Difficult colleagues: Mindful communication and emotional regulation
Perfectionism: Acceptance of "good enough" and learning from mistakes
Burnout prevention: Regular check-ins with energy and motivation levels

Relationship Stress

Conflict resolution: Mindful listening and response rather than reaction
Communication: Present-moment awareness during conversations
Boundaries: Mindful assessment of relationship dynamics
Empathy: Understanding others' perspectives without losing yourself

Health Anxiety

Body awareness: Distinguishing between normal sensations and anxiety
Catastrophic thinking: Observing worry thoughts without believing them
Medical appointments: Mindfulness during waiting and procedures
Chronic conditions: Acceptance and adaptation rather than resistance

Financial Stress

Money worries: Observing anxiety without getting overwhelmed
Spending decisions: Mindful consumption and impulse control
Future planning: Present-moment awareness while planning ahead
Scarcity mindset: Noticing and questioning limiting beliefs about money

Building a Sustainable Practice

Starting Guidelines

Consistency over duration: 10 minutes daily better than 60 minutes weekly
Same time and place: Habit formation through routine
Realistic expectations: Progress measured in weeks and months, not days
Gentle persistence: Returning to practice after breaks without self-judgment

Maintaining Motivation

Track benefits: Notice improvements in sleep, mood, relationships
Community support: Practice groups or online communities
Variety: Different techniques to maintain interest
Integration: Connecting practice to personal values and goals

Long-term Development

Deepening practice: Longer sessions and retreat experiences
Teaching others: Sharing knowledge to reinforce learning
Continued education: Books, courses, and workshops
Lifestyle integration: Mindfulness as way of being, not just formal practice

The Neuroscience Behind the Benefits

Brain Changes from Practice

Prefrontal cortex: Strengthened areas responsible for executive function
Amygdala: Reduced reactivity in brain's alarm system
Insula: Enhanced body awareness and emotional intelligence
Default mode network: Less rumination and self-referential thinking

Stress Response Improvements

HPA axis regulation: Better cortisol patterns and stress hormone balance
Inflammatory markers: Reduced chronic inflammation associated with stress
Immune function: Enhanced immune response and faster recovery
Cardiovascular health: Lower blood pressure and improved heart rate variability

Cultural Considerations and Accessibility

Adapting Practices

Cultural sensitivity: Respecting different spiritual and religious backgrounds
Language barriers: Practices available in multiple languages
Economic accessibility: Free resources and community programs
Physical limitations: Adaptations for different abilities and mobility

Avoiding Cultural Appropriation

Secular approaches: Evidence-based practices without religious elements
Respectful acknowledgment: Recognizing Buddhist origins without claiming expertise
Inclusive language: Avoiding terms that exclude or alienate
Diverse teachers: Learning from instructors with varied backgrounds

The Future of Mindfulness Research

Emerging Areas

Personalized approaches: Tailoring practices to individual differences
Mechanism studies: Understanding exactly how mindfulness creates benefits
Optimal dosing: Determining ideal frequency and duration for different goals
Technology integration: VR, biofeedback, and AI-enhanced practice

Remaining Questions

Individual differences: Who benefits most from which approaches
Long-term effects: Sustained benefits and potential risks
Comparison studies: Mindfulness versus other stress management techniques
Implementation: Best practices for teaching and disseminating mindfulness

Getting Started: A Practical Plan

Week 1-2: Foundation Building

Choose one formal practice (breath awareness or body scan)
Practice 5-10 minutes daily at consistent time
Begin informal mindfulness with one daily activity
Notice without judging your experience

Week 3-4: Expanding Awareness

Increase formal practice to 10-15 minutes
Add mindful walking or movement
Practice STOP technique during stressful moments
Track stress levels and sleep quality

Month 2-3: Deepening Practice

Extend sessions to 15-20 minutes
Explore different techniques (loving-kindness, open monitoring)
Join practice group or online community
Apply mindfulness to specific stressors

Ongoing: Integration and Growth

Maintain consistent daily practice
Attend workshops or retreats
Share practice with others
Continue learning and adapting approaches

The Bottom Line

Mindfulness is not a magic bullet for stress, but it is a scientifically-supported tool that can significantly improve how we relate to stressful experiences.

The benefits are real but require consistent practice and realistic expectations. Like physical fitness, mindfulness develops gradually through regular training.

The goal is not to eliminate stress or negative emotions, but to develop a healthier, more skillful relationship with the inevitable challenges of life.

Start where you are, use what works, and be patient with the process. The capacity for mindful awareness is already within you—practice simply helps you access and strengthen it.

Further Reading:

Mindfulness-Based Stress Reduction (MBSR) - Official program from UMass Medical School
NIH Research on Meditation - Evidence-based information from the National Institutes of Health
Learn more about our editorial team and how we research our wellness content.

Originally published at https://iloveblogs.blog

Micro-Frontends: The Complete Architecture Guide for 2026

Mahdi BEN RHOUMA — Thu, 30 Apr 2026 10:59:47 +0000

Micro-Frontends: The Complete Architecture Guide for 2026

Micro-frontends promise to solve the scaling challenges of large frontend applications. After implementing dozens of micro-frontend architectures, here's what actually works, what doesn't, and how to build them right.

Related reading: Check out our guides on React performance optimization and design systems at scale for more architecture insights.

What Are Micro-Frontends?

The Core Concept

Micro-frontends extend the microservices concept to frontend development. Instead of a monolithic frontend application, you build multiple smaller, independent applications that work together as a cohesive user experience.

Key principles:

Technology agnostic: Each micro-frontend can use different frameworks
Independent deployment: Deploy parts of your app independently
Team autonomy: Different teams own different parts of the application
Isolated development: Develop and test in isolation

When Micro-Frontends Make Sense

Large organizations with multiple teams working on the same product
Legacy modernization where you need to gradually migrate old systems
Different technology requirements for different parts of your application
Independent release cycles for different features

When to Avoid Micro-Frontends

Small teams (< 10 developers) - the overhead isn't worth it
Simple applications - monoliths are often better for straightforward apps
Tight coupling requirements - when features need deep integration
Performance-critical applications - the overhead can impact performance

Micro-Frontend Implementation Strategies

1. Module Federation (Webpack 5)

Best for: React/Vue/Angular applications with modern build tools

// Host application webpack config
const ModuleFederationPlugin = require('@module-federation/webpack');

module.exports = {
  mode: 'development',
  devServer: {
    port: 3000,
  },
  plugins: [
    new ModuleFederationPlugin({
      name: 'host',
      remotes: {
        mfShell: 'shell@http://localhost:3001/remoteEntry.js',
        mfProducts: 'products@http://localhost:3002/remoteEntry.js',
        mfCheckout: 'checkout@http://localhost:3003/remoteEntry.js',
      },
    }),
  ],
};

// Remote application webpack config
module.exports = {
  mode: 'development',
  devServer: {
    port: 3001,
  },
  plugins: [
    new ModuleFederationPlugin({
      name: 'shell',
      filename: 'remoteEntry.js',
      exposes: {
        './Header': './src/components/Header',
        './Navigation': './src/components/Navigation',
        './Footer': './src/components/Footer',
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
  ],
};

Using remote components:

// Host application
import React, { Suspense } from 'react';

const Header = React.lazy(() => import('mfShell/Header'));
const ProductList = React.lazy(() => import('mfProducts/ProductList'));
const Checkout = React.lazy(() => import('mfCheckout/CheckoutForm'));

function App() {
  return (
    <div>
      <Suspense fallback={<div>Loading header...</div>}>
        <Header />
      </Suspense>

      <main>
        <Suspense fallback={<div>Loading products...</div>}>
          <ProductList />
        </Suspense>

        <Suspense fallback={<div>Loading checkout...</div>}>
          <Checkout />
        </Suspense>
      </main>
    </div>
  );
}

2. Single-SPA Framework

Best for: Multi-framework applications or gradual migration

// Root config
import { registerApplication, start } from 'single-spa';

// Register micro-frontends
registerApplication({
  name: 'navbar',
  app: () => import('./navbar/navbar.app.js'),
  activeWhen: () => true, // Always active
});

registerApplication({
  name: 'products',
  app: () => import('./products/products.app.js'),
  activeWhen: location => location.pathname.startsWith('/products'),
});

registerApplication({
  name: 'checkout',
  app: () => import('./checkout/checkout.app.js'),
  activeWhen: '/checkout',
});

start();

// Individual micro-frontend (React)
import React from 'react';
import ReactDOM from 'react-dom';
import singleSpaReact from 'single-spa-react';
import ProductApp from './ProductApp';

const lifecycles = singleSpaReact({
  React,
  ReactDOM,
  rootComponent: ProductApp,
  errorBoundary(err, info, props) {
    return <div>Error in products app</div>;
  },
});

export const { bootstrap, mount, unmount } = lifecycles;

// Individual micro-frontend (Vue)
import Vue from 'vue';
import singleSpaVue from 'single-spa-vue';
import CheckoutApp from './CheckoutApp.vue';

const vueLifecycles = singleSpaVue({
  Vue,
  appOptions: {
    render: h => h(CheckoutApp),
  },
});

export const { bootstrap, mount, unmount } = vueLifecycles;

3. Web Components Approach

Best for: Framework-agnostic solutions with maximum isolation

// Micro-frontend as Web Component
class ProductCatalog extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    this.render();
    this.loadProducts();
  }

  render() {
    this.shadowRoot.innerHTML = `
      <style>
        :host {
          display: block;
          padding: 20px;
        }
        .product-grid {
          display: grid;
          grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
          gap: 20px;
        }
      </style>
      <div class="product-catalog">
        <h2>Products</h2>
        <div class="product-grid" id="products"></div>
      </div>
    `;
  }

  async loadProducts() {
    const response = await fetch('/api/products');
    const products = await response.json();
    this.renderProducts(products);
  }

  renderProducts(products) {
    const grid = this.shadowRoot.getElementById('products');
    grid.innerHTML = products.map(product => `
      <div class="product-card">
        <h3>${product.name}</h3>
        <p>$${product.price}</p>
        <button onclick="this.addToCart('${product.id}')">Add to Cart</button>
      </div>
    `).join('');
  }

  addToCart(productId) {
    // Dispatch custom event for communication
    this.dispatchEvent(new CustomEvent('add-to-cart', {
      detail: { productId },
      bubbles: true,
    }));
  }
}

customElements.define('product-catalog', ProductCatalog);

// Usage in host application
document.addEventListener('add-to-cart', (event) => {
  console.log('Product added to cart:', event.detail.productId);
  // Update cart state
});

4. Server-Side Composition

Best for: SEO-critical applications with server-side rendering

// Express.js composition server
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');
const app = express();

// Proxy to micro-frontends
app.use('/products', createProxyMiddleware({
  target: 'http://products-service:3001',
  changeOrigin: true,
}));

app.use('/checkout', createProxyMiddleware({
  target: 'http://checkout-service:3002',
  changeOrigin: true,
}));

// Server-side composition
app.get('/', async (req, res) => {
  try {
    // Fetch fragments from micro-frontends
    const [header, products, footer] = await Promise.all([
      fetch('http://shell-service:3000/header').then(r => r.text()),
      fetch('http://products-service:3001/featured').then(r => r.text()),
      fetch('http://shell-service:3000/footer').then(r => r.text()),
    ]);

    const html = `
      <!DOCTYPE html>
      <html>
        <head>
          <title>E-commerce App</title>
          <link rel="stylesheet" href="/styles.css">
        </head>
        <body>
          ${header}
          <main>
            ${products}
          </main>
          ${footer}
          <script src="/app.js"></script>
        </body>
      </html>
    `;

    res.send(html);
  } catch (error) {
    res.status(500).send('Error loading page');
  }
});

app.listen(3000);

Communication Between Micro-Frontends

1. Custom Events (Recommended)

// Publishing events
class EventBus {
  static dispatch(eventName, data) {
    const event = new CustomEvent(eventName, {
      detail: data,
      bubbles: true,
    });
    document.dispatchEvent(event);
  }

  static subscribe(eventName, callback) {
    document.addEventListener(eventName, callback);

    // Return unsubscribe function
    return () => document.removeEventListener(eventName, callback);
  }
}

// Micro-frontend A (Products)
function addToCart(product) {
  EventBus.dispatch('cart:add', { product });
}

// Micro-frontend B (Cart)
EventBus.subscribe('cart:add', (event) => {
  const { product } = event.detail;
  updateCartState(product);
});

2. Shared State Management

// Shared store using RxJS
import { BehaviorSubject } from 'rxjs';

class SharedStore {
  constructor() {
    this.state$ = new BehaviorSubject({
      user: null,
      cart: [],
      theme: 'light',
    });
  }

  getState() {
    return this.state$.value;
  }

  setState(newState) {
    this.state$.next({ ...this.getState(), ...newState });
  }

  subscribe(callback) {
    return this.state$.subscribe(callback);
  }

  // Specific actions
  addToCart(product) {
    const currentState = this.getState();
    this.setState({
      cart: [...currentState.cart, product],
    });
  }

  setUser(user) {
    this.setState({ user });
  }
}

// Global instance
window.sharedStore = new SharedStore();

// Usage in micro-frontends
const store = window.sharedStore;

// Subscribe to changes
store.subscribe((state) => {
  console.log('State updated:', state);
  updateUI(state);
});

// Update state
store.addToCart(product);

3. URL-Based Communication

// Router service for micro-frontends
class MicroFrontendRouter {
  constructor() {
    this.routes = new Map();
    this.currentRoute = null;

    window.addEventListener('popstate', this.handleRouteChange.bind(this));
  }

  register(pattern, microfrontend) {
    this.routes.set(pattern, microfrontend);
  }

  navigate(path, state = {}) {
    history.pushState(state, '', path);
    this.handleRouteChange();
  }

  handleRouteChange() {
    const path = window.location.pathname;

    for (const [pattern, microfrontend] of this.routes) {
      if (this.matchRoute(pattern, path)) {
        this.activateMicrofrontend(microfrontend, path);
        break;
      }
    }
  }

  matchRoute(pattern, path) {
    const regex = new RegExp(pattern.replace(/:\w+/g, '([^/]+)'));
    return regex.test(path);
  }

  activateMicrofrontend(microfrontend, path) {
    if (this.currentRoute !== microfrontend) {
      this.currentRoute?.deactivate?.();
      microfrontend.activate(path);
      this.currentRoute = microfrontend;
    }
  }
}

// Usage
const router = new MicroFrontendRouter();

router.register('/products/:category?', {
  activate: (path) => {
    import('./products/app.js').then(app => app.mount());
  },
  deactivate: () => {
    // Cleanup
  },
});

router.register('/checkout', {
  activate: () => {
    import('./checkout/app.js').then(app => app.mount());
  },
});

Styling and Design Systems

CSS Isolation Strategies

/* BEM methodology for namespace isolation */
.mf-products__card {
  border: 1px solid #ddd;
  padding: 16px;
}

.mf-products__card--featured {
  border-color: #007bff;
}

/* CSS Modules */
.productCard {
  composes: card from 'shared-styles/components.css';
  border-radius: 8px;
}

/* Styled Components with namespace */
const ProductCard = styled.div`
  border: 1px solid #ddd;
  padding: 16px;

  &.mf-products-featured {
    border-color: #007bff;
  }
`;

Shared Design System

// Design system package
// packages/design-system/src/index.js
export { Button } from './components/Button';
export { Card } from './components/Card';
export { theme } from './theme';

// Micro-frontend usage
import { Button, Card, theme } from '@company/design-system';
import { ThemeProvider } from 'styled-components';

function ProductApp() {
  return (
    <ThemeProvider theme={theme}>
      <Card>
        <h2>Product Name</h2>
        <Button variant="primary">Add to Cart</Button>
      </Card>
    </ThemeProvider>
  );
}

Testing Micro-Frontends

Unit Testing

// Jest configuration for micro-frontend
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.js'],
  moduleNameMapping: {
    '^@shared/(.*)$': '<rootDir>/../shared/src/$1',
  },
  transform: {
    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
  },
};

// Testing with mocked dependencies
import { render, screen } from '@testing-library/react';
import ProductList from './ProductList';

// Mock external micro-frontend
jest.mock('mfCart/CartService', () => ({
  addToCart: jest.fn(),
}));

test('renders product list', () => {
  render(<ProductList />);
  expect(screen.getByText('Products')).toBeInTheDocument();
});

Integration Testing

// Cypress integration tests
describe('Micro-frontend Integration', () => {
  it('should communicate between products and cart', () => {
    cy.visit('/');

    // Interact with products micro-frontend
    cy.get('[data-testid="product-card"]').first().click();
    cy.get('[data-testid="add-to-cart"]').click();

    // Verify cart micro-frontend updates
    cy.get('[data-testid="cart-count"]').should('contain', '1');

    // Navigate to cart
    cy.get('[data-testid="cart-link"]').click();
    cy.url().should('include', '/cart');
    cy.get('[data-testid="cart-item"]').should('exist');
  });
});

Contract Testing

// Pact.js for API contract testing
import { Pact } from '@pact-foundation/pact';

const provider = new Pact({
  consumer: 'products-microfrontend',
  provider: 'products-api',
  port: 1234,
});

describe('Products API Contract', () => {
  beforeAll(() => provider.setup());
  afterAll(() => provider.finalize());

  it('should get product list', async () => {
    await provider.addInteraction({
      state: 'products exist',
      uponReceiving: 'a request for products',
      withRequest: {
        method: 'GET',
        path: '/api/products',
      },
      willRespondWith: {
        status: 200,
        body: [
          { id: 1, name: 'Product 1', price: 99.99 },
        ],
      },
    });

    const response = await fetch('http://localhost:1234/api/products');
    const products = await response.json();

    expect(products).toHaveLength(1);
    expect(products[0]).toHaveProperty('id', 1);
  });
});

Deployment and DevOps

Container-Based Deployment

## Dockerfile for micro-frontend
FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

## docker-compose.yml
version: '3.8'
services:
  shell:
    build: ./shell
    ports:
      - "3000:80"
    environment:
      - PRODUCTS_URL=http://products:80
      - CHECKOUT_URL=http://checkout:80

  products:
    build: ./products
    ports:
      - "3001:80"

  checkout:
    build: ./checkout
    ports:
      - "3002:80"

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - shell
      - products
      - checkout

Kubernetes Deployment

## k8s/products-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: products-microfrontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: products-microfrontend
  template:
    metadata:
      labels:
        app: products-microfrontend
    spec:
      containers:
      - name: products
        image: company/products-microfrontend:latest
        ports:
        - containerPort: 80
        env:
        - name: API_URL
          value: "https://api.company.com"
---
apiVersion: v1
kind: Service
metadata:
  name: products-service
spec:
  selector:
    app: products-microfrontend
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

CI/CD Pipeline

## .github/workflows/deploy.yml
name: Deploy Micro-frontend

on:
  push:
    branches: [main]
    paths: ['products/**']

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
        working-directory: ./products
      - run: npm test
        working-directory: ./products
      - run: npm run test:integration
        working-directory: ./products

  build-and-deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Docker image
        run: |
          docker build -t company/products-microfrontend:${{ github.sha }} ./products
          docker tag company/products-microfrontend:${{ github.sha }} company/products-microfrontend:latest

      - name: Deploy to staging
        run: |
          kubectl set image deployment/products-microfrontend products=company/products-microfrontend:${{ github.sha }}
          kubectl rollout status deployment/products-microfrontend

Performance Optimization

Bundle Optimization

// Webpack optimization for micro-frontends
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          chunks: 'all',
        },
        shared: {
          name: 'shared',
          chunks: 'all',
          minChunks: 2,
        },
      },
    },
  },
  externals: {
    react: 'React',
    'react-dom': 'ReactDOM',
  },
};

// Dynamic imports for lazy loading
const LazyProductList = React.lazy(() => 
  import('mfProducts/ProductList').catch(() => ({
    default: () => <div>Products unavailable</div>
  }))
);

Caching Strategies

// Service worker for micro-frontend caching
const CACHE_NAME = 'mf-products-v1';
const REMOTE_CACHE = 'mf-remotes-v1';

self.addEventListener('fetch', event => {
  const { request } = event;

  // Cache micro-frontend bundles
  if (request.url.includes('remoteEntry.js')) {
    event.respondWith(
      caches.open(REMOTE_CACHE).then(cache => {
        return cache.match(request).then(response => {
          if (response) {
            // Serve from cache, update in background
            fetch(request).then(fetchResponse => {
              cache.put(request, fetchResponse.clone());
            });
            return response;
          }
          return fetch(request).then(fetchResponse => {
            cache.put(request, fetchResponse.clone());
            return fetchResponse;
          });
        });
      })
    );
  }
});

Common Pitfalls and Solutions

1. Dependency Conflicts

Problem: Different versions of shared libraries causing conflicts

Solution: Use Module Federation's shared dependencies

// webpack.config.js
new ModuleFederationPlugin({
  shared: {
    react: {
      singleton: true,
      requiredVersion: '^18.0.0',
    },
    'react-dom': {
      singleton: true,
      requiredVersion: '^18.0.0',
    },
  },
});

2. Performance Overhead

Problem: Loading multiple bundles impacts performance

Solution: Implement smart loading strategies

// Preload critical micro-frontends
const preloadMicrofrontend = (name) => {
  const link = document.createElement('link');
  link.rel = 'preload';
  link.href = `${name}/remoteEntry.js`;
  link.as = 'script';
  document.head.appendChild(link);
};

// Preload on user interaction
button.addEventListener('mouseenter', () => {
  preloadMicrofrontend('products');
});

3. State Management Complexity

Problem: Sharing state between micro-frontends becomes complex

Solution: Use event-driven architecture with clear boundaries

// Clear state boundaries
class MicrofrontendState {
  constructor(namespace) {
    this.namespace = namespace;
    this.state = new Map();
  }

  get(key) {
    return this.state.get(`${this.namespace}:${key}`);
  }

  set(key, value) {
    this.state.set(`${this.namespace}:${key}`, value);
    this.emit('stateChange', { key, value });
  }

  emit(event, data) {
    window.dispatchEvent(new CustomEvent(`${this.namespace}:${event}`, {
      detail: data
    }));
  }
}

Frequently Asked Questions

Q: When should I choose micro-frontends over a monolith?
A: Consider micro-frontends when you have multiple teams (10+ developers), need independent deployments, or are modernizing legacy systems. For smaller teams or simple applications, monoliths are often better.

Q: How do I handle SEO with micro-frontends?
A: Use server-side composition or static site generation. Each micro-frontend should be able to render on the server and provide proper meta tags and structured data.

Q: What about bundle size and performance?
A: Micro-frontends can increase bundle size due to duplication. Use shared dependencies, lazy loading, and proper caching strategies. Monitor performance metrics closely.

Q: How do I test micro-frontends?
A: Use a combination of unit tests for individual micro-frontends, integration tests for communication, and contract tests for APIs. Consider using tools like Pact for contract testing.

Q: Can I mix different frameworks?
A: Yes, that's one of the benefits of micro-frontends. You can use React for one part, Vue for another, and Angular for a third. However, this increases complexity and bundle size.

Micro-frontends are powerful but complex. They solve real problems for large organizations but introduce new challenges. Choose them when the benefits outweigh the costs, and implement them thoughtfully with proper tooling and processes.

Explore more articles in our API Development series:

Complete Guide to Building SaaS with Next.js and Supabase - Complete guide covering all aspects
More related articles coming soon

Originally published at https://iloveblogs.blog

Why 'Powering Through' is Burning You Out: The ROI of Mental Health Days

Mahdi BEN RHOUMA — Wed, 29 Apr 2026 11:01:02 +0000

Why 'Powering Through' is Burning You Out: The ROI of Mental

We treat our bodies like machines, but even machines need downtime for maintenance. If you run a car engine at the redline 24/7, it explodes. Why do you expect your brain to be different?

Related reading: See our articles on mindfulness and stress management and social media's impact on mental health for more insights.

The Cortisol Cycle

Chronic stress keeps cortisol levels high. This:

Shrinks the hippocampus (memory center).
Impairs the prefrontal cortex (decision making).
Weakens the immune system.

Rest vs. Recovery

Sitting on the couch scrolling TikTok is Rest (low activity), but it is NOT Recovery.
True Recovery requires:

Detachment: Psychological disconnect from work thoughts.
Relaxation: Actively lowering sympathetic nervous system arousal (meditation, nature walks).
Mastery: Doing something you're good at just for fun (hobbies).

How to Take a Mental Health Day

Plan it: Don't wait until you crash. Schedule it proactively.
Unplug: Delete Slack/Email from your phone for 24 hours. The world will survive.
Do Nothing or Do Something: But do it intentionally.

Conclusion

Productivity isn't a marathon; it's a series of sprints. Mental health days are the interval rest periods that allow you to sprint again.

Further Reading:

American Psychological Association: Burnout and Stress - Research-backed insights on workplace stress and mental health from the leading psychology organization.
National Institute of Mental Health - Evidence-based resources on mental health care and wellness from the NIH.
Learn more about our editorial team and how we research our content.

Originally published at https://iloveblogs.blog

Machine Learning Basics for JavaScript Developers

Mahdi BEN RHOUMA — Tue, 28 Apr 2026 11:08:58 +0000

Machine Learning Basics for JavaScript Developers

Machine Learning (ML) often feels like a party where everyone is speaking Python. But the web is the most accessible platform in the world, and JavaScript is its language. It's time to bring ML to the browser.

Related reading: See our articles on AI coding assistants and productivity and plug-and-play AI APIs for more insights.

Why JavaScript for ML?

Privacy: Run models directly on the client's device; no data leaves the browser.
Latency: Real-time inference without server round-trips.
Reach: Access to sensors (camera, microphone, GPS) and easy deployment to billions of devices.

Key Concepts Explained

1. Tensors

Think of them as supercharged arrays. They are the fundamental data structure in ML frameworks.

// A simple 1D tensor in TensorFlow.js
const t = tf.tensor([1, 2, 3, 4]);

2. Models & Layers

A model is like a function that learns. It's built of layers, each transforming data to extract features. E.g., a "Dense" layer connects every input to every output, good for general learning tasks.

3. Training vs. Inference

Training: Teaching the model using data (heavy lifting, often server-side).
Inference: Using the trained model to make predictions (fast, great for client-side).

Getting Started with TensorFlow.js

TensorFlow.js is the heavy hitter here. You can:

Import existing models: Use pre-trained models for image recognition, pose detection, etc.
Transfer learning: Retrain top layers of an existing model with your own data.
Build from scratch: Define your own architecture.

Example: Using a Pre-trained Model

// Load the MobileNet model
const model = await mobilenet.load();

// Classify the image
const predictions = await model.classify(imgElement);

console.log('Predictions: ', predictions);

The Future is Isomorphic

With runtimes like Node.js, Deno, and Bun, your ML JavaScript code can run anywhere. Whether you're building smart UI components or intelligent serverless functions, the barrier to entry for ML has never been lower.

Further Reading:

TensorFlow.js Official Documentation - The official guide and API reference for machine learning in JavaScript from Google.
MDN Web Docs: Machine Learning - Mozilla's comprehensive web development resources and JavaScript fundamentals.
Learn more about our editorial team and how we research our content.

This article is part of our comprehensive AI Integration for Next.js + Supabase Applications guide.

Frequently Asked Questions

Why JavaScript for ML?

Privacy: Run models directly on the client's device; no data leaves the browser. - Latency: Real-time inference without server round-trips. - Reach: Access to sensors (camera, microphone, GPS) and easy deployment to billions of devices.

Explore more articles in our AI Integration series:

AI Integration for Next.js + Supabase Applications - Complete guide covering all aspects
More related articles coming soon

Originally published at https://iloveblogs.blog

DEV Community: Mahdi BEN RHOUMA

Next.js Server Actions with Supabase: Complete Production Guide

Next.js Server Actions with Supabase: Complete Production Guide

Prerequisites

Why Server Actions with Supabase

Basic Server Action Setup

Type-Safe Validation with Zod

Loading States and Pending UI

Optimistic Updates

File Uploads with Server Actions

Revalidation Strategies

Error Handling Patterns

Common Pitfalls

1. Forgetting 'use server' Directive

2. Using Client-Only APIs

3. Not Handling Race Conditions

4. Returning Non-Serializable Data

5. Missing Revalidation

Production Patterns

Rate Limiting

Audit Logging

Summary

Next.js Performance Optimization for Indie Developers

Next.js Performance Optimization for Indie Developers

Why Performance Matters

1. Understanding Core Web Vitals

The Three Key Metrics

Measuring Performance

2. Image Optimization

Next.js Image Component

Responsive Images

Image Formats

External Image Optimization

3. Code Splitting and Bundling

Dynamic Imports

Route-Based Code Splitting

Component-Level Code Splitting

Bundle Analysis

4. Server-Side Rendering Optimization

Server Components (Default)

Client Components (When Needed)

Streaming with Suspense

Parallel Data Fetching

5. Static Generation and ISR

Static Site Generation (SSG)

Incremental Static Regeneration (ISR)

On-Demand Revalidation

6. Caching Strategies

Fetch Caching

React Cache

Memoization

7. Database Query Optimization

Efficient Queries

Pagination

Indexing

8. Font Optimization

Next.js Font Optimization

Custom Fonts

9. Reducing First Contentful Paint (FCP)

Critical CSS

Preload Critical Resources

Remove Render-Blocking Resources

10. Monitoring and Measuring Performance

Real User Monitoring (RUM)

Performance API

Lighthouse CI

11. Edge Runtime Optimization

Edge Functions

Edge Middleware

12. Common Performance Pitfalls

Avoid Client-Side Data Fetching

Avoid Large Client Bundles

Avoid Layout Shifts

Related Articles

Conclusion

Resolve Next.js Hydration Mismatch Errors Complete Guide

Resolve Next.js Hydration Mismatch Errors Complete Guide

What is Hydration?

Common Error Messages

Solution 1: Fix Date/Time Rendering