Next.js Project Structure & Best Practices | Sinhala Guide | Next.js සංවිධානය

ආයුබෝවන් හැමෝටම!

අද අපි කතා කරන්න යන්නේ ගොඩක් Next.js developers ලාට වැදගත් වෙන, ඒ වගේම project එකක maintainability එකයි, scalability එකයි වැඩි කරන මාතෘකාවක් ගැන. ඒ තමයි Next.js Project Structure එකයි, ඒක organize කරගන්න පුළුවන් best practices ගැනයි. ගොඩක් වෙලාවට පොඩි project එකක් පටන් ගන්නකොට අපි ඒ ගැන වැඩිය හිතන්නේ නෑ. හැබැයි project එක ලොකු වෙනකොට, අලුත් features add වෙනකොට, මේ structure එක හරියට නැතිනම්, වැඩේ අවුල් වෙනවා. අලුත් කෙනෙක් project එකට එනකොට, codebase එක තේරුම් ගන්නත් අමාරු වෙනවා.

ඉතින් මේ guide එකෙන් අපි බලමු, ඔබේ Next.js project එකට clean, maintainable, සහ scalable structure එකක් හදාගන්නේ කොහොමද කියලා. දැනටමත් project එකක් තියෙනවා නම්, ඒක reorganize කරගන්න විදිහත් අපි කතා කරනවා. එහෙනම්, අපි පටන් ගමු!

Next.js Project Structure කියන්නේ මොකක්ද?

සරලව කිව්වොත්, project structure එකක් කියන්නේ ඔබේ application එකේ files සහ directories organize කරලා තියෙන විදිහ. Next.js එකේදී default විදිහටම හොඳ structure එකක් ලැබුණත්, අපේ project එකේ අවශ්‍යතාවයන් අනුව, ඒක තවදුරටත් customize කරගන්න පුළුවන්. හොඳ structure එකක තියෙන ප්‍රධානම වාසි කිහිපයක් තමයි:

• Code Clarity: Code එක කියවන්න, තේරුම් ගන්න ලේසියි.
• Maintainability: Bugs fix කරන්නයි, existing features modify කරන්නයි ලේසියි.
• Scalability: Application එකට අලුත් features එකතු කරන්න ලේසියි.
• Team Collaboration: කණ්ඩායමක් විදිහට වැඩ කරනකොට, හැමෝටම codebase එක තේරුම් ගන්න පහසුයි.
• Reusability: Components සහ utility functions නැවත නැවත භාවිතා කරන්න පුළුවන් වෙන විදිහට හදාගන්න පුළුවන්.

Recommended Project Structure: Layers by Layers

Next.js වලට specific කියලා එකම "right" structure එකක් නෑ. හැබැයි අත්දැකීම් බහුල developers ලා භාවිතා කරන, ගොඩක් beneficial වෙන patterns කිහිපයක් තියෙනවා. අපි එකින් එක බලමු.

The src Directory: Your New Home

Next.js project එකක් initialize කරාම, default විදිහටම pages, public, styles වගේ directories මුල් level එකේම තියෙනවා. හැබැයි, ගොඩක් large-scale applications වලට src නමින් තව directory එකක් හදාගන්න එක best practice එකක්. මේ src directory එක ඇතුලට ඔබේ application code ඔක්කොම දාන්න පුළුවන්. මේකෙන් project root එකේ තියෙන configuration files (next.config.js, tailwind.config.js, .eslintrc.json, etc.) සහ source code එක වෙන් කරගන්න පුළුවන්.

ඔබේ project root එකේ src directory එකක් හදාගන්න. ඊට පස්සේ ඔබේ pages, components, utils, hooks වගේ directories ඒක ඇතුලට දාන්න.

Components: Reusability වල රහස

React සහ Next.js වලදී components කියන්නේ UI එකේ building blocks. මේවා organize කරගන්න විදිහ ගොඩක් වැදගත්. components directory එක ඇතුලත ඔබට තව sub-directories හදාගන්න පුළුවන්.

