portfolio/AGENTS.md

AGENTS.md - Agent Coding Guidelines

This document provides guidelines for agents working on this codebase.

Project Overview

• Framework: Nuxt 3 (Vue 3)
• Styling: Tailwind CSS
• State Management: Pinia
• UI Components: Headless UI + Nuxt Icon
• Image Handling: @nuxt/image
• TypeScript: Enabled (tsconfig extends .nuxt/tsconfig.json)
• Storybook: Available for component documentation

Build Commands

# Development
npm run dev              # Start development server
npm run build            # Build for production
npm run generate         # Generate static site (SSG)
npm run preview          # Preview production build

# No test framework configured

Code Style Guidelines

General Conventions

• Use Vue 3 Composition API with <script setup lang="ts">
• TypeScript is preferred for new files; stores use JavaScript (.js)
• Follow Nuxt 3 auto-import conventions (no explicit imports for composables, components, etc.)

File Organization

/pages/          - Page components (file-based routing)
/components/     - Vue components (auto-imported)
/layouts/        - Layout components
/server/api/     - Server API routes (Nitro)
/stores/         - Pinia stores (.js files)
/assets/         - Static assets
/public/         - Public static files

Naming Conventions

• Components: PascalCase (e.g., Modal.vue, IconButton.vue)
• Files: kebab-case for pages, PascalCase for components
• Stores: CamelCase (e.g., ModalStore.js, AudioPlayerStore.js)
• Props/Emits: camelCase

Component Patterns

<script setup lang="ts">
// Use withDefaults for optional props
const props = withDefaults(
  defineProps<{
    modelValue?: boolean
    persistent?: boolean
  }>(),
  {
    modelValue: false,
    persistent: false,
  },
)

// Use type-only emits
const emit = defineEmits<{
  (e: 'update:modelValue', value: boolean): void
}>()

// Use toRefs for reactive destructuring
const { modelValue } = toRefs(props)
</script>

<template>
  <!-- Template content -->
</template>

Tailwind CSS

• Use Tailwind utility classes for all styling
• Common classes used: flex, grid, fixed, relative, z-*, p-*, m-*, text-*, etc.

API Routes (Server)

// server/api/example.ts
export default defineEventHandler((event) => {
  // Handle request and return data
})

Store Patterns (Pinia)

// stores/ExampleStore.js
import { defineStore } from "pinia"

export const useExampleStore = defineStore("ExampleStore", {
  state: () => ({ count: 0 }),
  actions: {
    increment() {
      this.count++
    }
  }
})

Error Handling

• Use try/catch in API routes
• Return appropriate HTTP status codes
• Handle undefined/null values gracefully

Imports

• Vue/composables: Use Nuxt auto-imports (no import needed)
• External modules: Explicit import
• Server-only: Place in /server/ directory
• Path aliases: @/ maps to project root

Additional Notes

• Project uses Storybook (.stories.ts files) for component documentation
• Environment variables should use .env files (not committed)
• Image domains configured for unboundedpress.org in nuxt.config.ts