Next.js 15.5+ + Firebase Development Guide

This skill provides comprehensive guidance for building modern Next.js 15.5+ applications with Firebase, TypeScript, Material-UI v7, and Node.js.

When to Use This Skill

Use this skill when:

• Setting up a new Next.js 15.5+ project with Firebase
• Configuring Next.js with TypeScript, MUI v7, or Turbopack
• Working with Next.js App Router patterns (Server Components, Client Components, routing)
• Integrating Firebase services (Auth, Firestore, Storage, Firebase SDK v12.x)
• Troubleshooting build errors, runtime errors, or deployment issues
• Implementing best practices for Next.js + Firebase projects
• Optimizing performance and build times with Turbopack (beta for production builds)
• Using Node.js Middleware (stable in 15.5)
• Working with typed routes and route props helpers
• Understanding CLI commands and configuration options

Quick Reference

Essential Commands

# Create new project (Next.js 15.5+)
npx create-next-app@latest my-app --typescript --eslint --src-dir --app

# Development
npm run dev              # Start dev server (webpack by default)
npm run dev --turbopack  # Start with Turbopack (faster, optional)
npm run dev -- -p 4000   # Start on custom port

# Type checking & linting
tsc --noEmit            # Check types
npx eslint .            # Run ESLint CLI directly (next lint deprecated in 15.5)

# Generate types for routes (NEW in 15.5)
npx next typegen        # Generate route types without full build

# Build & production
npm run build           # Create production build (webpack - RECOMMENDED)
npm run start           # Start production server

⚠️ Important: Turbopack production builds (--turbopack flag) are in beta and NOT RECOMMENDED for production use yet. Use webpack (default) for builds.

Project Stack

• Framework: Next.js 15.5+ with App Router
• Language: TypeScript 5.9.3+
• UI Library: Material-UI (MUI) v7.3.4+
• Backend: Firebase SDK v12.x (Firestore, Auth, Storage, App Hosting)
• Bundler: webpack (default, recommended) / Turbopack (optional for dev with --turbopack flag)
• Runtime: Node.js ≥22.x (recommended)

Reference Documentation

The skill includes comprehensive reference documentation. Read these files as needed:

Core References

• cli-commands.md - Complete Next.js CLI reference

  • Read when: Running CLI commands, debugging dev server, configuring ports

• create-next-app.md - Project initialization guide

  • Read when: Creating new Next.js projects, understanding setup options

• next-config.md - Configuration reference

  • Read when: Configuring Next.js, setting up Firebase-specific options, troubleshooting build config

• typescript.md - TypeScript integration guide

  • Read when: Setting up TypeScript, using typed routes, configuring type checking

• turbopack.md - Turbopack bundler reference

  • Read when: Enabling Turbopack for dev (optional), understanding Turbopack limitations, troubleshooting bundler issues

Practice Guides

• best-practices.md - Comprehensive development guide

  • Read when: Starting a new project, implementing Firebase, working with App Router, setting up MUI
  • Contains: Project structure, Firebase setup, authentication patterns, Firestore patterns, routing patterns

• troubleshooting.md - Common errors and solutions

  • Read when: Encountering build errors, runtime errors, TypeScript errors, Firebase errors, deployment issues
  • Contains: Solutions for hydration errors, module not found, Firebase auth errors, MUI setup issues

Key Workflows

1. Starting a New Next.js + Firebase Project

1. Create project:

   npx create-next-app@latest my-app \
     --typescript \
     --eslint \
     --src-dir \
     --app \
     --turbopack
   

2. Install Firebase and MUI:

   npm install firebase  # Firebase SDK v12.x
   npm install @mui/material @mui/icons-material @emotion/react @emotion/styled
   

3. Configure next.config.ts:

   • Enable React Strict Mode
   • Add MUI packages to transpilePackages
   • Configure images for Firebase Storage
   • See next-config.md for full configuration

4. Set up Firebase:

   • Create Firebase project in console
   • Add web app and get config
   • Create .env.local with Firebase credentials
   • Initialize Firebase in src/lib/firebase/config.ts
   • See best-practices.md for detailed setup

5. Configure MUI:

   • Set up ThemeProvider in root layout
   • Add AppRouterCacheProvider
   • Create custom theme
   • See best-practices.md for MUI integration

2. Working with App Router

Server Components (default):

• Fetch data directly in components
• No 'use client' needed
• Can use async/await
• Example: best-practices.md - "App Router Patterns"