• components/ui: මේක ඇතුලට දාන්නේ generic, reusable UI components. මේවාට application එකේ business logic එකක් නෑ. උදාහරණ විදිහට Button.tsx, Input.tsx, Card.tsx, Modal.tsx වගේ ඒවා. මේවා ඕනෑම තැනක import කරලා පාවිච්චි කරන්න පුළුවන්.
• components/shared: මේවා UI components වගේම application එකේ business logic එකක් නැති, හැබැයි application එකේ multiple places වල share වෙන components. උදාහරණයක් විදිහට Header.tsx, Footer.tsx, Navbar.tsx වගේ ඒවා. මේවා application-specific වුණත්, එක තැනකට විතරක් සීමා වෙන්නේ නෑ.
• components/features (හෝ components/[feature-name]): Application එකේ specific feature එකකට අදාළ components මෙතනට දානවා. උදාහරණයක් විදිහට, e-commerce app එකක නම් components/features/products, components/features/cart වගේ directories හදලා, ඒ අදාළ components ඒ ඇතුලට දාන්න පුළුවන්. මේකෙන් feature එකක් isolate කරගන්න පුළුවන් වෙනවා.

උදාහරණයක්:

src/
├── components/
│   ├── ui/
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Modal.tsx
│   ├── shared/
│   │   ├── Header.tsx
│   │   └── Footer.tsx
│   └── features/
│       ├── products/
│       │   ├── ProductCard.tsx
│       │   └── ProductList.tsx
│       └── cart/
│           ├── CartItem.tsx
│           └── CartSummary.tsx
...

lib or utils: Helpers for Everything

මේ directories දෙක ගොඩක් වෙලාවට එකිනෙකාට interchangeable විදිහට භාවිතා වුණත්, ඒවා වෙන් කරලා භාවිතා කරන එක best practice එකක්.

• lib: මේක සාමාන්‍යයෙන් backend-focused helper functions, API clients, database connection setups, authentication logic, server-side utilities වගේ දේවල් වලට භාවිතා කරනවා. මේවා client-side එකට bundle නොකරන එක වඩා හොඳයි. (Next.js API Routes හෝ Server Components වලදී ගොඩක් වැදගත්).
• utils: මේක client-side එකට අදාළ general utility functions වලට භාවිතා කරනවා. උදාහරණයක් විදිහට date formatters, string manipulators, form validators, client-side data transformations වගේ දේවල්. මේවා application එකේ ඕනෑම තැනකට import කරලා පාවිච්චි කරන්න පුළුවන්.

උදාහරණයක්:

src/
├── lib/
│   ├── api.ts          # API client (e.g., Axios instance)
│   ├── db.ts           # Database connection
│   └── auth.ts         # Server-side authentication helpers
├── utils/
│   ├── formatters.ts   # Date and currency formatters
│   ├── validators.ts   # Client-side form validation
│   └── helpers.ts      # General utility functions
...

hooks: Custom Logic වලට

React Hooks කියන්නේ functional components වලට state සහ lifecycle features access කරන්න පුළුවන් powerful ක්‍රමයක්. ඔබේ application එකේ reusable logic කොටස් custom hooks විදිහට හදලා, ඒවා hooks directory එක ඇතුලට දාන්න පුළුවන්. මේකෙන් component එකේ logic එක clean කරගන්නයි, logic එක reuse කරන්නයි පුළුවන් වෙනවා.

උදාහරණයක්:

src/
├── hooks/
│   ├── useAuth.ts        # Custom hook for authentication logic
│   ├── useDebounce.ts    # Custom hook for debouncing values
│   └── useLocalStorage.ts# Custom hook for local storage interaction
...

public: Static Files වලට

මේ directory එකේ තියෙන්නේ static assets. උදාහරණ විදිහට images, fonts, favicons වගේ files. Next.js එකේදී මේ files වලට root path (/) එක හරහා access කරන්න පුළුවන්. ඒ නිසා මේ directory එකේ structure එක එතරම් සංකීර්ණ කරන්න අවශ්‍ය නෑ.

pages (හෝ app Directory): ඔබේ Routes

Next.js වලදී file-system-based routing එකට අදාළ files තියෙන්නේ pages directory එක ඇතුලෙයි. (Next.js 13 සහ ඊට ඉහළ versions වලදී app directory එක new default routing paradigm එක විදිහට හඳුන්වා දීලා තියෙනවා.) pages හෝ app directory එක ඇතුලත routes organize කරගන්න එක clean structure එකකට ගොඩක් වැදගත්. Nested routes වලට sub-directories භාවිතා කරන්න. උදාහරණයක් විදිහට:

Pages Router:

src/
├── pages/
│   ├── index.tsx         # Home page
│   ├── about.tsx         # About page
│   ├── blog/             # Blog routes
│   │   ├── index.tsx     # Blog list page
│   │   ├── [slug].tsx    # Individual blog post page
│   └── dashboard/        # Dashboard routes
│       ├── index.tsx     # Dashboard home
│       └── settings.tsx  # Dashboard settings
...

App Router (Reference සඳහා):

