wefa-vue-cookbook

WeFa Vue Cookbook

This is the shared Vue skill for WeFa.

Use it in two situations:

1. In consuming Vue projects that use @nside/wefa.
2. Inside the WeFa vue/ package for the shared conventions that also apply to the library itself.

When the task is inside the WeFa vue/ package, pair this skill with wefa-vue-frontend, which is the maintainer skill for repo-specific export, docs, demo, generated-artifact, and quality-gate work.

Use this skill in two layers:

1. Keep this SKILL.md loaded for the always-on rules.
2. Load only the matching reference file when the task needs deeper checks.

Always-Loaded Rules

1. Treat @nside/wefa as a PrimeVue superset styled through Tailwind 4 with tailwindcss-primeui.
2. Follow the reuse hierarchy strictly: WeFa component/container -> PrimeVue composition -> native HTML fallback.
3. Start by mirroring the nearest existing local pattern before inventing a new abstraction, prop API, fetch flow, or styling approach.
4. Before adding helpers or infrastructure, check whether the current app, WeFa, or PrimeVue already provides the needed building block.
5. Keep user-facing text translated through i18n keys, including labels, placeholders, validation copy, aria-label, and title.
6. Prefer Tailwind utilities for routine styling. Use flex by default for layout, reach for grid when it clearly fits better, and do not add new CSS imports or routine <style> blocks.
7. For server state, prefer typedApiClient when an OpenAPI-generated callable exists, then apiClient for straightforward URL-based GET or POST flows, then direct TanStack Query hooks only when the wrappers cannot model the behavior cleanly, then raw axiosInstance only for lower-level infrastructure or non-query-managed calls.
8. TanStack Query already covers most fetch lifecycle, caching, retries, invalidation, and mutation state. Prefer built-in query and cache features over hand-rolled refs, watches, loading flags, or manual cache synchronization.
9. Treat TanStack query data as immutable. Copy it before binding to v-model or mutating it locally.
10. Put every changing query dependency into the query key, and avoid unwrapping reactive inputs too early if the query should react to them.
11. Parent components own external layout and sizing context. Reusable children should not assume fill behavior or decorative outer chrome unless that is part of their explicit contract.
12. When shared or public-facing behavior changes, update the surrounding tests, docs, and usage examples expected by that codebase.
13. Run the validation commands that match the host project and the risk of the change. If working inside the WeFa repo, wefa-vue-frontend adds the exact repo gate.