vue-ts-example/.github/copilot-instructions.md

Project Conventions and Technical Guidelines

This document outlines the core technical choices, coding conventions, and configuration details for this project. Adhering to these guidelines ensures consistency and leverages the project's setup effectively.

🚀 Core Technologies & Conventions

• Framework: Vue 3
• Language: TypeScript
• API Style: Strictly use the Composition API with <script setup> syntax. The Options API and the standard <script> block with the setup() function are not used in this project.
• Single File Component (SFC) Structure: Follow this order within .vue files:
  1. <script setup lang="ts"> (Imports, logic, composables, etc.)
  2. <template> (HTML structure)
  3. <style> (Preferably <style scoped>)
• Code Comments: All comments within the codebase must be written in Chinese. (代码中的所有注释必须使用中文。) 注释应解释代码的“为什么”或复杂逻辑，而不是解释“是什么”或重复代码/配置本身。

📦 UI Libraries & Components

• UI Libraries: This project utilizes both Ant Design Vue and PrimeVue.
• Component Auto-Import: Components from Ant Design Vue, PrimeVue, and those defined in src/components/**/*.vue (excluding filenames starting with __) are automatically imported via unplugin-vue-components.
  • Ant Design Vue: Use components directly (e.g., <a-button>, <a-table>). Icons are also resolved (e.g., <UserOutlined />). CSS-in-JS is used; no manual style import is needed.
  • PrimeVue: Use components directly with their standard names (e.g., <Button>, <InputText>, <DataTable>).
  • Custom Components: Local components (e.g., <MyCustomComponent /> defined in src/components/MyCustomComponent.vue) should be used directly in templates without explicit imports in <script setup>.
• Custom Icons: Custom SVG icons are available via unplugin-icons with the prefix icon-. Usage: <icon-your-svg-file-name />.
• No Auto-Import Comments for Components: When using auto-imported components (UI libraries, local components), do not add comments indicating they are auto-imported. Assume this behavior is known.

✨ API Auto-Import (unplugin-auto-import)

• Automatic API Availability: This project leverages unplugin-auto-import extensively. APIs from the following libraries/modules are globally available and SHOULD NOT be explicitly imported in <script setup> blocks unless necessary for specific type augmentation or rare cases:
  • vue (e.g., ref, computed, watch, onMounted, defineProps, defineEmits, etc.)
  • pinia (e.g., defineStore, storeToRefs)
  • vue-router/auto (e.g., useRouter, useRoute, useLink) - Provided by unplugin-vue-router integration.
  • @vueuse/core (Common utility functions)
  • vue-i18n (e.g., useI18n)
  • consola/browser (Available as the consola global for logging)
• Auto-Imported Directories: All exports from files within src/stores/** and src/utils/** are also auto-imported globally. Functions, variables, or stores defined and exported in these directories can be used directly without explicit import statements.
• Template Usage: Auto-import functionality also applies within the <template> block where appropriate (e.g., accessing store state or using certain utility functions directly).
• Important: Rely on the auto-import mechanism for the specified libraries and directories. Explicitly importing these APIs clutters the code unnecessarily.
• No Auto-Import Explanation Comments: When using auto-imported APIs (from libraries like Vue, Pinia, VueUse, or custom directories like src/utils, src/stores), simply use them directly. Absolutely avoid adding comments that merely state an item is auto-imported (e.g., DO NOT add comments like "// xxx is auto-imported from src/utils"). Focus comments on explaining complex logic or intent.

✅ Summary of Key Rules & Conventions

• Always use <script setup lang="ts">.
• Composition API is the only accepted style.
• Code comments must be in Chinese and explain why/how, not what or the build system.
• Vue 3 Composition API, Pinia, Vue Router (auto), VueUse functions, consola, and exports from src/stores & src/utils are globally available via auto-import; do not import them explicitly.
• Ant Design Vue, PrimeVue, and local src/components components are auto-imported; use them directly in templates without explicit imports.
• Crucially: Do not add comments solely to explain that an API or component is auto-imported. Trust the auto-import setup.
• Use custom SVG icons via the <icon-name /> syntax.
• Maintain the specified SFC structure: <script setup>, <template>, <style>.

---

(Further details regarding state management patterns, routing configuration, specific linting rules, testing setup, or detailed coding style guides can be added to this document as needed.)