vue-ts-example-2025/AGENTS.md

AGENTS.md

This file provides guidance to AI when working with code in this repository.

Project Overview

Vue 3 TypeScript application with Vite.

Routing & Layouts

• File-based routing: Uses unplugin-vue-router with .page.vue and .page.md extensions in src/pages/
• Route naming: Converts to PascalCase (e.g., user-profile.page.vue → UserProfile)
• Layouts: vite-plugin-vue-meta-layouts with default layout base-layout/base-layout

Auto-Import Configuration

Multiple auto-import systems are active:

• Vue APIs: Core Vue, VueUse, Pinia, Vue Router, vue-i18n
• Components: Auto-registered from multiple UI libraries (Naive UI, PrimeVue)
• Icons: Uses unplugin-icons with icon- prefix; custom SVGs from src/assets/icons/svgs/ available via icon-svg:filename

IMPORTANT - Auto-Import Limitations:

• Dynamic components: Auto-imported components cannot be used with <component :is="..." /> syntax
  • ❌ Avoid: <component :is="icon-${name}" />
  • ✅ Use: <icon-foo v-if="condition" /> with v-if/v-else-if/v-else directives
• In TypeScript/TSX files: Auto-import does NOT work. You must explicitly import icons using the ~icons/ prefix:

  import IconMenuRounded from '~icons/material-symbols/menu-rounded';
  
  // Then use in JSX/TSX
  const menuOption = {
    icon: () => <IconMenuRounded />
  };
  

UI Component Libraries

Project has multiple UI frameworks configured:

• Naive UI
• PrimeVue:

Styling

• UnoCSS: Wind preset
• SCSS: Modern compiler API with global imports from @/styles/scss/global.scss

State Management

Pinia stores

Cloudflare Workers Integration

• Server entry: server/index.ts handles /api/* routes with KV storage
• KV binding: Named KV

Vite Plugins (notable)

• vue-macros: Enhanced Vue features
• unplugin-vue-markdown: .md files as Vue components with frontmatter

Path Aliases

• @/ maps to src/ directory