chat-gpz/AGENTS.md

Agent Instructions for Next.js + Mantine Project

This document provides context, rules, and workflows for AI agents operating in this codebase.

1. Project Overview & Commands

Core Scripts

The project uses npm for dependency management and script execution.

• Development Server: npm run dev
  • Starts the Next.js development server on port 3000.
• Production Build: npm run build
  • Creates an optimized production build.
• Start Production: npm run start
  • Runs the built application in production mode.
• Type Check: npm run typecheck
  • Runs TypeScript compiler (tsc) without emitting files to verify types.
• Storybook: npm run storybook
  • Launches the Storybook UI environment for component development.

Linting & Formatting

Always ensure code passes these checks before submitting changes.

• Lint All: npm run lint (Runs ESLint and Stylelint)
• ESLint: npm run eslint (Checks JavaScript/TypeScript rules)
• Stylelint: npm run stylelint (Checks CSS/SCSS modules)
• Prettier Check: npm run prettier:check (Verifies formatting)
• Prettier Fix: npm run prettier:write (Fixes formatting issues automatically)

Testing

• Run All Checks: npm test
  • Comprehensive check: typegen, prettier, lint, typecheck, and unit tests.
• Run Unit Tests: npm run jest
  • Runs the Jest test suite.
• Run Single Test File: npm run jest -- components/MyComponent/MyComponent.test.tsx
  • Critical: Use this when working on a specific component to save time.
• Watch Mode: npm run jest:watch

2. Architecture & File Structure

Directory Layout

.
├── app/                  # Next.js App Router pages and layouts
├── components/           # Shared React components (Atomic design preferred)
│   └── Feature/          # Feature-specific directory
│       ├── Feature.tsx        # Main component file
│       ├── Feature.module.css # CSS Modules
│       ├── Feature.story.tsx  # Storybook file
│       └── Feature.test.tsx   # Jest test file
├── public/               # Static assets (images, fonts, etc.)
├── theme.ts              # Mantine theme overrides and configuration
└── ...config files

Framework Conventions

• Next.js App Router:
  • Use page.tsx for routes.
  • Use layout.tsx for wrapping pages.
  • default to Server Components.
  • Add 'use client'; at the very top of the file only when interactivity (hooks, event listeners) is required.
• Mantine UI:
  • Use @mantine/core components for structure (Stack, Group, Grid) instead of raw divs with CSS flexbox.
  • Use rem functions for sizing to respect user settings.

3. Code Style & Standards

TypeScript

• Strict Mode: Enabled. No implicit any.
• Interfaces: Prefer interface over type for object definitions.
• Props: Define a specific interface for component props, exported if reusable.

  export interface MyComponentProps {
    title: string;
    isActive?: boolean;
  }
  

Naming Conventions

• Components: PascalCase (e.g., UserProfile.tsx).
• Functions/Hooks: camelCase (e.g., useAuth, handleSubmit).
• CSS Modules: camelCase for class names.

  /* styles.module.css */
  .container { ... } /* Good */
  .user-card { ... } /* Avoid kebab-case in modules if possible for dot notation access */
  

• Tests: ComponentName.test.tsx.

Imports

• Path Aliases: Always use @/ to refer to the project root.
  • import { Button } from '@mantine/core';
  • import { MyComp } from '@/components/MyComp';
• Sorting: Imports are automatically sorted. Run npm run prettier:write if the linter complains.

4. Component Development Workflow

When creating or modifying a component (e.g., UserProfile), follow this checklist:

1. Scaffold Files:
   • UserProfile.tsx
   • UserProfile.module.css
   • UserProfile.test.tsx
   • UserProfile.story.tsx
2. Implementation:
   • Define strict Props interface.
   • Use Mantine components for layout.
   • Use CSS Modules for custom styling not covered by Mantine props.
3. Theming:
   • Use theme object from Mantine for colors/spacing.
   • Support light/dark mode using Mantine's mixins or standard CSS variables if needed.
4. Testing:
   • Write a basic render test.
   • Test user interactions (clicks, inputs) using @testing-library/user-event.
   • Ensure accessibility (aria- attributes) if creating custom interactive elements.
5. Storybook:
   • Create a basic story to visualize the component in isolation.

5. Testing & Verification

Jest & React Testing Library

• Queries: Prioritize accessibility-based queries:
  1. getByRole (buttons, links, headings)
  2. getByLabelText (form inputs)
  3. getByText (non-interactive content)
  4. getByTestId (last resort)
• Mocking:
  • Mock external modules utilizing jest.mock.
  • Use jest.setup.cjs for global mocks if needed (like window.matchMedia).

Example Test Pattern

import { render, screen } from '@/test-utils'; // Use project test-utils if available
import { MyComponent } from './MyComponent';

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent title="Test" />);
    expect(screen.getByRole('heading', { name: /test/i })).toBeInTheDocument();
  });
});

6. Error Handling & Best Practices

• Async/Await: Use try/catch blocks for API calls.
• Validation: Use zod if installed for schema validation, otherwise use strict TypeScript checks.
• Accessibility:
  • Ensure all img tags have alt text.
  • Ensure buttons have discernible text or aria-label.
  • Verify contrast ratios using the Storybook accessibility addon if available.
• Performance:
  • Use next/image for images.
  • Avoid heavy computations in render cycles; use useMemo sparingly and only when proven necessary.

7. Troubleshooting

• Style Issues: If styles aren't applying, check if postcss.config.cjs is correctly processing the file and that the class is applied via className={classes.myClass}.
• Hydration Errors: Ensure HTML structure is valid (no div inside p) and that the server/client output matches. Use useEffect for browser-only rendering if needed.
• Test Failures: If jest fails on imports, check jest.config.cjs for moduleNameMapper settings matching tsconfig.json paths.

8. Documentation & External Resources

• Mantine Documentation:
  • CRITICAL: When implementing Mantine components or features, you MUST refer to the official AI-optimized documentation.
  • URL: https://mantine.dev/llms.txt
  • Use the WebFetch tool to retrieve the latest patterns and examples from this URL if you are unsure about the implementation details or best practices for the current version.