Next.js 13 න් පස්සේ ආපු app directory එකත් මේ structure එකට ගොඩක් සමානයි. ඒකෙදී layout.tsx, page.tsx, loading.tsx වගේ special files හරහා routes define කරනවා. concepts ටිකක් වෙනස් වුණත්, project structure එකට අදාළ component organization වගේ best practices ඒකටත් අදාළයි.

styles: CSS වලට Clean Space එකක්

ඔබේ CSS files organize කරගන්නත් හොඳ structure එකක් තියෙන්න ඕනේ. Next.js එකේදී global styles, CSS modules, සහ Tailwind CSS වගේ options තියෙනවා.

• globals.css: Global styles මෙතනට දාන්න.
• [component-name].module.css: Component-specific styles වලට CSS modules භාවිතා කරන්න. මේවා අදාළ component එකටම යාබදව තියෙන එක maintainability එකට හොඳයි.
• Utility CSS (Tailwind CSS): Tailwind CSS වගේ framework එකක් භාවිතා කරනවා නම්, utility classes නිසා CSS files ගොඩක් අඩු වෙනවා.

උදාහරණයක්:

src/
├── styles/
│   ├── globals.css
│   └── variables.css # Optional: for CSS variables
├── components/
│   └── ui/
│       ├── Button.tsx
│       └── Button.module.css # Component-specific CSS module
...

types (Optional): TypeScript භාවිත කරන අයට

ඔබ TypeScript භාවිතා කරනවා නම්, ඔබේ custom types සහ interfaces src/types directory එකක් ඇතුලට දාන්න පුළුවන්. මේකෙන් type definitions එක තැනකට centralize කරගන්න පුළුවන්. index.d.ts හෝ global.d.ts වගේ files වලට global types දාන්නත් පුළුවන්.

Reorganizing Your Project: Step-by-Step

දැනටමත් Next.js project එකක් තියෙනවා නම්, මේ structure එකට ඒක reorganize කරගන්න පුළුවන්. මේක ටිකක් කම්මැලි වැඩක් වුණත්, දිගු කාලීනව ගොඩක් beneficial වෙනවා.

1. නව Directories හදන්න: මුලින්ම src, components (ඒ ඇතුලත ui, shared, features), lib, utils, hooks වගේ directories root level එකේ හෝ src එක ඇතුලත හදාගන්න.
2. Files Move කරන්න: ඔබේ දැනට තියෙන files අලුතින් හදාගත්තු directories වලට move කරන්න. උදාහරණයක් විදිහට, Header.tsx එක components/shared/Header.tsx වලට, api/ folder එකේ තියෙන helper functions lib/api.ts වලට, utils folder එකේ තියෙන formatters utils/formatters.ts වලට වගේ.
3. Imports Update කරන්න: මේක තමයි ටිකක් වෙලා යන, වැදගත්ම step එක. files move කරාට පස්සේ, ඒ files අනිත් තැන්වලට import කරලා තියෙන paths ඔක්කොම update කරන්න වෙනවා. VS Code වගේ IDE එකක් භාවිතා කරනවා නම්, "Find and Replace" (Ctrl/Cmd + Shift + H) එකෙන් ගොඩක් වැඩ පහසු කරගන්න පුළුවන්.
4. Aliases භාවිතා කරන්න: import paths කෙටි කරගන්න path aliases භාවිතා කරන එක best practice එකක්. jsconfig.json (JavaScript වලට) හෝ tsconfig.json (TypeScript වලට) file එකට මේවා add කරන්න පුළුවන්.

Aliases for Easier Imports

Next.js එකේදී jsconfig.json හෝ tsconfig.json file එකට paths property එකක් එකතු කරලා aliases define කරන්න පුළුවන්. මේකෙන් deeply nested imports වළක්වා ගන්න පුළුවන්.

tsconfig.json (or jsconfig.json)

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["src/components/*"],
      "@/lib/*": ["src/lib/*"],
      "@/utils/*": ["src/utils/*"],
      "@/hooks/*": ["src/hooks/*"],
      "@/styles/*": ["src/styles/*"]
    }
  }
}

දැන් ඔබට මෙහෙම import කරන්න පුළුවන්:

Before (without aliases):

import { Button } from '../../components/ui/Button';
import { getProducts } from '../../../lib/api';

After (with aliases):

import { Button } from '@/components/ui/Button';
import { getProducts } from '@/lib/api';

මෙහෙම aliases භාවිතා කරනකොට code එක ගොඩක් clean වෙනවා නේද? file එකක location එක වෙනස් වුණත්, import path එක වෙනස් වෙන්නේ නෑ.