Client Components:

• Add 'use client' directive at top
• Use React hooks (useState, useEffect, etc.)
• Firebase Auth listeners
• Interactive UI elements
• Example: best-practices.md - "Client Components"

Key principle: Use Server Components by default, only add 'use client' when needed (interactivity, hooks, Firebase Auth).

3. Firebase Integration

Authentication:

• Use custom useAuth hook for auth state
• Implement protected routes with loading states
• Handle auth errors properly
• See best-practices.md - "Firebase Authentication Patterns"

Firestore:

• Read data in Server Components when possible
• Write data in Client Components
• Use real-time listeners in Client Components
• Implement proper security rules
• See best-practices.md - "Firestore Patterns"

4. Troubleshooting Common Issues

When encountering errors, follow this process:

1. Identify error category:

   • Build error → Check troubleshooting.md - "Build Errors"
   • Runtime error → Check troubleshooting.md - "Runtime Errors"
   • TypeScript error → Check troubleshooting.md - "TypeScript Errors"
   • Firebase error → Check troubleshooting.md - "Firebase Errors"

2. Apply common solutions:

   • Clear cache: rm -rf .next node_modules && npm install
   • Check environment variables
   • Verify 'use client' directive placement
   • Ensure proper loading state handling

3. Enable debug mode if needed:

   NEXT_DEBUG=1 npm run dev
   

5. Deployment to Firebase

1. Install Firebase CLI: npm install -g firebase-tools
2. Login: firebase login
3. Initialize: firebase init hosting
4. Configure firebase.json for Next.js
5. Build: npm run build
6. Deploy: firebase deploy --only hosting

See best-practices.md - "Deployment to Firebase" for detailed steps.

Important Configuration Files

next.config.ts

Essential for Firebase + MUI setup:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  reactStrictMode: true,
  transpilePackages: [
    '@mui/material',
    '@mui/system',
    '@mui/icons-material',
  ],
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'firebasestorage.googleapis.com',
      },
    ],
  },
}

export default nextConfig

tsconfig.json

Configure path aliases and includes:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": [
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ]
}

Best Practices Summary

Do:

• ✅ Use TypeScript for type safety
• ✅ Use Server Components by default
• ✅ Handle loading and error states
• ✅ Use environment variables for Firebase config
• ✅ Enable React Strict Mode
• ✅ Use Turbopack for faster development
• ✅ Implement Firebase Security Rules
• ✅ Optimize images with next/image
• ✅ Check if Firebase already initialized

Don't:

• ❌ Don't use Firebase Auth in Server Components
• ❌ Don't ignore TypeScript errors in production
• ❌ Don't forget loading states
• ❌ Don't initialize Firebase multiple times
• ❌ Don't create Client Components unnecessarily
• ❌ Don't expose sensitive data in client code

Progressive Reference Loading

Read reference files progressively based on task needs:

For setup tasks:

1. Start with best-practices.md
2. Refer to create-next-app.md for initialization
3. Check next-config.md for configuration

For development tasks:

1. Check best-practices.md for patterns
2. Refer to typescript.md for type issues
3. Check turbopack.md for bundler features

For troubleshooting:

1. Start with troubleshooting.md
2. Check specific error category
3. Refer to relevant practice guide for correct implementation

For CLI operations:

1. Check cli-commands.md for command syntax
2. Refer to examples in best-practices.md

Common Task Quick Guide

Notes

• This skill is optimized for Next.js 15.5+ with App Router (not Pages Router)
• All examples use TypeScript (not JavaScript)
• Firebase App Hosting is the deployment target (not Vercel)
• MUI v7.3.4+ is used for UI components
• webpack is the default and recommended bundler for builds
• Turbopack can be used for dev with --turbopack flag (optional, faster HMR)
• Turbopack production builds are NOT RECOMMENDED (beta, unstable)
• Node.js Middleware is now stable (supports full Node.js APIs)
• next lint command is deprecated (use ESLint CLI directly)
• next typegen command is new in 15.5 (generates types without full build)
• Typed routes are now stable (enables compile-time link validation)
• Firebase SDK v12.x is the current version

Getting Help

If you encounter issues not covered in the troubleshooting guide:

1. Check Next.js documentation: https://nextjs.org/docs
2. Check Firebase documentation: https://firebase.google.com/docs
3. Search GitHub issues for Next.js and Firebase
4. Enable debug mode: NEXT_DEBUG=1 npm run dev