6.3 KiB

Raw Blame History

AGENTS.md

This file contains guidelines and commands for agentic coding agents working in this repository.

Build/Lint/Test Commands

# Development
npm run dev                    # Start development server (Next.js)

# Build & Production
npm run build                  # Build for production
npm run start                  # Start production server

# Code Quality
npm run lint                   # Run ESLint

Note: This project does not have test commands configured. If tests are added, update the scripts in package.json.

Project Architecture

This is a Next.js 16 application with TypeScript that serves as a dashboard for Dolibarr project management. The app uses:

UI Framework: shadcn/ui components with Radix UI primitives
Styling: Tailwind CSS with custom design system
State Management: React hooks and context
API Integration: Custom Dolibarr client
Icons: Lucide React

Code Style Guidelines

Imports & Dependencies

// 1. React imports first
import React from "react";
import { forwardRef } from "react";

// 2. Third-party libraries (alphabetical)
import { cva, type VariantProps } from "class-variance-authority";
import { Slot } from "@radix-ui/react-slot";

// 3. Internal imports (use @/ aliases)
import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import { Project } from "@/types/project";

Component Structure

"use client"; // Add for client components

// Imports
import { ComponentProps } from "react";

// Types/Interfaces
interface ComponentProps {
  // props here
}

// Helper functions (if any)
function helper() {
  // implementation
}

// Main component
export default function Component({ prop }: ComponentProps) {
  // implementation
}

TypeScript Guidelines

Always use types for props, function parameters, and return values
Prefer interfaces for object shapes, types for unions/primitives
Use generic types when appropriate: React.FC<Props>, VariantProps<T>
Strict mode enabled - no implicit any

Naming Conventions

Components: PascalCase (ProjectCard, DashboardHeader)
Functions: camelCase (getInitials, mapDolibarrProject)
Constants: UPPER_SNAKE_CASE (STATUS_CONFIG, API_BASE_URL)
Files: kebab-case (project-card.tsx, dolibarr-client.ts)
Types: PascalCase with descriptive suffixes (ProjectStatus, DolibarrProject)

shadcn/ui Component Patterns

// Use cva for variant styling
const buttonVariants = cva(
  "base-classes",
  {
    variants: {
      variant: {
        default: "variant-classes",
        // other variants
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
);

// Forward ref for composable components
const Component = forwardRef<HTMLDivElement, ComponentProps>(
  ({ className, ...props }, ref) => {
    return (
      <div
        className={cn(variantClasses, className)}
        ref={ref}
        {...props}
      />
    );
  }
);
Component.displayName = "Component";

Styling Guidelines

Use Tailwind classes for all styling
Utility-first approach - avoid custom CSS when possible
Responsive design: sm:, md:, lg:, xl: prefixes
State styling: hover:, focus:, disabled: prefixes
Use cn() utility for conditional class merging
Design tokens: Use CSS custom properties from globals.css

Error Handling

// API calls - throw errors, handle at call site
export async function apiCall() {
  const res = await fetch(url);
  if (!res.ok) {
    console.error("API Error:", res.status, await res.text());
    throw new Error("API request failed");
  }
  return res.json();
}

// Components - handle errors gracefully
try {
  const data = await apiCall();
  // render data
} catch (error) {
  console.error("Failed to load data:", error);
  // render error state or fallback
}

File Organization

src/
├── app/                 # Next.js app router
├── components/         # React components
│   ├── ui/            # shadcn/ui components
│   └── dashboard/     # Feature components
├── hooks/             # Custom React hooks
├── lib/               # Utilities, API clients
├── types/             # TypeScript type definitions
└── public/            # Static assets

Path Aliases

Use these configured path aliases:

@/components → ./components
@/lib → ./lib
@/hooks → ./hooks
@/utils → ./lib/utils
@/ui → ./components/ui

API Integration

Environment variables: Use NEXT_PUBLIC_* for client-side access
Dolibarr client: Use dolibarrFetch() from @/lib/dolibarrClient
Data transformation: Map API responses to UI types using helper functions
Error boundaries: Implement error handling for API failures

Performance Guidelines

Dynamic imports: Use next/dynamic for heavy components
Image optimization: Use Next.js Image component
Bundle analysis: Check bundle size with npm run build
Memoization: Use React.memo() for expensive components

Accessibility

Semantic HTML: Use appropriate elements (<button>, <nav>, etc.)
ARIA attributes: Add when needed for screen readers
Keyboard navigation: Ensure all interactive elements are keyboard accessible
Focus management: Handle focus in modals and dropdowns

Development Workflow

Start development: npm run dev
Run linter: npm run lint (fix any errors before committing)
Build test: npm run build (ensure production build works)
Type checking: TypeScript is strict - fix all type errors

Key Dependencies

Next.js: 16.0.7 (App Router)
React: 19.2.0
TypeScript: 5.x
Tailwind CSS: 3.4.18 + tailwindcss-animate
Radix UI: Headless components for accessibility
Lucide React: Icon library
shadcn/ui: Component library built on Radix UI

Environment Variables

Required environment variables (create .env.local):

NEXT_PUBLIC_API_URL - Dolibarr API base URL
NEXT_PUBLIC_DOLIBARR_API_KEY - Dolibarr API key

Testing

No test framework is currently configured. Recommended setup:

Add Jest/Vitest for unit tests
Add React Testing Library for component tests
Add Playwright/Cypress for E2E tests
Update package.json with test scripts

6.3 KiB Raw Blame History