Best Practices for a Healthy Next.js Project

හොඳ structure එකකට අමතරව, ඔබේ Next.js project එක maintainable කරගන්න තව best practices කිහිපයක් තියෙනවා.

Keep Components Small and Focused (Single Responsibility Principle)

මේක software development වල තියෙන ගොඩක් වැදගත් principle එකක්. component එකකට එක වැඩක් විතරක් කරන්න දෙන්න. උදාහරණයක් විදිහට, ProductCard component එක product එකේ විස්තර display කරන එක විතරක් කරන්න ඕනේ. cart එකට add කරන logic එකට වෙන component එකක් හෝ hook එකක් භාවිතා කරන්න.

මොකද මේක වැදගත්?

• Easier to Understand: පොඩි component එකක් කියවන්නයි, තේරුම් ගන්නයි ලේසියි.
• Easier to Test: පොඩි component එකකට unit tests ලියන්න ලේසියි.
• Better Reusability: පොඩි component එකක් වෙනත් තැන්වල reuse කරන්න පුළුවන්.

Separate UI Components from Business Logic

මේක කලින් කතා කරපු Single Responsibility Principle එකටම අදාළයි. ඔබේ components දෙකට වෙන් කරන්න:

• Presentational (UI) Components: මේවා dumb components. data එකක් prop එකක් විදිහට අරගෙන, ඒක display කරනවා විතරයි. මේවාට state management හෝ API calls වගේ logic නෑ. components/ui folder එකට දාන්න පුළුවන්.
• Container (Smart) Components: මේවා data fetching, state management, business logic වගේ දේවල් handle කරනවා. මේවා presentational components වලට data සහ functions pass කරනවා. pages හෝ components/features folder එකේ තියෙන්න පුළුවන්.

මේ separation එකෙන් component එකක responsibility එක clear වෙනවා.

Avoid Deeply Nested Directories

ගොඩක් වෙලාවට අපි files organize කරන්න ගිහින් directories ගොඩක් ගැඹුරට nest කරනවා. ඒත් directory structure එක ගොඩක් ගැඹුරු වෙනකොට import paths ලොකු වෙනවා, ඒ වගේම navigation කරන්නත් අමාරු වෙනවා. 3-4 levels වලට වඩා ගැඹුරට යන්නේ නැතුව බලන්න. aliases භාවිතා කරන එක මේකට හොඳ solution එකක්.

Consistent Naming Conventions

ඔබේ project එක පුරාම files, folders, components වලට consistent naming conventions භාවිතා කරන්න. උදාහරණයක් විදිහට:

• Components: PascalCase (e.g., ProductCard.tsx).
• Files/Folders: kebab-case (e.g., product-details) හෝ camelCase (e.g., productDetails) - project එකේ තියෙන convention එකක් අනුගමනය කරන්න.
• Hooks: use prefix එකෙන් පටන් ගන්න (e.g., useAuth.ts).

Consistency එකෙන් codebase එක කියවන්න ලේසියි.

Conclusion: ඔබේ Project එකට අලුත් පණක්

හොඳ project structure එකක් කියන්නේ ඔබේ Next.js application එකේ long-term success එකට අත්‍යවශ්‍ය දෙයක්. මේ guide එකෙන් අපි සාකච්ඡා කරපු best practices භාවිතා කරලා, ඔබට clean, maintainable, සහ scalable Next.js project එකක් හදාගන්න පුළුවන්. මතක තියාගන්න, project structure එකක් කියන්නේ ජීවමාන දෙයක් වගේ. ඔබේ project එක ලොකු වෙනකොට, අවශ්‍යතාවයන් වෙනස් වෙනකොට, ඒක refactor කරන්න බය වෙන්න එපා.

මුලදී ටිකක් වෙලා ගත්තත්, මේ practices අනුගමනය කරන එකෙන් future development වලදී ඔබේ කාලයයි, ශ්‍රමයයි ගොඩක් ඉතිරි කරගන්න පුළුවන්. ඒ වගේම team members ලාටත් වැඩේ ගොඩක් පහසු වෙනවා.

දැන් ඉතින් ඔබේ Next.js project එක මේ tips පාවිච්චි කරලා optimize කරන්න පටන් ගන්න. ඔබේ අත්දැකීම් කොහොමද? පහල comments වලින් අපිට කියන්න. ඒ වගේම තවත් best practices තියෙනවා නම්, ඒවාත් බෙදාගන්න.

සුබ coding!