unboundedpress/AGENTS.md

Agent Guidelines for Unboundedpress Dev

Project Overview

This repository contains two main projects:

• portfolio-nuxt/ - Primary Nuxt 3 application (Vue 3, TypeScript, Tailwind CSS, Pinia)
• portfolio/ - Legacy Express.js application (plain JavaScript)

The Nuxt project is the main focus for development.

Build Commands

portfolio-nuxt (Primary Project)

cd portfolio-nuxt
npm install    # Install dependencies
npm run dev    # Development server
npm run build  # Build for production
npm run generate   # Generate static site
npm run preview    # Preview production build

portfolio (Legacy Project)

cd portfolio/src
npm run serve  # Development with nodemon
npm run format # Format code

Running a Single Test

No test framework is currently configured. If you add tests:

• For Nuxt: Use Vitest
• Run a single test: npx vitest run --testNamePattern="test name"

Code Style Guidelines

General Principles

• Use TypeScript in Vue components (.vue with <script setup lang="ts">)
• Use JavaScript (.js) in Pinia stores under stores/
• Follow Vue 3 Composition API with <script setup>
• Use Tailwind CSS classes for styling

TypeScript Conventions

• Use defineProps and defineEmits with type-based syntax
• Use withDefaults for optional props with default values
• Prefer ref and reactive from Vue
• Use toRefs when destructuring props

const props = withDefaults(
  defineProps<{
    modelValue?: boolean
    persistent?: boolean
  }>(),
  {
    modelValue: false,
    persistent: false,
  },
)

const emit = defineEmits<{
  (e: 'update:modelValue', value: boolean): void
}>()

Vue Component Structure

1. <script setup lang="ts"> - Logic (imports, props, emits, composables)
2. <template> - Template with slots
3. <style> - Scoped styles (if needed, Tailwind preferred)

Imports

• Use @/ alias for imports (configured in Nuxt)
• Import Vue core: import { ref, watch } from 'vue'
• Import from stores: import { useModalStore } from '@/stores/ModalStore'
• Import icons: import Icon from 'nuxt-icon' or <Icon name="..." /> in template

File Naming

• Vue components: PascalCase (e.g., IconButton.vue, Modal.vue)
• Component folders: PascalCase with index.vue (e.g., components/Modal/)
• Stores: PascalCase with Store suffix (e.g., AudioPlayerStore.js, ModalStore.js)
• Pages: kebab-case (e.g., index.vue, about-us.vue)

Tailwind CSS

• Use utility classes for all styling
• Follow existing patterns in components (see components/Modal/Modal.vue)
• Use bg-, text-, p-, m-, flex-, grid- prefixes

State Management (Pinia)

• Create stores in stores/ directory
• Use JavaScript (.js) for stores
• Follow the pattern in stores/ModalStore.js:

import { defineStore } from "pinia"

export const useModalStore = defineStore("ModalStore", {
  state: () => ({ key: "value" }),
  actions: {
    setKey(value) {
      this.key = value
    }
  }
})

API Data Fetching

• Use Nuxt's useFetch and useAsyncData composables
• Transform data in the transform option

const { data: works } = await useFetch('https://unboundedpress.org/api/works', {
  transform: (works) => {
    // transformation logic
    return transformedData
  }
})

Error Handling

• Handle null/undefined values in templates with v-if guards
• Use optional chaining (?.) when accessing nested properties
• Validate URLs before using them (see pattern in pages/index.vue)

Head Management

Use useHead for SEO metadata:

useHead({
  titleTemplate: 'Site Title - %s'
})

Transition and Animation

• Use Vue's built-in <Transition> and <TransitionRoot> components
• Use Headless UI for complex components (already installed)

Additional Conventions

Composables

• Place reusable logic in composables/ directory
• Use the use prefix (e.g., useModal)

Server Routes

• Place API routes in server/api/ directory
• Use .ts files for TypeScript routes

Image Handling

• Use <NuxtImg> component for optimized images
• Configure domains in nuxt.config.ts under image.domains

Environment Variables

• Use .env files for local development
• Template available in .env_template
• Never commit secrets to version control

Docker

• Dockerfile provided for deployment
• Multi-stage build available in Dockerfile_upgrade