AGENTS.md

AI/Agent Instructions for bakir.dev

Project Overview

• Framework: Next.js 16 (App Router) with React 19.
• Styling: Tailwind CSS 4.
  • Plugins Active: @tailwindcss/typography, tailwindcss-motion, tailwindcss-intersect, tw-animate-css.
• UI Components:
  • Shadcn UI (located in src/shadcn/components/ui).
  • Hugeicons (via @hugeicons/react and @hugeicons/core-free-icons).
  • Base UI (@base-ui/react).
• Content: MDX-based blog posts located in BLOG/ (aliased as &/*).
• Tooling: Biome for linting and formatting, pnpm for package management.

Architecture & Patterns

• Feature-Based Components: Domain-specific components go in src/features (e.g., Navbar, Footer).
• Pages: Follow Next.js App Router conventions in src/app.
• Blog Architecture:
  • Content: MDX files in BLOG/.
  • Routes: src/app/blog.
  • Metadata: Registered in blogs array in src/lib/blogs.ts. Only title, published, slug, and description are used.
  • Components: Custom MDX components (like A, Pre) in src/features/MDX mapped via src/mdx-components.tsx.
• Type Safety:
  • Env Vars: Validated and strongly typed in src/types/env.ts.
  • JSON-LD: Typed using schema-dts in src/features/JsonLD/JsonLD.tsx.

Coding Conventions

• Linting/Formatting: Use Biome. Run pnpm lint to fix issues and format files.
• TypeScript: Strict type checking is enforced. Run pnpm tsc to verify types.
• Path Aliases:
  • @/* → src/* (Application code)
  • #/* → public/* (Static assets)
  • &/* → BLOG/* (Blog content)
• Styling:
  • Use the cn() utility from @/shadcn/lib/utils for merging classes only in conditional scenarios.
  • Use Tailwind 4 features (CSS variables, @theme blocks in CSS) as present in src/css/global.css.

Specific Implementation Patterns

Environment Variables

Environment variables are strictly validated and typed using zod in src/types/env.ts.

• Validation: Variables are checked at runtime/build time using envVarsSchema.parse(process.env).
• Typing: process.env is augmented via declare global to provide autocomplete and type safety.
• Guarantee: You can assume all variables defined in src/types/env.ts are present and valid (e.g., URLs are valid URLs, Emails are valid emails). If they are missing, the build will fail explicitly.

Icons

Use Hugeicons with the wrapper component pattern:

import { Home01Icon } from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";

  <HugeiconsIcon icon={Home01Icon} />

Layout

Main content is wrapped in a container structure. Refer to src/app/layout.tsx or page wrappers:

<div className="container mx-auto px-4 min-h-dvh flex flex-col">{children}</div>

Critical Workflows

• Development: pnpm dev:clean (deletes .next directory to prevent errors and ensure a clean start).
• Linting: pnpm lint (performs formatting and linting).
• Type Check: pnpm tsc (verifies types).
• Build: pnpm build:clean (deletes .next directory to prevent errors and ensure a clean start).
• Clean Install: pnpm install:clean (removes node_modules and pnpm lockfile).

Deployment & Infrastructure

• Hosting: Custom VPS hosting using Dokploy.
• Docker: Dockerfile is used for the production build.
• Testing: Out of scope. No tests are implemented or required.

Integration Points

• MDX: Configured in next.config.ts using @next/mdx with remark-gfm.
• Google Analytics: Configured in root layout via @next/third-parties/google.