DEV Community

Cover image for Scalable Git Workflow & Next.js Project Structure Master Guide.
Omor Faruk
Omor Faruk

Posted on

Scalable Git Workflow & Next.js Project Structure Master Guide.

#nextjs #architecture #git #programming

Scalable Git Workflow & Next.js Project Structure Guide

Uses Next.js App Router, next/font with Geist, TypeScript, and Docker for production-ready deployments.

Introduction

As modern web applications grow in size and complexity, maintaining clean Git practices and a scalable project structure becomes critical. This guide provides:

  • A simple Git branch & commit naming convention
  • A predictable team workflow (PRs, reviews, releases)
  • A scalable Next.js App Router structure
  • Font optimization with next/font (Geist)
  • A Docker production setup
  • Optional tooling: Husky, Commitlint, ESLint, CI/CD

Designed for beginner–intermediate teams who want a lean, professional standard.

Part 0: Font Setup with next/font (Geist)

Next.js automatically optimizes fonts using next/font.

app/layout.tsx

import { GeistSans } from 'geist/font/sans';
import './globals.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={GeistSans.className}>
      <body>{children}</body>
    </html>
  );
}
Enter fullscreen mode Exit fullscreen mode

Benefits:

  • No layout shift
  • Automatic preload
  • No external font requests

Part 1: Git Branch Naming Convention

Format 

<category>/<reference>/<description-in-kebab-case>
Enter fullscreen mode Exit fullscreen mode

Categories

  • feature → Add/change a feature
  • bugfix → Fix a bug
  • hotfix → Emergency fix
  • test → Experiments

Reference

  • Issue ID: issue-42
  • No issue: no-ref

Examples 

feature/issue-42/create-new-button-component
bugfix/issue-342/button-overlap-form-on-mobile
hotfix/no-ref/registration-form-not-working
test/no-ref/refactor-components-with-atomic-design
Enter fullscreen mode Exit fullscreen mode

Part 2: Git Commit Message Convention

Format 

<category>: <imperative statements separated by ;>
Enter fullscreen mode Exit fullscreen mode

Categories

  • feat → New feature
  • fix → Bug fix
  • refactor → Internal code change
  • chore → Docs, tests, formatting

Examples 

feat: add new button component; add button to templates
fix: prevent event propagation in button
refactor: rewrite button component in TypeScript
chore: add button documentation
Enter fullscreen mode Exit fullscreen mode

Part 3: Team Git Workflow

Branch Flow

  • main → Production
  • develop → Integration
  • feature/* → New work
  • bugfix/* → Bug fixes
  • hotfix/* → Emergency patches

Rules

  • Never push directly to main
  • Always open PRs
  • Require 1–2 approvals
  • Squash merge to keep history clean

Part 4: Scalable Next.js Project Structure (App Router) 

my-nextjs-project/
│
├── app/
│   ├── (auth)/
│   │   ├── login/page.tsx
│   │   ├── register/page.tsx
│   ├── dashboard/
│   │   ├── page.tsx
│   │   ├── layout.tsx
│   ├── game/
│   │   ├── page.tsx
│   │   ├── layout.tsx
│   │   └── _components/
│   │       ├── GameHeader.tsx
│   │       └── ScorePanel.tsx
│   ├── api/
│   │   └── users/route.ts
│   ├── layout.tsx
│   ├── page.tsx
│   ├── globals.css
│
├── components/
│   ├── ui/Button.tsx
│   ├── ui/Card.tsx
│   ├── forms/LoginForm.tsx
│   ├── layouts/Header.tsx
│   ├── layouts/Footer.tsx
│
├── context/
│   ├── userContext.ts
│   └── authContext.ts
│
├── lib/
│   ├── api.ts
│   └── utils.ts
│
├── hooks/
│   ├── useUser.ts
│   └── useAuth.ts
│
├── types/
│   ├── user.ts
│   └── api.ts
│
├── public/images/logo.svg
├── .env
├── .gitignore
├── .dockerignore
├── next.config.js
├── package.json
├── tsconfig.json
├── Dockerfile
├── compose.yml
└── README.md
Enter fullscreen mode Exit fullscreen mode

Part 5: Key Architecture Rules

Server vs Client Components

  • Default to Server Components

  • Add 'use client' only when:

    • Using state
    • Using effects
    • Accessing browser APIs

Absolute Imports

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["./*"] }
  }
}
Enter fullscreen mode Exit fullscreen mode

Usage:

import Button from '@/components/ui/Button';
Enter fullscreen mode Exit fullscreen mode

Part 6: Environment Variables

.env

NEXT_PUBLIC_API_URL=https://api.example.com
JWT_SECRET=supersecret
Enter fullscreen mode Exit fullscreen mode

Rules:

  • NEXT_PUBLIC_* → Client-safe
  • Others → Server-only

Part 7: Getting Started 

npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

Open: http://localhost:3000

Part 8: Production Docker Setup (Multi‑Stage)

Dockerfile

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["npm", "start"]
Enter fullscreen mode Exit fullscreen mode

compose.yml

services:
  nextjs:
    build: .
    ports:
      - '3000:3000'
    env_file:
      - .env
Enter fullscreen mode Exit fullscreen mode

Part 9: Code Quality Tooling (Optional)

ESLint + Prettier 

npm install -D eslint prettier eslint-config-next
Enter fullscreen mode Exit fullscreen mode

Husky + Commitlint 

npm install -D husky @commitlint/cli @commitlint/config-conventional
npx husky install
Enter fullscreen mode Exit fullscreen mode

commitlint.config.js

module.exports = { extends: ['@commitlint/config-conventional'] };
Enter fullscreen mode Exit fullscreen mode

Part 10: CI/CD with GitHub Actions

.github/workflows/ci.yml

name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm ci
      - run: npm run lint
      - run: npm run build
Enter fullscreen mode Exit fullscreen mode

Conclusion

This standard gives you:

  • Clean Git history
  • Predictable workflows
  • Scalable Next.js structure
  • Optimized fonts
  • Production Docker builds
  • CI-ready pipeline

Optional Enhancements

  • Semantic versioning + releases
  • Feature flags
  • Error tracking (Sentry)
  • Code owners

Follow me for more : https://www.linkedin.com/in/theonlineaid/

Top comments (2)

Collapse
 
gi_mi_d1135cca91c6c5584ad profile image
gi mi •

hello, when the project scale but if i don't want to use hard code and i want to Easy maintenance,

how to create organize Architecture Structure make it clean and Standard next js , Thank

Collapse
 
theonlineaid profile image
Omor Faruk •

Ignore Docker if you don't need it. The rest of the things you need to understand. It depends on you when you should code and need to scale; if you are a junior, a senior will maintain it.