NEXTJS.md

# NEXTJS.md

## STACK

REQUIRED

- Next.js 16.x
- React 19.x
- JavaScript

OPTIONAL

- TailwindCSS 4.x
- TypeScript
- next-intl

USE_DECLARED_STACK_ONLY

DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED

---

## VERSION_POLICY

PACKAGE_JSON_IS_SOURCE_OF_TRUTH

FRAMEWORK_MD_IS_FALLBACK

USE_DECLARED_VERSIONS_ONLY

DO_NOT_ASSUME_LIBRARY_VERSIONS

DO_NOT_ASSUME_NEXTJS_VERSION

DO_NOT_GENERATE_DEPRECATED_PATTERNS

WHEN_VERSION_CONFLICT_EXISTS

FOLLOW_PACKAGE_JSON

---

## PROJECT_STRUCTURE

```text
app/

components/
├── layout/
├── sections/
└── ui/

data/
hooks/
utils/
styles/
images/

public/

next.config.mjs
```

THIS_STRUCTURE_IS_AUTHORITATIVE

DO_NOT_CREATE_SRC_DIRECTORY

DO_NOT_CREATE_SRC_APP

DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES

PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES

---

## FILE_PLACEMENT

routes -> app

layout_components -> components/layout

section_components -> components/sections

reusable_ui_components -> components/ui

static_content -> data

navigation_data -> data

custom_hooks -> hooks

utility_functions -> utils

global_styles -> styles

project_images -> images

public_assets -> public

---

## ROUTING_RULES

USE_APP_ROUTER_ONLY

APP_ROUTER_IS_ROOT_LEVEL

DO_NOT_USE_PAGES_ROUTER

DO_NOT_CREATE_PAGES_DIRECTORY

FOLLOW_NEXTJS_FILE_CONVENTIONS

USE_ROUTE_GROUPS_WHEN_APPROPRIATE

USE_PRIVATE_FOLDERS_FOR_ROUTE_SPECIFIC_CODE

PRIVATE_FOLDERS_START_WITH_UNDERSCORE

---

## COLOCATION_RULES

ALLOW_ROUTE_LOCAL_COMPONENTS

ALLOW_ROUTE_LOCAL_UTILITIES

ALLOW_ROUTE_LOCAL_DATA

USE_PRIVATE_FOLDERS_FOR_ROUTE_SPECIFIC_FILES

PREFER_ROUTE_LOCAL_CODE_WHEN_NOT_SHARED

USE_SHARED_DIRECTORIES_ONLY_FOR_REUSABLE_CODE

---

## COMPONENT_RULES

USE_SERVER_COMPONENTS_BY_DEFAULT

ADD_USE_CLIENT_ONLY_WHEN_REQUIRED

MINIMIZE_CLIENT_COMPONENTS

PREFER_SERVER_RENDERING

ONE_COMPONENT_PER_FILE

DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE

PREFER_SMALL_COMPOSABLE_COMPONENTS

---

## DATA_FETCHING_RULES

FETCH_DATA_IN_SERVER_COMPONENTS_WHEN_POSSIBLE

PREFER_ASYNC_SERVER_COMPONENTS

AVOID_CLIENT_SIDE_FETCHING_UNLESS_REQUIRED

DO_NOT_MOVE_SERVER_FETCHING_TO_CLIENT_COMPONENTS

---

## API_RULES

API_ROUTES_BELONG_IN_APP_API

USE_ROUTE_HANDLERS

FOLLOW_NEXTJS_API_CONVENTIONS

DO_NOT_CREATE_CUSTOM_API_ARCHITECTURE

---

## IMAGE_RULES

USE_NEXT_IMAGE_WHEN_POSSIBLE

PROJECT_IMAGES_BELONG_IN_IMAGES

PUBLIC_ASSETS_BELONG_IN_PUBLIC

OPTIMIZE_IMAGES

---

## STYLING_RULES

USE_PROJECT_DEFINED_STYLING_SOLUTION

IF_TAILWIND_IS_INSTALLED

USE_TAILWINDCSS_ONLY

DO_NOT_MIX_MULTIPLE_STYLING_APPROACHES

---

## RESPONSIVE_RULES

MOBILE_FIRST

RESPONSIVENESS_IS_REQUIRED

REQUIRE_RESPONSIVE_LAYOUTS

REQUIRE_RESPONSIVE_TYPOGRAPHY

REQUIRE_RESPONSIVE_IMAGES

REQUIRE_FLEXIBLE_LAYOUTS

AVOID_FIXED_WIDTH_LAYOUTS

AVOID_HORIZONTAL_SCROLLING

---

## ACCESSIBILITY_RULES

ACCESSIBILITY_IS_REQUIRED

REQUIRE_PROPER_HEADING_HIERARCHY

REQUIRE_ALT_TEXT

REQUIRE_KEYBOARD_ACCESSIBILITY

REQUIRE_SUFFICIENT_COLOR_CONTRAST

ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES

---

## FORBIDDEN_DIRECTORIES

- pages
- src
- features
- shared
- widgets
- modules
- views

DO_NOT_CREATE_FORBIDDEN_DIRECTORIES

UNLESS_EXPLICITLY_REQUESTED

---

## ROOT_DIRECTORY_POLICY

ALLOWED_ROOT_DIRECTORIES

- app
- components
- data
- hooks
- utils
- styles
- images
- public

ALLOWED_ROOT_FILES

- package.json
- next.config.js
- next.config.mjs
- README.md
- jsconfig.json
- tsconfig.json

DO_NOT_CREATE_UNDEFINED_ROOT_DIRECTORIES

---

## GENERATION_POLICY

BEFORE_CREATING_ANY_FILE

1. CHECK_EXISTING_STRUCTURE
2. CHECK_EXISTING_COMPONENTS
3. CHECK_EXISTING_PATTERNS
4. REUSE_BEFORE_CREATING

PREFER_MODIFICATION_OVER_CREATION

PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS

DO_NOT_INVENT_NEW_ARCHITECTURE

DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY

PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS

WHEN_UNCERTAIN

FOLLOW_EXISTING_CODEBASE

DO_NOT_GUESS

---

## NEXTJS_PRINCIPLES

LATEST_STABLE_ONLY

NEW_PROJECTS_ONLY

APP_ROUTER_ONLY

SERVER_FIRST

SERVER_COMPONENTS_BY_DEFAULT

MINIMIZE_USE_CLIENT

MINIMIZE_CLIENT_SIDE_JAVASCRIPT

RESPONSIVE_BY_DEFAULT

ACCESSIBLE_BY_DEFAULT

REUSE_BEFORE_CREATING