RFC: Standardize Vue 3 & TS development patterns in AGENTS.md#4865
RFC: Standardize Vue 3 & TS development patterns in AGENTS.md#4865Erics1337 wants to merge 1 commit intobetaflight:masterfrom
Conversation
This RFC proposes adopting standard development instructions for AI agents and developers to support the incremental migration to Vue 3 and TypeScript. Key points: - Incremental adoption of TypeScript (mix of JS/TS allowed). - Strict adherence to Single File Components (SFC) for all new styles. - Generic `AGENTS.md` location for broad tool compatibility (Windsurf, etc.). Based on github/awesome-copilot instructions but adapted for the current codebase state.
WalkthroughA new documentation file introducing Vue.js 3 development standards and RFC-style guidelines covering architecture, TypeScript integration, component design, state management, testing practices, security, and accessibility protocols. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
|
🎉 Do you want to test this code? 🎉 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In `@AGENTS.md`:
- Line 63: Remove the Nuxt-specific mention of useAsyncData from the AGENTS.md
recommendation: clarify that the project uses Vite + Vue 3 and that useAsyncData
is not available here, and either delete the suggestion "Use `useAsyncData` or
third-party data utilities (Vue Query)" or replace it with a Vite-appropriate
alternative (e.g., recommend using Vue Query, plain fetch with reactive state,
or other composables) and add a note that useAsyncData only applies if migrating
to Nuxt (reference symbols: useAsyncData, Vue Query).
- Line 102: Replace the specific library recommendation ("VeeValidate" and
"@vueuse/form") in the AGENTS.md line that suggests declarative validation with
a generic guidance phrase; update the sentence to something like "Use validation
libraries or build custom validation composables for declarative validation" so
it no longer prescribes unadopted dependencies and avoids encouraging adding
VeeValidate or `@vueuse/form` to the project.
- Line 86: Remove the framework-specific suggestion "useFetch" and the unrelated
"Vue Query" reference and replace with guidance to either implement a
project-specific data-fetching composable (e.g., a custom useFetch built with
the Vue 3 Composition API and the browser Fetch API) or explicitly pick and
document a supported library (name it and add installation/usage notes). Update
the AGENTS.md entry that currently mentions `useFetch` and `Vue Query` to
describe building a custom composable (Composition API + Fetch API) or to state
which third‑party library the project will use, including brief setup and where
to find example usage.
- Around line 117-124: Update the "Testing" section to remove or clearly mark as
optional any tools not present in the repo: remove explicit prescriptive
references to "Cypress", "Playwright", and "axe-core" (or add a note that they
are optional external tools not configured here), and instead state that
"Vitest" is the project's configured test runner and give guidance to write unit
tests with Vue Test Utils and Vitest, mock global plugins (router, Pinia), and
optionally mention end-to-end/accessibility tools as alternatives only if the
developer adds them.
- Line 42: Update the guideline sentence in AGENTS.md that currently says "Use
PascalCase for component names and kebab-case for file names" to recommend
PascalCase for both component names and file names to match the codebase
convention (47 PascalCase Vue component files); ensure the line explicitly
states "Use PascalCase for component names and file names" and adjust any brief
explanatory note to reflect the existing project standard.
🧹 Nitpick comments (3)
AGENTS.md (3)
1-173: Consider adding a dedicated "Migration Strategy" section.While this RFC provides excellent standards for Vue 3 + TypeScript development, it could benefit from a dedicated section on migration strategy that addresses:
JS to TS Migration Path:
- When to add JSDoc annotations vs. full TypeScript conversion
- How to gradually type existing modules
- Handling type inference and
anytypes during transitionOptions API to Composition API Migration:
- Step-by-step conversion patterns
- Handling lifecycle hooks, computed properties, watchers
- Converting mixins to composables
Global to Scoped Styles Migration:
- Identifying global style dependencies
- Extracting component-specific styles
- Handling shared design tokens
Testing During Migration:
- Ensuring behavioral equivalence
- Regression testing strategy
- Incremental testing approach
This would make the document more actionable for developers actively migrating components.
32-32: Clarify mechanism for enabling strict mode on new files only.The guidance to "Enable
strictmode intsconfig.jsonfor new parts of the codebase" needs clarification. TypeScript's strict mode is typically project-wide. Consider specifying the intended approach:
- Option 1: Use per-file
//@ts-checkand `// `@ts-strictdirectives- Option 2: Create separate
tsconfigfiles with different strict settings for new vs. legacy code- Option 3: Use ESLint rules to enforce stricter checking on new files
This clarification will help developers implement the incremental TypeScript adoption correctly.
75-140: Consider marking advanced topics as "Future Considerations."The sections on Performance Optimization, Error Handling, Security, and Accessibility (lines 75-140) contain valuable best practices but may be too prescriptive for an incremental migration RFC. Consider:
- Restructuring these as "Advanced Topics" or "Future Enhancements" to distinguish them from core migration requirements
- Removing tool-specific recommendations (e.g., Sentry/LogRocket on line 98) unless they're actively being adopted
- Focusing the main RFC on migration essentials: TypeScript adoption, Composition API, scoped styles, and Pinia state management
This would keep the RFC focused on actionable migration guidance while preserving these best practices as aspirational goals.
| ### Component Design | ||
|
|
||
| - Adhere to the single responsibility principle for components | ||
| - Use PascalCase for component names and kebab-case for file names |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check naming conventions of existing .vue files
echo "=== PascalCase .vue files (examples) ==="
fd -e vue -x basename {} | grep -E '^[A-Z][a-zA-Z0-9]*\.vue$' | sort | head -20
echo -e "\n=== kebab-case .vue files (examples) ==="
fd -e vue -x basename {} | grep -E '^[a-z][a-z0-9-]*\.vue$' | sort | head -20
echo -e "\n=== Count by convention ==="
pascal_count=$(fd -e vue -x basename {} | grep -cE '^[A-Z][a-zA-Z0-9]*\.vue$')
kebab_count=$(fd -e vue -x basename {} | grep -cE '^[a-z][a-z0-9-]*\.vue$')
echo "PascalCase: $pascal_count"
echo "kebab-case: $kebab_count"
echo -e "\n=== All .vue files (for reference) ==="
fd -e vue -x basename {} | sortRepository: betaflight/betaflight-configurator
Length of output: 1406
Update AGENTS.md guideline to match the actual codebase convention.
The project uses PascalCase for all Vue component file names (47 components, 0 kebab-case files). Line 42 should recommend PascalCase instead of kebab-case to align with the existing codebase standard.
🤖 Prompt for AI Agents
In `@AGENTS.md` at line 42, Update the guideline sentence in AGENTS.md that
currently says "Use PascalCase for component names and kebab-case for file
names" to recommend PascalCase for both component names and file names to match
the codebase convention (47 PascalCase Vue component files); ensure the line
explicitly states "Use PascalCase for component names and file names" and adjust
any brief explanatory note to reflect the existing project standard.
| - Use `watch` and `watchEffect` with precise dependency lists | ||
| - Cleanup side effects in `onUnmounted` or `watch` cleanup callbacks | ||
| - Use `provide`/`inject` sparingly for deep dependency injection | ||
| - Use `useAsyncData` or third-party data utilities (Vue Query) |
There was a problem hiding this comment.
Remove Nuxt-specific reference in Vite-based project.
useAsyncData is a Nuxt-specific composable and won't be available in a Vite-based Vue 3 project (as indicated on line 15). Consider removing this reference or clarifying that it's only applicable if migrating to Nuxt in the future.
📝 Suggested fix
-- Use `useAsyncData` or third-party data utilities (Vue Query)
+- Use third-party data utilities like Vue Query (TanStack Query)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Use `useAsyncData` or third-party data utilities (Vue Query) | |
| - Use third-party data utilities like Vue Query (TanStack Query) |
🤖 Prompt for AI Agents
In `@AGENTS.md` at line 63, Remove the Nuxt-specific mention of useAsyncData from
the AGENTS.md recommendation: clarify that the project uses Vite + Vue 3 and
that useAsyncData is not available here, and either delete the suggestion "Use
`useAsyncData` or third-party data utilities (Vue Query)" or replace it with a
Vite-appropriate alternative (e.g., recommend using Vue Query, plain fetch with
reactive state, or other composables) and add a note that useAsyncData only
applies if migrating to Nuxt (reference symbols: useAsyncData, Vue Query).
|
|
||
| ### Data Fetching | ||
|
|
||
| - Use composables like `useFetch` (Nuxt) or libraries like Vue Query |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check for data fetching library dependencies and useFetch usage
echo "=== Checking package.json for data fetching libraries ==="
if [ -f "package.json" ]; then
cat package.json | jq '.dependencies, .devDependencies' 2>/dev/null | grep -iE "(vue-query|tanstack|axios|usefetch)" || echo "No matches found in dependencies"
else
echo "package.json not found"
fi
echo -e "\n=== Checking for custom useFetch composables ==="
rg "useFetch" --type=ts --type=js -g '!node_modules' -C2 2>/dev/null || echo "No useFetch found"
echo -e "\n=== Full package.json dependencies ==="
if [ -f "package.json" ]; then
cat package.json | jq '.dependencies, .devDependencies' 2>/dev/null
fiRepository: betaflight/betaflight-configurator
Length of output: 2472
🏁 Script executed:
# Check AGENTS.md file context around line 86
echo "=== AGENTS.md file content around line 86 ==="
if [ -f "AGENTS.md" ]; then
sed -n '75,95p' AGENTS.md
else
echo "AGENTS.md not found"
fiRepository: betaflight/betaflight-configurator
Length of output: 1004
🏁 Script executed:
# Check for Nuxt usage in the project
echo "=== Checking for Nuxt framework references ==="
rg "nuxt|@nuxtjs" --type=ts --type=js --type=json -g '!node_modules' 2>/dev/null || echo "No Nuxt references found"
echo -e "\n=== Check if project uses Vue 3 setup ==="
rg "vue" package.json | head -5Repository: betaflight/betaflight-configurator
Length of output: 417
Remove framework-specific references from data fetching guidance.
The reference to useFetch (Nuxt) does not apply to this Vite + Vue 3 project, and Vue Query is not in the project dependencies. Update the guidance to either recommend building custom useFetch composables using the Composition API and Fetch API, or adopt a specific data fetching library and document that choice explicitly.
🤖 Prompt for AI Agents
In `@AGENTS.md` at line 86, Remove the framework-specific suggestion "useFetch"
and the unrelated "Vue Query" reference and replace with guidance to either
implement a project-specific data-fetching composable (e.g., a custom useFetch
built with the Vue 3 Composition API and the browser Fetch API) or explicitly
pick and document a supported library (name it and add installation/usage
notes). Update the AGENTS.md entry that currently mentions `useFetch` and `Vue
Query` to describe building a custom composable (Composition API + Fetch API) or
to state which third‑party library the project will use, including brief setup
and where to find example usage.
|
|
||
| ### Forms and Validation | ||
|
|
||
| - Use libraries like VeeValidate or @vueuse/form for declarative validation |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check for form validation library dependencies and usage
echo "=== Checking package.json for form validation libraries ==="
if [ -f "package.json" ]; then
cat package.json | jq -r '.dependencies, .devDependencies // empty | to_entries[]? | select(.key | test("vee-validate|vueuse|yup|zod|joi")) | "\(.key): \(.value)"' 2>/dev/null || echo "No matching dependencies found"
else
echo "package.json not found"
fi
echo -e "\n=== Checking for VeeValidate/form validation imports ==="
rg "VeeValidate|from ['\"]vee-validate|from ['\"]@vueuse/form" -i --type vue --type js --type ts -g '!node_modules' 2>/dev/null || echo "No VeeValidate imports found"
echo -e "\n=== Checking AGENTS.md for context ==="
sed -n '95,110p' AGENTS.md 2>/dev/null || echo "Could not read AGENTS.md"Repository: betaflight/betaflight-configurator
Length of output: 921
Use generic validation guidance instead of prescribing unadopted libraries.
VeeValidate and @vueuse/form are not present in the project's dependencies and have no usage in the codebase. Replace the specific library recommendation with generic guidance such as: "Use validation libraries or build custom validation composables for declarative validation" to avoid misleading developers into adding unnecessary dependencies.
🤖 Prompt for AI Agents
In `@AGENTS.md` at line 102, Replace the specific library recommendation
("VeeValidate" and "@vueuse/form") in the AGENTS.md line that suggests
declarative validation with a generic guidance phrase; update the sentence to
something like "Use validation libraries or build custom validation composables
for declarative validation" so it no longer prescribes unadopted dependencies
and avoids encouraging adding VeeValidate or `@vueuse/form` to the project.
| ### Testing | ||
|
|
||
| - Write unit tests with Vue Test Utils and Vitest | ||
| - Focus on behavior, not implementation details | ||
| - Use `mount` and `shallowMount` for component isolation | ||
| - Mock global plugins (router, Pinia) as needed | ||
| - Add end-to-end tests with Cypress or Playwright | ||
| - Test accessibility using axe-core integration |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check for testing framework dependencies and configuration
echo "=== Checking package.json for testing libraries ==="
if [ -f "package.json" ]; then
cat package.json | jq '.dependencies, .devDependencies' 2>/dev/null | grep -iE "(vitest|jest|cypress|playwright|mocha|axe|testing-library)" || echo "No matches found in package.json"
else
echo "package.json not found"
fi
echo -e "\n=== Checking for test configuration files ==="
fd -t f "(vitest|vite|cypress|playwright|jest|mocha)\.config\.(ts|js|mjs)" -d 2 2>/dev/null || echo "No test config files found"
echo -e "\n=== Checking for test files ==="
fd -e spec.ts -e spec.js -e test.ts -e test.js 2>/dev/null | head -20 || echo "No test files found"
echo -e "\n=== Full package.json devDependencies ==="
if [ -f "package.json" ]; then
cat package.json | jq '.devDependencies' 2>/dev/null
fiRepository: betaflight/betaflight-configurator
Length of output: 1611
Remove or clarify testing tools not in the project setup.
The document prescribes Cypress, Playwright, and axe-core, but these tools are not in the project's devDependencies. Only Vitest is actually configured and available. Remove references to unavailable tools or clarify they are optional alternatives not set up in the project. If applicable, update the testing guidance to reflect what's actually installed (Vitest).
🤖 Prompt for AI Agents
In `@AGENTS.md` around lines 117 - 124, Update the "Testing" section to remove or
clearly mark as optional any tools not present in the repo: remove explicit
prescriptive references to "Cypress", "Playwright", and "axe-core" (or add a
note that they are optional external tools not configured here), and instead
state that "Vitest" is the project's configured test runner and give guidance to
write unit tests with Vue Test Utils and Vitest, mock global plugins (router,
Pinia), and optionally mention end-to-end/accessibility tools as alternatives
only if the developer adds them.
1 participant
This RFC proposes adding
AGENTS.mdto standardise development instructions for AI agents and human developers.Why is this needed?
The codebase is undergoing a significant migration to Vue 3 and incrementally adopting TypeScript. Without standardized instructions:
Research & Current State
Based on a scan of the codebase:
OsdTab.vueuse<style scoped>(Good, enforced in RFC).<script setup>is widely used in new components (Good, enforced).fc.jsstore structure matches Pinia pattern).Recommendation: JSDoc for Incremental Migration
To facilitate a smooth transition to TypeScript without breaking existing workflows:
.tsimmediately. Instead, add JSDoc annotations (@param,@returns,@type) to exported functions and complex logic. This provides immediate type checking and IDE support..tsor<script setup lang="ts">).Content
AGENTS.mdin root for compatibility with Windsurf, Copilot, etc.Feedback welcome on the proposed standards.
Summary by CodeRabbit