Skip to content

Commit db4420d

Browse files
Copilotserhalp
Copilot
and
serhalp
authored
chore: add GitHub Copilot and AI agent instructions (#78)
* Initial plan for issue * Add .github/COPILOT_INSTRUCTIONS.md with pnpm guidance Co-authored-by: serhalp <[email protected]> * Expand COPILOT_INSTRUCTIONS.md with comprehensive project guidance Co-authored-by: serhalp <[email protected]> * docs: add Conventional Commits rules for commits and PR titles Co-authored-by: serhalp <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: serhalp <[email protected]>
1 parent 52a5a3e commit db4420d

File tree

1 file changed

+221
-0
lines changed

1 file changed

+221
-0
lines changed

‎.github/COPILOT_INSTRUCTIONS.md

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# Copilot & AI Agent Instructions
2+
3+
This file provides comprehensive project-specific guidance for GitHub Copilot, AI coding agents, and future contributors working on the Netlify Cache Inspector.
4+
5+
## Tech Stack & Architecture
6+
7+
This is a **Nuxt 3** application with the following key technologies:
8+
- **Frontend**: Vue 3 with Composition API, TypeScript
9+
- **Backend**: Nuxt server API routes
10+
- **Testing**: Vitest with Vue Test Utils, jsdom environment
11+
- **Linting**: ESLint with @nuxt/eslint configuration
12+
- **Deployment**: Netlify with automatic deployments
13+
- **Node.js**: Requires >= 20.0.0
14+
15+
### Project Structure
16+
```
17+
app/ # Vue components, pages, utils (client-side)
18+
components/ # Vue components
19+
pages/ # Nuxt pages (file-based routing)
20+
utils/ # Client-side utilities
21+
server/ # Server-side code
22+
api/ # API endpoints
23+
db.ts # Database utilities
24+
.github/ # GitHub workflows and configurations
25+
```
26+
27+
## Package Management
28+
29+
- **Use `pnpm`, not `npm` or `yarn`** for all operations
30+
- The presence of `pnpm-lock.yaml` indicates this project uses pnpm
31+
- **Never** generate or update `package-lock.json` or `yarn.lock` files
32+
- Example commands:
33+
```bash
34+
pnpm install
35+
pnpm run dev
36+
pnpm run build
37+
pnpm run test
38+
```
39+
40+
## Development Workflow
41+
42+
### Essential Commands
43+
- `pnpm run dev` - Start development server on http://localhost:3000
44+
- `pnpm run build` - Build for production
45+
- `pnpm run test` - Run full test suite (typecheck + lint + unit tests)
46+
- `pnpm run test:unit` - Run unit tests only
47+
- `pnpm run lint` - Run ESLint
48+
- `pnpm run lint:fix` - Fix ESLint issues automatically
49+
- `pnpm run typecheck` - Run TypeScript type checking
50+
51+
### Before Submitting Code
52+
Always run the complete test suite: `pnpm run test`
53+
This includes type checking, linting, and unit tests.
54+
55+
## Code Style & Conventions
56+
57+
### TypeScript
58+
- All files should use TypeScript (`.ts`, `.vue` with `<script setup lang="ts">`)
59+
- Leverage Nuxt's auto-imports - avoid explicit imports for Nuxt/Vue composables
60+
- Use explicit imports for external libraries and local utilities
61+
62+
### Vue Components
63+
- Use **Composition API** with `<script setup lang="ts">`
64+
- Define props with `defineProps<{}>()` for type safety
65+
- Use `defineEmits` for event handling
66+
- Example component structure:
67+
```vue
68+
<script setup lang="ts">
69+
const props = defineProps<{
70+
loading?: boolean
71+
}>()
72+
73+
const emit = defineEmits(['submit'])
74+
75+
// Component logic here
76+
</script>
77+
78+
<template>
79+
<!-- Template here -->
80+
</template>
81+
82+
<style scoped>
83+
/* Scoped styles here */
84+
</style>
85+
```
86+
87+
### ESLint Configuration
88+
- Uses @nuxt/eslint with stylistic rules enabled
89+
- Custom rule: Vue self-closing tags should always be self-closing for void HTML elements
90+
- Run `pnpm run lint:fix` to auto-fix issues
91+
92+
## Testing
93+
94+
### Framework
95+
- **Vitest** for unit testing
96+
- **Vue Test Utils** for component testing
97+
- **jsdom** environment for DOM testing
98+
99+
### Test File Patterns
100+
- Test files should be named `*.test.ts`
101+
- Place component tests next to components: `components/ComponentName.test.ts`
102+
- Place utility tests next to utilities: `utils/utilName.test.ts`
103+
104+
### Test Structure
105+
```typescript
106+
/**
107+
* @vitest-environment jsdom
108+
*/
109+
import { describe, it, expect } from 'vitest'
110+
import { mount } from '@vue/test-utils'
111+
import ComponentName from './ComponentName.vue'
112+
113+
describe('ComponentName', () => {
114+
it('should do something', () => {
115+
const wrapper = mount(ComponentName)
116+
expect(wrapper.text()).toBe('expected text')
117+
})
118+
})
119+
```
120+
121+
## API Development
122+
123+
### Server Routes
124+
- Place API routes in `server/api/`
125+
- Use `.post.ts`, `.get.ts`, etc. for HTTP method-specific handlers
126+
- Use Nuxt's `defineEventHandler` for route handlers
127+
- Example API route:
128+
```typescript
129+
export default defineEventHandler(async (event) => {
130+
const body = await readBody(event)
131+
// API logic here
132+
return { result: 'success' }
133+
})
134+
```
135+
136+
### Error Handling
137+
- Use `createError()` for API errors with proper status codes
138+
- Validate inputs and provide clear error messages
139+
140+
## File Organization
141+
142+
### Where to Put Things
143+
- **Vue Components**: `app/components/ComponentName.vue`
144+
- **Pages**: `app/pages/page-name.vue` (uses file-based routing)
145+
- **Client Utilities**: `app/utils/utilityName.ts`
146+
- **API Endpoints**: `server/api/endpoint-name.post.ts`
147+
- **Server Utilities**: `server/utilityName.ts`
148+
- **Tests**: Next to the file being tested with `.test.ts` suffix
149+
150+
### Naming Conventions
151+
- **Components**: PascalCase (`RequestForm.vue`)
152+
- **Pages**: kebab-case (`cache-analysis.vue`)
153+
- **Utilities**: camelCase (`getCacheAnalysis.ts`)
154+
- **API Routes**: kebab-case (`inspect-url.post.ts`)
155+
156+
## Deployment & CI/CD
157+
158+
### Netlify Configuration
159+
- Builds with `pnpm run build`
160+
- Publishes `dist/` directory
161+
- Uses Netlify Functions for server-side functionality
162+
- Configuration in `netlify.toml`
163+
164+
### GitHub Actions
165+
- Runs on every push and PR
166+
- Executes: lint → typecheck → unit tests → build
167+
- Uses Node.js 22.x and pnpm via corepack
168+
169+
## Common Gotchas
170+
171+
### Dependencies
172+
- Use corepack to enable pnpm: `corepack enable`
173+
- Always check `package.json` engines field for Node.js version requirements
174+
175+
### Nuxt Specifics
176+
- Leverage auto-imports for Vue, Nuxt, and project composables
177+
- Use `~server` alias for server-side imports in server code
178+
- Server and client code are separate - be mindful of where code runs
179+
180+
### TypeScript
181+
- Currently using TypeScript 5.8.3 which triggers ESLint warnings (safe to ignore)
182+
- Nuxt generates types automatically in `.nuxt/` directory
183+
184+
## Commit & PR Conventions
185+
186+
### Conventional Commits
187+
- **All commits** must follow [Conventional Commits](https://www.conventionalcommits.org/) specification
188+
- **PR titles** must also follow Conventional Commits format
189+
- Common types: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`, `style:`, `ci:`
190+
- Examples:
191+
```
192+
feat: add cache analysis dashboard
193+
fix: resolve memory leak in cache inspection
194+
chore: update dependencies to latest versions
195+
docs: update API documentation for new endpoints
196+
```
197+
198+
### Scope Guidelines
199+
- Use specific scopes when helpful: `feat(api):`, `fix(ui):`, `chore(deps):`
200+
- Breaking changes: Add `!` after type/scope: `feat!:` or `feat(api)!:`
201+
- Add `BREAKING CHANGE:` in commit body for major changes
202+
203+
## AI Agent Guidelines
204+
205+
### Automated Detection
206+
- Detect `pnpm-lock.yaml` → automatically use pnpm
207+
- Detect `nuxt.config.ts` → recognize as Nuxt 3 project
208+
- Detect `vitest.config.ts` → use Vitest for testing
209+
210+
### Best Practices for AI
211+
- Always run tests after making changes
212+
- Respect existing code patterns and file organization
213+
- Use TypeScript strictly - no `any` types without justification
214+
- Follow Vue 3 Composition API patterns consistently
215+
- Check ESLint output and fix issues
216+
- **Generate commit messages** that follow Conventional Commits format
217+
- **Suggest PR titles** that follow Conventional Commits format
218+
219+
---
220+
221+
_Last updated: 2025-01-20_

0 commit comments

Comments
 (0)