From 3c62cc1cd16e965cb9ac1eecf8b819683af301b4 Mon Sep 17 00:00:00 2001 From: sexygoat <1538832180@qq.com> Date: Tue, 31 Mar 2026 18:41:52 +0800 Subject: [PATCH] first --- .agents/skills/antfu/SKILL.md | 222 + .../antfu/references/antfu-eslint-config.md | 328 + .../antfu/references/app-development.md | 60 + .../skills/antfu/references/github-actions.md | 68 + .agents/skills/antfu/references/gitignore.md | 29 + .../antfu/references/library-development.md | 85 + .agents/skills/antfu/references/monorepo.md | 126 + .../antfu/references/vscode-extensions.md | 34 + .agents/skills/pinia/GENERATION.md | 5 + .agents/skills/pinia/SKILL.md | 59 + .../skills/pinia/references/advanced-hmr.md | 61 + .../skills/pinia/references/advanced-nuxt.md | 119 + .../skills/pinia/references/advanced-ssr.md | 121 + .../best-practices-outside-component.md | 115 + .../references/best-practices-testing.md | 212 + .../skills/pinia/references/core-stores.md | 389 + .../pinia/references/features-composables.md | 114 + .../references/features-composing-stores.md | 134 + .../pinia/references/features-plugins.md | 203 + .agents/skills/pnpm/GENERATION.md | 5 + .agents/skills/pnpm/SKILL.md | 42 + .../pnpm/references/best-practices-ci.md | 285 + .../references/best-practices-migration.md | 291 + .../references/best-practices-performance.md | 284 + .agents/skills/pnpm/references/core-cli.md | 229 + .agents/skills/pnpm/references/core-config.md | 188 + .agents/skills/pnpm/references/core-store.md | 179 + .../skills/pnpm/references/core-workspaces.md | 205 + .../pnpm/references/features-aliases.md | 168 + .../pnpm/references/features-catalogs.md | 159 + .../skills/pnpm/references/features-hooks.md | 233 + .../pnpm/references/features-overrides.md | 184 + .../pnpm/references/features-patches.md | 201 + .../pnpm/references/features-peer-deps.md | 250 + .agents/skills/unocss/GENERATION.md | 5 + .agents/skills/unocss/SKILL.md | 64 + .../skills/unocss/references/core-config.md | 187 + .../unocss/references/core-extracting.md | 137 + .../skills/unocss/references/core-layers.md | 104 + .../skills/unocss/references/core-rules.md | 166 + .../skills/unocss/references/core-safelist.md | 105 + .../unocss/references/core-shortcuts.md | 89 + .../skills/unocss/references/core-theme.md | 172 + .../skills/unocss/references/core-variants.md | 175 + .../unocss/references/integrations-nuxt.md | 199 + .../unocss/references/integrations-vite.md | 283 + .../unocss/references/preset-attributify.md | 142 + .../skills/unocss/references/preset-icons.md | 184 + .../skills/unocss/references/preset-mini.md | 158 + .../unocss/references/preset-rem-to-px.md | 97 + .../skills/unocss/references/preset-tagify.md | 134 + .../unocss/references/preset-typography.md | 95 + .../unocss/references/preset-web-fonts.md | 91 + .../skills/unocss/references/preset-wind3.md | 194 + .../skills/unocss/references/preset-wind4.md | 247 + .../references/transformer-attributify-jsx.md | 156 + .../references/transformer-compile-class.md | 128 + .../references/transformer-directives.md | 157 + .../references/transformer-variant-group.md | 97 + .agents/skills/vite/GENERATION.md | 5 + .agents/skills/vite/SKILL.md | 50 + .../skills/vite/references/advanced-api.md | 218 + .../vite/references/advanced-backend.md | 164 + .../vite/references/advanced-performance.md | 168 + .../vite/references/advanced-plugin-api.md | 258 + .../skills/vite/references/build-library.md | 172 + .../vite/references/build-production.md | 220 + .agents/skills/vite/references/build-ssr.md | 194 + .agents/skills/vite/references/core-cli.md | 137 + .agents/skills/vite/references/core-config.md | 176 + .../skills/vite/references/core-features.md | 170 + .../skills/vite/references/core-plugins.md | 154 + .../skills/vite/references/features-assets.md | 138 + .../skills/vite/references/features-css.md | 215 + .../vite/references/features-dep-bundling.md | 148 + .../skills/vite/references/features-env.md | 161 + .../vite/references/features-glob-import.md | 161 + .../skills/vite/references/features-hmr.md | 200 + .../vite/references/features-workers.md | 115 + .agents/skills/vue-best-practices/LICENSE.md | 21 + .agents/skills/vue-best-practices/SKILL.md | 38 + .agents/skills/vue-best-practices/SYNC.md | 5 + .../rules/codeactions-save-performance.md | 79 + .../rules/data-attributes-config.md | 74 + .../rules/deep-watch-numeric.md | 97 + .../rules/define-model-update-event.md | 79 + .../rules/duplicate-plugin-detection.md | 102 + .../rules/extract-component-props.md | 57 + .../rules/fallthrough-attributes.md | 63 + .../vue-best-practices/rules/hmr-vue-ssr.md | 124 + .../rules/module-resolution-bundler.md | 81 + .../rules/pinia-store-mocking.md | 159 + .../rules/script-setup-jsdoc.md | 85 + .../rules/strict-css-modules.md | 68 + .../rules/volar-3-breaking-changes.md | 65 + .../rules/vue-directive-comments.md | 73 + .../rules/vue-router-typed-params.md | 81 + .../rules/vue-tsc-strict-templates.md | 69 + .../rules/with-defaults-union-types.md | 102 + .agents/skills/vue/GENERATION.md | 5 + .agents/skills/vue/SKILL.md | 63 + .../vue/references/advanced-async-suspense.md | 246 + .../vue/references/advanced-provide-inject.md | 174 + .../skills/vue/references/components-emits.md | 139 + .../vue/references/components-lifecycle.md | 192 + .../skills/vue/references/components-props.md | 211 + .../skills/vue/references/components-slots.md | 201 + .../vue/references/components-v-model.md | 183 + .../skills/vue/references/core-reactivity.md | 289 + .../vue/references/features-composables.md | 262 + .../vue/references/features-directives.md | 224 + .../vue/references/features-script-setup.md | 247 + .../vue/references/features-template-refs.md | 212 + .../vue/references/features-typescript.md | 274 + .claude/AGENT-SYSTEM-DESIGN.md | 1066 + .claude/AGENT-SYSTEM-QUICKSTART.md | 577 + .claude/COMPONENT-PATTERNS.md | 666 + .claude/DESIGN-SYSTEM.md | 1004 + .claude/MOBILE-LAYOUT.md | 292 + .claude/UI-CHECKLIST.md | 103 + .claude/UI-COMPONENTS.md | 398 + .claude/settings.local.json | 8 + .claude/skills/ui-ux-pro-max/SKILL.md | 377 + .claude/skills/ui-ux-pro-max/data/charts.csv | 26 + .claude/skills/ui-ux-pro-max/data/colors.csv | 97 + .claude/skills/ui-ux-pro-max/data/icons.csv | 101 + .claude/skills/ui-ux-pro-max/data/landing.csv | 31 + .../skills/ui-ux-pro-max/data/products.csv | 97 + .../ui-ux-pro-max/data/react-performance.csv | 45 + .../ui-ux-pro-max/data/stacks/astro.csv | 54 + .../ui-ux-pro-max/data/stacks/flutter.csv | 53 + .../data/stacks/html-tailwind.csv | 56 + .../data/stacks/jetpack-compose.csv | 53 + .../ui-ux-pro-max/data/stacks/nextjs.csv | 53 + .../ui-ux-pro-max/data/stacks/nuxt-ui.csv | 51 + .../ui-ux-pro-max/data/stacks/nuxtjs.csv | 59 + .../data/stacks/react-native.csv | 52 + .../ui-ux-pro-max/data/stacks/react.csv | 54 + .../ui-ux-pro-max/data/stacks/shadcn.csv | 61 + .../ui-ux-pro-max/data/stacks/svelte.csv | 54 + .../ui-ux-pro-max/data/stacks/swiftui.csv | 51 + .../skills/ui-ux-pro-max/data/stacks/vue.csv | 50 + .claude/skills/ui-ux-pro-max/data/styles.csv | 68 + .../skills/ui-ux-pro-max/data/typography.csv | 58 + .../ui-ux-pro-max/data/ui-reasoning.csv | 101 + .../ui-ux-pro-max/data/ux-guidelines.csv | 100 + .../ui-ux-pro-max/data/web-interface.csv | 31 + .../scripts/__pycache__/core.cpython-314.pyc | Bin 0 -> 12619 bytes .../__pycache__/design_system.cpython-314.pyc | Bin 0 -> 62939 bytes .../__pycache__/search.cpython-314.pyc | Bin 0 -> 6584 bytes .claude/skills/ui-ux-pro-max/scripts/core.py | 253 + .../ui-ux-pro-max/scripts/design_system.py | 1067 + .../skills/ui-ux-pro-max/scripts/search.py | 114 + .cursor/mcp.json | 7 + .cursor/rules/git.mdc | 39 + .cursor/rules/index.mdc | 17 + .cursor/rules/project.mdc | 81 + .cursor/rules/ts.mdc | 42 + .cursor/rules/vue.mdc | 63 + .cursor/skills/antfu/SKILL.md | 222 + .../antfu/references/antfu-eslint-config.md | 328 + .../antfu/references/app-development.md | 60 + .../skills/antfu/references/github-actions.md | 68 + .cursor/skills/antfu/references/gitignore.md | 29 + .../antfu/references/library-development.md | 85 + .cursor/skills/antfu/references/monorepo.md | 126 + .../antfu/references/vscode-extensions.md | 34 + .cursor/skills/pinia/GENERATION.md | 5 + .cursor/skills/pinia/SKILL.md | 59 + .../skills/pinia/references/advanced-hmr.md | 61 + .../skills/pinia/references/advanced-nuxt.md | 119 + .../skills/pinia/references/advanced-ssr.md | 121 + .../best-practices-outside-component.md | 115 + .../references/best-practices-testing.md | 212 + .../skills/pinia/references/core-stores.md | 389 + .../pinia/references/features-composables.md | 114 + .../references/features-composing-stores.md | 134 + .../pinia/references/features-plugins.md | 203 + .cursor/skills/pnpm/GENERATION.md | 5 + .cursor/skills/pnpm/SKILL.md | 42 + .../pnpm/references/best-practices-ci.md | 285 + .../references/best-practices-migration.md | 291 + .../references/best-practices-performance.md | 284 + .cursor/skills/pnpm/references/core-cli.md | 229 + .cursor/skills/pnpm/references/core-config.md | 188 + .cursor/skills/pnpm/references/core-store.md | 179 + .../skills/pnpm/references/core-workspaces.md | 205 + .../pnpm/references/features-aliases.md | 168 + .../pnpm/references/features-catalogs.md | 159 + .../skills/pnpm/references/features-hooks.md | 233 + .../pnpm/references/features-overrides.md | 184 + .../pnpm/references/features-patches.md | 201 + .../pnpm/references/features-peer-deps.md | 250 + .cursor/skills/unocss/GENERATION.md | 5 + .cursor/skills/unocss/SKILL.md | 64 + .../skills/unocss/references/core-config.md | 187 + .../unocss/references/core-extracting.md | 137 + .../skills/unocss/references/core-layers.md | 104 + .../skills/unocss/references/core-rules.md | 166 + .../skills/unocss/references/core-safelist.md | 105 + .../unocss/references/core-shortcuts.md | 89 + .../skills/unocss/references/core-theme.md | 172 + .../skills/unocss/references/core-variants.md | 175 + .../unocss/references/integrations-nuxt.md | 199 + .../unocss/references/integrations-vite.md | 283 + .../unocss/references/preset-attributify.md | 142 + .../skills/unocss/references/preset-icons.md | 184 + .../skills/unocss/references/preset-mini.md | 158 + .../unocss/references/preset-rem-to-px.md | 97 + .../skills/unocss/references/preset-tagify.md | 134 + .../unocss/references/preset-typography.md | 95 + .../unocss/references/preset-web-fonts.md | 91 + .../skills/unocss/references/preset-wind3.md | 194 + .../skills/unocss/references/preset-wind4.md | 247 + .../references/transformer-attributify-jsx.md | 156 + .../references/transformer-compile-class.md | 128 + .../references/transformer-directives.md | 157 + .../references/transformer-variant-group.md | 97 + .cursor/skills/vite/GENERATION.md | 5 + .cursor/skills/vite/SKILL.md | 50 + .../skills/vite/references/advanced-api.md | 218 + .../vite/references/advanced-backend.md | 164 + .../vite/references/advanced-performance.md | 168 + .../vite/references/advanced-plugin-api.md | 258 + .../skills/vite/references/build-library.md | 172 + .../vite/references/build-production.md | 220 + .cursor/skills/vite/references/build-ssr.md | 194 + .cursor/skills/vite/references/core-cli.md | 137 + .cursor/skills/vite/references/core-config.md | 176 + .../skills/vite/references/core-features.md | 170 + .../skills/vite/references/core-plugins.md | 154 + .../skills/vite/references/features-assets.md | 138 + .../skills/vite/references/features-css.md | 215 + .../vite/references/features-dep-bundling.md | 148 + .../skills/vite/references/features-env.md | 161 + .../vite/references/features-glob-import.md | 161 + .../skills/vite/references/features-hmr.md | 200 + .../vite/references/features-workers.md | 115 + .cursor/skills/vue-best-practices/LICENSE.md | 21 + .cursor/skills/vue-best-practices/SKILL.md | 38 + .cursor/skills/vue-best-practices/SYNC.md | 5 + .../rules/codeactions-save-performance.md | 79 + .../rules/data-attributes-config.md | 74 + .../rules/deep-watch-numeric.md | 97 + .../rules/define-model-update-event.md | 79 + .../rules/duplicate-plugin-detection.md | 102 + .../rules/extract-component-props.md | 57 + .../rules/fallthrough-attributes.md | 63 + .../vue-best-practices/rules/hmr-vue-ssr.md | 124 + .../rules/module-resolution-bundler.md | 81 + .../rules/pinia-store-mocking.md | 159 + .../rules/script-setup-jsdoc.md | 85 + .../rules/strict-css-modules.md | 68 + .../rules/volar-3-breaking-changes.md | 65 + .../rules/vue-directive-comments.md | 73 + .../rules/vue-router-typed-params.md | 81 + .../rules/vue-tsc-strict-templates.md | 69 + .../rules/with-defaults-union-types.md | 102 + .cursor/skills/vue/GENERATION.md | 5 + .cursor/skills/vue/SKILL.md | 63 + .../vue/references/advanced-async-suspense.md | 246 + .../vue/references/advanced-provide-inject.md | 174 + .../skills/vue/references/components-emits.md | 139 + .../vue/references/components-lifecycle.md | 192 + .../skills/vue/references/components-props.md | 211 + .../skills/vue/references/components-slots.md | 201 + .../vue/references/components-v-model.md | 183 + .../skills/vue/references/core-reactivity.md | 289 + .../vue/references/features-composables.md | 262 + .../vue/references/features-directives.md | 224 + .../vue/references/features-script-setup.md | 247 + .../vue/references/features-template-refs.md | 212 + .../vue/references/features-typescript.md | 274 + .editorconfig | 22 + .gitignore | 29 + .npmrc | 12 + .trae/rules/project_rules.md | 223 + .trae/skills/antfu/SKILL.md | 222 + .../antfu/references/antfu-eslint-config.md | 328 + .../antfu/references/app-development.md | 60 + .../skills/antfu/references/github-actions.md | 68 + .trae/skills/antfu/references/gitignore.md | 29 + .../antfu/references/library-development.md | 85 + .trae/skills/antfu/references/monorepo.md | 126 + .../antfu/references/vscode-extensions.md | 34 + .trae/skills/pinia/GENERATION.md | 5 + .trae/skills/pinia/SKILL.md | 59 + .trae/skills/pinia/references/advanced-hmr.md | 61 + .../skills/pinia/references/advanced-nuxt.md | 119 + .trae/skills/pinia/references/advanced-ssr.md | 121 + .../best-practices-outside-component.md | 115 + .../references/best-practices-testing.md | 212 + .trae/skills/pinia/references/core-stores.md | 389 + .../pinia/references/features-composables.md | 114 + .../references/features-composing-stores.md | 134 + .../pinia/references/features-plugins.md | 203 + .trae/skills/pnpm/GENERATION.md | 5 + .trae/skills/pnpm/SKILL.md | 42 + .../pnpm/references/best-practices-ci.md | 285 + .../references/best-practices-migration.md | 291 + .../references/best-practices-performance.md | 284 + .trae/skills/pnpm/references/core-cli.md | 229 + .trae/skills/pnpm/references/core-config.md | 188 + .trae/skills/pnpm/references/core-store.md | 179 + .../skills/pnpm/references/core-workspaces.md | 205 + .../pnpm/references/features-aliases.md | 168 + .../pnpm/references/features-catalogs.md | 159 + .../skills/pnpm/references/features-hooks.md | 233 + .../pnpm/references/features-overrides.md | 184 + .../pnpm/references/features-patches.md | 201 + .../pnpm/references/features-peer-deps.md | 250 + .trae/skills/unocss/GENERATION.md | 5 + .trae/skills/unocss/SKILL.md | 64 + .trae/skills/unocss/references/core-config.md | 187 + .../unocss/references/core-extracting.md | 137 + .trae/skills/unocss/references/core-layers.md | 104 + .trae/skills/unocss/references/core-rules.md | 166 + .../skills/unocss/references/core-safelist.md | 105 + .../unocss/references/core-shortcuts.md | 89 + .trae/skills/unocss/references/core-theme.md | 172 + .../skills/unocss/references/core-variants.md | 175 + .../unocss/references/integrations-nuxt.md | 199 + .../unocss/references/integrations-vite.md | 283 + .../unocss/references/preset-attributify.md | 142 + .../skills/unocss/references/preset-icons.md | 184 + .trae/skills/unocss/references/preset-mini.md | 158 + .../unocss/references/preset-rem-to-px.md | 97 + .../skills/unocss/references/preset-tagify.md | 134 + .../unocss/references/preset-typography.md | 95 + .../unocss/references/preset-web-fonts.md | 91 + .../skills/unocss/references/preset-wind3.md | 194 + .../skills/unocss/references/preset-wind4.md | 247 + .../references/transformer-attributify-jsx.md | 156 + .../references/transformer-compile-class.md | 128 + .../references/transformer-directives.md | 157 + .../references/transformer-variant-group.md | 97 + .trae/skills/vite/GENERATION.md | 5 + .trae/skills/vite/SKILL.md | 50 + .trae/skills/vite/references/advanced-api.md | 218 + .../vite/references/advanced-backend.md | 164 + .../vite/references/advanced-performance.md | 168 + .../vite/references/advanced-plugin-api.md | 258 + .trae/skills/vite/references/build-library.md | 172 + .../vite/references/build-production.md | 220 + .trae/skills/vite/references/build-ssr.md | 194 + .trae/skills/vite/references/core-cli.md | 137 + .trae/skills/vite/references/core-config.md | 176 + .trae/skills/vite/references/core-features.md | 170 + .trae/skills/vite/references/core-plugins.md | 154 + .../skills/vite/references/features-assets.md | 138 + .trae/skills/vite/references/features-css.md | 215 + .../vite/references/features-dep-bundling.md | 148 + .trae/skills/vite/references/features-env.md | 161 + .../vite/references/features-glob-import.md | 161 + .trae/skills/vite/references/features-hmr.md | 200 + .../vite/references/features-workers.md | 115 + .trae/skills/vue-best-practices/LICENSE.md | 21 + .trae/skills/vue-best-practices/SKILL.md | 38 + .trae/skills/vue-best-practices/SYNC.md | 5 + .../rules/codeactions-save-performance.md | 79 + .../rules/data-attributes-config.md | 74 + .../rules/deep-watch-numeric.md | 97 + .../rules/define-model-update-event.md | 79 + .../rules/duplicate-plugin-detection.md | 102 + .../rules/extract-component-props.md | 57 + .../rules/fallthrough-attributes.md | 63 + .../vue-best-practices/rules/hmr-vue-ssr.md | 124 + .../rules/module-resolution-bundler.md | 81 + .../rules/pinia-store-mocking.md | 159 + .../rules/script-setup-jsdoc.md | 85 + .../rules/strict-css-modules.md | 68 + .../rules/volar-3-breaking-changes.md | 65 + .../rules/vue-directive-comments.md | 73 + .../rules/vue-router-typed-params.md | 81 + .../rules/vue-tsc-strict-templates.md | 69 + .../rules/with-defaults-union-types.md | 102 + .trae/skills/vue/GENERATION.md | 5 + .trae/skills/vue/SKILL.md | 63 + .../vue/references/advanced-async-suspense.md | 246 + .../vue/references/advanced-provide-inject.md | 174 + .../skills/vue/references/components-emits.md | 139 + .../vue/references/components-lifecycle.md | 192 + .../skills/vue/references/components-props.md | 211 + .../skills/vue/references/components-slots.md | 201 + .../vue/references/components-v-model.md | 183 + .../skills/vue/references/core-reactivity.md | 289 + .../vue/references/features-composables.md | 262 + .../vue/references/features-directives.md | 224 + .../vue/references/features-script-setup.md | 247 + .../vue/references/features-template-refs.md | 212 + .../vue/references/features-typescript.md | 274 + .vscode/extensions.json | 21 + .vscode/settings.json | 36 + .vscode/unocss.json | 11 + .vscode/vue3.code-snippets | 48 + CONTRIBUTING.md | 71 + LICENSE | 21 + README-AGENT-SYSTEM.md | 232 + README.md | 436 + build/config/index.ts | 1 + build/config/proxy.ts | 18 + build/plugins/autoImport.ts | 13 + build/plugins/cleanImage.ts | 12 + build/plugins/component.ts | 11 + build/plugins/index.ts | 43 + build/plugins/mcp.ts | 9 + build/plugins/replaceUrl.ts | 13 + build/plugins/unocss.ts | 11 + build/plugins/visualizer.ts | 13 + check-tags.cjs | 30 + cz.config.js | 58 + docs/API.md | 2071 ++ docs/企业卡授权列表和设备授权列表.md | 130 + docs/佣金和钱包.md | 391 + docs/停复机.md | 427 + docs/资产列表(代理调用的接口).md | 135 + docs/资产详情.md | 333 + env/.env | 20 + env/.env.development | 14 + env/.env.production | 14 + env/.env.test | 14 + eslint.config.js | 56 + index.html | 67 + package.json | 157 + pnpm-lock.yaml | 19904 ++++++++++++++++ scripts/mini-ci.js | 200 + scripts/post-upgrade.js | 36 + scripts/verify-commit.js | 28 + src/App.vue | 41 + src/api/assets.ts | 398 + src/api/auth.ts | 111 + src/api/carrier.ts | 47 + src/api/commission.ts | 128 + src/api/common/index.ts | 12 + src/api/common/types.ts | 21 + src/api/enterprise.ts | 75 + src/api/index.ts | 4 + src/api/user/index.ts | 18 + src/api/user/types.ts | 30 + src/api/wallet.ts | 38 + src/api/withdrawal.ts | 89 + src/components/.gitkeep | 0 src/components/SimplePicker.vue | 182 + src/components/Skeleton.vue | 95 + src/components/agree-privacy/index.vue | 214 + src/components/lang-select/index.vue | 51 + src/components/theme-picker/index.vue | 32 + src/hooks/index.ts | 9 + src/hooks/use-clipboard/index.ts | 33 + src/hooks/use-loading/index.ts | 24 + src/hooks/use-location/index.ts | 326 + src/hooks/use-location/types.ts | 30 + src/hooks/use-modal/index.ts | 24 + src/hooks/use-permission/index.ts | 10 + src/hooks/use-share/index.ts | 48 + src/hooks/use-share/types.ts | 6 + src/hooks/use-theme/index.ts | 38 + src/locales/index.ts | 21 + src/locales/langs/en.ts | 11 + src/locales/langs/zh-Hans.ts | 11 + src/main.ts | 14 + src/manifest.json | 78 + src/pages.json | 176 + src/pages/agent-system/asset-detail/index.vue | 623 + src/pages/agent-system/asset-search/index.vue | 1160 + src/pages/agent-system/asset-wallet/index.vue | 252 + src/pages/agent-system/assets/index.vue | 841 + .../agent-system/change-password/index.vue | 438 + .../agent-system/commission-center/index.vue | 460 + src/pages/agent-system/commission/index.vue | 16 + .../agent-system/enterprise-cards/index.vue | 536 + .../agent-system/enterprise-devices/index.vue | 317 + src/pages/agent-system/home/index.vue | 392 + src/pages/agent-system/index.vue | 1512 ++ src/pages/agent-system/my-packages/index.vue | 23 + src/pages/agent-system/packages/index.vue | 245 + src/pages/agent-system/tags/index.vue | 23 + src/pages/agent-system/user-info/index.vue | 264 + src/pages/agent-system/utils.ts | 77 + src/pages/agent-system/withdraw/index.vue | 587 + src/pages/common/404/index.vue | 35 + src/pages/common/login/index.vue | 481 + src/pages/common/theme/index.vue | 103 + src/pages/common/webview/index.vue | 12 + src/pages/tab/home/index.vue | 58 + src/plugins/index.ts | 21 + src/plugins/permission.ts | 57 + src/plugins/ui.ts | 28 + src/router/index.ts | 85 + src/static/icons/.gitkeep | 0 src/static/icons/preview-close-one.png | Bin 0 -> 5849 bytes src/static/icons/preview-open.png | Bin 0 -> 6115 bytes src/static/images/404.png | Bin 0 -> 8486 bytes src/static/images/logo.png | Bin 0 -> 4023 bytes src/static/images/pay.png | Bin 0 -> 68567 bytes src/static/styles/common.scss | 5 + src/static/styles/theme.scss | 280 + src/store/index.ts | 27 + src/store/modules/app/index.ts | 47 + src/store/modules/app/types.ts | 5 + src/store/modules/user/index.ts | 105 + src/store/modules/user/types.ts | 16 + src/uni.scss | 55 + src/utils/auth/index.ts | 15 + src/utils/common/index.ts | 28 + src/utils/format.ts | 59 + src/utils/index.ts | 5 + src/utils/modals/index.ts | 57 + src/utils/modals/types.ts | 25 + src/utils/request/index.ts | 58 + src/utils/request/interceptors.ts | 239 + src/utils/request/status.ts | 46 + src/utils/request/types.ts | 7 + src/utils/storage/index.ts | 25 + stylelint.config.js | 91 + tsconfig.json | 35 + types/auto-imports.d.ts | 207 + types/components.d.ts | 19 + types/env.d.ts | 20 + types/global.d.ts | 40 + types/i18n.d.ts | 8 + types/module.d.ts | 9 + uno.config.ts | 79 + vite.config.ts | 53 + 代理企业管理系统-移动端.md | 300 + 套餐列表页面说明.md | 372 + 套餐管理系统说明.md | 413 + 527 files changed, 96725 insertions(+) create mode 100644 .agents/skills/antfu/SKILL.md create mode 100644 .agents/skills/antfu/references/antfu-eslint-config.md create mode 100644 .agents/skills/antfu/references/app-development.md create mode 100644 .agents/skills/antfu/references/github-actions.md create mode 100644 .agents/skills/antfu/references/gitignore.md create mode 100644 .agents/skills/antfu/references/library-development.md create mode 100644 .agents/skills/antfu/references/monorepo.md create mode 100644 .agents/skills/antfu/references/vscode-extensions.md create mode 100644 .agents/skills/pinia/GENERATION.md create mode 100644 .agents/skills/pinia/SKILL.md create mode 100644 .agents/skills/pinia/references/advanced-hmr.md create mode 100644 .agents/skills/pinia/references/advanced-nuxt.md create mode 100644 .agents/skills/pinia/references/advanced-ssr.md create mode 100644 .agents/skills/pinia/references/best-practices-outside-component.md create mode 100644 .agents/skills/pinia/references/best-practices-testing.md create mode 100644 .agents/skills/pinia/references/core-stores.md create mode 100644 .agents/skills/pinia/references/features-composables.md create mode 100644 .agents/skills/pinia/references/features-composing-stores.md create mode 100644 .agents/skills/pinia/references/features-plugins.md create mode 100644 .agents/skills/pnpm/GENERATION.md create mode 100644 .agents/skills/pnpm/SKILL.md create mode 100644 .agents/skills/pnpm/references/best-practices-ci.md create mode 100644 .agents/skills/pnpm/references/best-practices-migration.md create mode 100644 .agents/skills/pnpm/references/best-practices-performance.md create mode 100644 .agents/skills/pnpm/references/core-cli.md create mode 100644 .agents/skills/pnpm/references/core-config.md create mode 100644 .agents/skills/pnpm/references/core-store.md create mode 100644 .agents/skills/pnpm/references/core-workspaces.md create mode 100644 .agents/skills/pnpm/references/features-aliases.md create mode 100644 .agents/skills/pnpm/references/features-catalogs.md create mode 100644 .agents/skills/pnpm/references/features-hooks.md create mode 100644 .agents/skills/pnpm/references/features-overrides.md create mode 100644 .agents/skills/pnpm/references/features-patches.md create mode 100644 .agents/skills/pnpm/references/features-peer-deps.md create mode 100644 .agents/skills/unocss/GENERATION.md create mode 100644 .agents/skills/unocss/SKILL.md create mode 100644 .agents/skills/unocss/references/core-config.md create mode 100644 .agents/skills/unocss/references/core-extracting.md create mode 100644 .agents/skills/unocss/references/core-layers.md create mode 100644 .agents/skills/unocss/references/core-rules.md create mode 100644 .agents/skills/unocss/references/core-safelist.md create mode 100644 .agents/skills/unocss/references/core-shortcuts.md create mode 100644 .agents/skills/unocss/references/core-theme.md create mode 100644 .agents/skills/unocss/references/core-variants.md create mode 100644 .agents/skills/unocss/references/integrations-nuxt.md create mode 100644 .agents/skills/unocss/references/integrations-vite.md create mode 100644 .agents/skills/unocss/references/preset-attributify.md create mode 100644 .agents/skills/unocss/references/preset-icons.md create mode 100644 .agents/skills/unocss/references/preset-mini.md create mode 100644 .agents/skills/unocss/references/preset-rem-to-px.md create mode 100644 .agents/skills/unocss/references/preset-tagify.md create mode 100644 .agents/skills/unocss/references/preset-typography.md create mode 100644 .agents/skills/unocss/references/preset-web-fonts.md create mode 100644 .agents/skills/unocss/references/preset-wind3.md create mode 100644 .agents/skills/unocss/references/preset-wind4.md create mode 100644 .agents/skills/unocss/references/transformer-attributify-jsx.md create mode 100644 .agents/skills/unocss/references/transformer-compile-class.md create mode 100644 .agents/skills/unocss/references/transformer-directives.md create mode 100644 .agents/skills/unocss/references/transformer-variant-group.md create mode 100644 .agents/skills/vite/GENERATION.md create mode 100644 .agents/skills/vite/SKILL.md create mode 100644 .agents/skills/vite/references/advanced-api.md create mode 100644 .agents/skills/vite/references/advanced-backend.md create mode 100644 .agents/skills/vite/references/advanced-performance.md create mode 100644 .agents/skills/vite/references/advanced-plugin-api.md create mode 100644 .agents/skills/vite/references/build-library.md create mode 100644 .agents/skills/vite/references/build-production.md create mode 100644 .agents/skills/vite/references/build-ssr.md create mode 100644 .agents/skills/vite/references/core-cli.md create mode 100644 .agents/skills/vite/references/core-config.md create mode 100644 .agents/skills/vite/references/core-features.md create mode 100644 .agents/skills/vite/references/core-plugins.md create mode 100644 .agents/skills/vite/references/features-assets.md create mode 100644 .agents/skills/vite/references/features-css.md create mode 100644 .agents/skills/vite/references/features-dep-bundling.md create mode 100644 .agents/skills/vite/references/features-env.md create mode 100644 .agents/skills/vite/references/features-glob-import.md create mode 100644 .agents/skills/vite/references/features-hmr.md create mode 100644 .agents/skills/vite/references/features-workers.md create mode 100644 .agents/skills/vue-best-practices/LICENSE.md create mode 100644 .agents/skills/vue-best-practices/SKILL.md create mode 100644 .agents/skills/vue-best-practices/SYNC.md create mode 100644 .agents/skills/vue-best-practices/rules/codeactions-save-performance.md create mode 100644 .agents/skills/vue-best-practices/rules/data-attributes-config.md create mode 100644 .agents/skills/vue-best-practices/rules/deep-watch-numeric.md create mode 100644 .agents/skills/vue-best-practices/rules/define-model-update-event.md create mode 100644 .agents/skills/vue-best-practices/rules/duplicate-plugin-detection.md create mode 100644 .agents/skills/vue-best-practices/rules/extract-component-props.md create mode 100644 .agents/skills/vue-best-practices/rules/fallthrough-attributes.md create mode 100644 .agents/skills/vue-best-practices/rules/hmr-vue-ssr.md create mode 100644 .agents/skills/vue-best-practices/rules/module-resolution-bundler.md create mode 100644 .agents/skills/vue-best-practices/rules/pinia-store-mocking.md create mode 100644 .agents/skills/vue-best-practices/rules/script-setup-jsdoc.md create mode 100644 .agents/skills/vue-best-practices/rules/strict-css-modules.md create mode 100644 .agents/skills/vue-best-practices/rules/volar-3-breaking-changes.md create mode 100644 .agents/skills/vue-best-practices/rules/vue-directive-comments.md create mode 100644 .agents/skills/vue-best-practices/rules/vue-router-typed-params.md create mode 100644 .agents/skills/vue-best-practices/rules/vue-tsc-strict-templates.md create mode 100644 .agents/skills/vue-best-practices/rules/with-defaults-union-types.md create mode 100644 .agents/skills/vue/GENERATION.md create mode 100644 .agents/skills/vue/SKILL.md create mode 100644 .agents/skills/vue/references/advanced-async-suspense.md create mode 100644 .agents/skills/vue/references/advanced-provide-inject.md create mode 100644 .agents/skills/vue/references/components-emits.md create mode 100644 .agents/skills/vue/references/components-lifecycle.md create mode 100644 .agents/skills/vue/references/components-props.md create mode 100644 .agents/skills/vue/references/components-slots.md create mode 100644 .agents/skills/vue/references/components-v-model.md create mode 100644 .agents/skills/vue/references/core-reactivity.md create mode 100644 .agents/skills/vue/references/features-composables.md create mode 100644 .agents/skills/vue/references/features-directives.md create mode 100644 .agents/skills/vue/references/features-script-setup.md create mode 100644 .agents/skills/vue/references/features-template-refs.md create mode 100644 .agents/skills/vue/references/features-typescript.md create mode 100644 .claude/AGENT-SYSTEM-DESIGN.md create mode 100644 .claude/AGENT-SYSTEM-QUICKSTART.md create mode 100644 .claude/COMPONENT-PATTERNS.md create mode 100644 .claude/DESIGN-SYSTEM.md create mode 100644 .claude/MOBILE-LAYOUT.md create mode 100644 .claude/UI-CHECKLIST.md create mode 100644 .claude/UI-COMPONENTS.md create mode 100644 .claude/settings.local.json create mode 100644 .claude/skills/ui-ux-pro-max/SKILL.md create mode 100644 .claude/skills/ui-ux-pro-max/data/charts.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/colors.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/icons.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/landing.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/products.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/react-performance.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/astro.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/flutter.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/html-tailwind.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/jetpack-compose.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/nextjs.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/nuxt-ui.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/nuxtjs.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/react-native.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/react.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/shadcn.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/svelte.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/swiftui.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/stacks/vue.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/styles.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/typography.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/ui-reasoning.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/ux-guidelines.csv create mode 100644 .claude/skills/ui-ux-pro-max/data/web-interface.csv create mode 100644 .claude/skills/ui-ux-pro-max/scripts/__pycache__/core.cpython-314.pyc create mode 100644 .claude/skills/ui-ux-pro-max/scripts/__pycache__/design_system.cpython-314.pyc create mode 100644 .claude/skills/ui-ux-pro-max/scripts/__pycache__/search.cpython-314.pyc create mode 100644 .claude/skills/ui-ux-pro-max/scripts/core.py create mode 100644 .claude/skills/ui-ux-pro-max/scripts/design_system.py create mode 100644 .claude/skills/ui-ux-pro-max/scripts/search.py create mode 100644 .cursor/mcp.json create mode 100644 .cursor/rules/git.mdc create mode 100644 .cursor/rules/index.mdc create mode 100644 .cursor/rules/project.mdc create mode 100644 .cursor/rules/ts.mdc create mode 100644 .cursor/rules/vue.mdc create mode 100644 .cursor/skills/antfu/SKILL.md create mode 100644 .cursor/skills/antfu/references/antfu-eslint-config.md create mode 100644 .cursor/skills/antfu/references/app-development.md create mode 100644 .cursor/skills/antfu/references/github-actions.md create mode 100644 .cursor/skills/antfu/references/gitignore.md create mode 100644 .cursor/skills/antfu/references/library-development.md create mode 100644 .cursor/skills/antfu/references/monorepo.md create mode 100644 .cursor/skills/antfu/references/vscode-extensions.md create mode 100644 .cursor/skills/pinia/GENERATION.md create mode 100644 .cursor/skills/pinia/SKILL.md create mode 100644 .cursor/skills/pinia/references/advanced-hmr.md create mode 100644 .cursor/skills/pinia/references/advanced-nuxt.md create mode 100644 .cursor/skills/pinia/references/advanced-ssr.md create mode 100644 .cursor/skills/pinia/references/best-practices-outside-component.md create mode 100644 .cursor/skills/pinia/references/best-practices-testing.md create mode 100644 .cursor/skills/pinia/references/core-stores.md create mode 100644 .cursor/skills/pinia/references/features-composables.md create mode 100644 .cursor/skills/pinia/references/features-composing-stores.md create mode 100644 .cursor/skills/pinia/references/features-plugins.md create mode 100644 .cursor/skills/pnpm/GENERATION.md create mode 100644 .cursor/skills/pnpm/SKILL.md create mode 100644 .cursor/skills/pnpm/references/best-practices-ci.md create mode 100644 .cursor/skills/pnpm/references/best-practices-migration.md create mode 100644 .cursor/skills/pnpm/references/best-practices-performance.md create mode 100644 .cursor/skills/pnpm/references/core-cli.md create mode 100644 .cursor/skills/pnpm/references/core-config.md create mode 100644 .cursor/skills/pnpm/references/core-store.md create mode 100644 .cursor/skills/pnpm/references/core-workspaces.md create mode 100644 .cursor/skills/pnpm/references/features-aliases.md create mode 100644 .cursor/skills/pnpm/references/features-catalogs.md create mode 100644 .cursor/skills/pnpm/references/features-hooks.md create mode 100644 .cursor/skills/pnpm/references/features-overrides.md create mode 100644 .cursor/skills/pnpm/references/features-patches.md create mode 100644 .cursor/skills/pnpm/references/features-peer-deps.md create mode 100644 .cursor/skills/unocss/GENERATION.md create mode 100644 .cursor/skills/unocss/SKILL.md create mode 100644 .cursor/skills/unocss/references/core-config.md create mode 100644 .cursor/skills/unocss/references/core-extracting.md create mode 100644 .cursor/skills/unocss/references/core-layers.md create mode 100644 .cursor/skills/unocss/references/core-rules.md create mode 100644 .cursor/skills/unocss/references/core-safelist.md create mode 100644 .cursor/skills/unocss/references/core-shortcuts.md create mode 100644 .cursor/skills/unocss/references/core-theme.md create mode 100644 .cursor/skills/unocss/references/core-variants.md create mode 100644 .cursor/skills/unocss/references/integrations-nuxt.md create mode 100644 .cursor/skills/unocss/references/integrations-vite.md create mode 100644 .cursor/skills/unocss/references/preset-attributify.md create mode 100644 .cursor/skills/unocss/references/preset-icons.md create mode 100644 .cursor/skills/unocss/references/preset-mini.md create mode 100644 .cursor/skills/unocss/references/preset-rem-to-px.md create mode 100644 .cursor/skills/unocss/references/preset-tagify.md create mode 100644 .cursor/skills/unocss/references/preset-typography.md create mode 100644 .cursor/skills/unocss/references/preset-web-fonts.md create mode 100644 .cursor/skills/unocss/references/preset-wind3.md create mode 100644 .cursor/skills/unocss/references/preset-wind4.md create mode 100644 .cursor/skills/unocss/references/transformer-attributify-jsx.md create mode 100644 .cursor/skills/unocss/references/transformer-compile-class.md create mode 100644 .cursor/skills/unocss/references/transformer-directives.md create mode 100644 .cursor/skills/unocss/references/transformer-variant-group.md create mode 100644 .cursor/skills/vite/GENERATION.md create mode 100644 .cursor/skills/vite/SKILL.md create mode 100644 .cursor/skills/vite/references/advanced-api.md create mode 100644 .cursor/skills/vite/references/advanced-backend.md create mode 100644 .cursor/skills/vite/references/advanced-performance.md create mode 100644 .cursor/skills/vite/references/advanced-plugin-api.md create mode 100644 .cursor/skills/vite/references/build-library.md create mode 100644 .cursor/skills/vite/references/build-production.md create mode 100644 .cursor/skills/vite/references/build-ssr.md create mode 100644 .cursor/skills/vite/references/core-cli.md create mode 100644 .cursor/skills/vite/references/core-config.md create mode 100644 .cursor/skills/vite/references/core-features.md create mode 100644 .cursor/skills/vite/references/core-plugins.md create mode 100644 .cursor/skills/vite/references/features-assets.md create mode 100644 .cursor/skills/vite/references/features-css.md create mode 100644 .cursor/skills/vite/references/features-dep-bundling.md create mode 100644 .cursor/skills/vite/references/features-env.md create mode 100644 .cursor/skills/vite/references/features-glob-import.md create mode 100644 .cursor/skills/vite/references/features-hmr.md create mode 100644 .cursor/skills/vite/references/features-workers.md create mode 100644 .cursor/skills/vue-best-practices/LICENSE.md create mode 100644 .cursor/skills/vue-best-practices/SKILL.md create mode 100644 .cursor/skills/vue-best-practices/SYNC.md create mode 100644 .cursor/skills/vue-best-practices/rules/codeactions-save-performance.md create mode 100644 .cursor/skills/vue-best-practices/rules/data-attributes-config.md create mode 100644 .cursor/skills/vue-best-practices/rules/deep-watch-numeric.md create mode 100644 .cursor/skills/vue-best-practices/rules/define-model-update-event.md create mode 100644 .cursor/skills/vue-best-practices/rules/duplicate-plugin-detection.md create mode 100644 .cursor/skills/vue-best-practices/rules/extract-component-props.md create mode 100644 .cursor/skills/vue-best-practices/rules/fallthrough-attributes.md create mode 100644 .cursor/skills/vue-best-practices/rules/hmr-vue-ssr.md create mode 100644 .cursor/skills/vue-best-practices/rules/module-resolution-bundler.md create mode 100644 .cursor/skills/vue-best-practices/rules/pinia-store-mocking.md create mode 100644 .cursor/skills/vue-best-practices/rules/script-setup-jsdoc.md create mode 100644 .cursor/skills/vue-best-practices/rules/strict-css-modules.md create mode 100644 .cursor/skills/vue-best-practices/rules/volar-3-breaking-changes.md create mode 100644 .cursor/skills/vue-best-practices/rules/vue-directive-comments.md create mode 100644 .cursor/skills/vue-best-practices/rules/vue-router-typed-params.md create mode 100644 .cursor/skills/vue-best-practices/rules/vue-tsc-strict-templates.md create mode 100644 .cursor/skills/vue-best-practices/rules/with-defaults-union-types.md create mode 100644 .cursor/skills/vue/GENERATION.md create mode 100644 .cursor/skills/vue/SKILL.md create mode 100644 .cursor/skills/vue/references/advanced-async-suspense.md create mode 100644 .cursor/skills/vue/references/advanced-provide-inject.md create mode 100644 .cursor/skills/vue/references/components-emits.md create mode 100644 .cursor/skills/vue/references/components-lifecycle.md create mode 100644 .cursor/skills/vue/references/components-props.md create mode 100644 .cursor/skills/vue/references/components-slots.md create mode 100644 .cursor/skills/vue/references/components-v-model.md create mode 100644 .cursor/skills/vue/references/core-reactivity.md create mode 100644 .cursor/skills/vue/references/features-composables.md create mode 100644 .cursor/skills/vue/references/features-directives.md create mode 100644 .cursor/skills/vue/references/features-script-setup.md create mode 100644 .cursor/skills/vue/references/features-template-refs.md create mode 100644 .cursor/skills/vue/references/features-typescript.md create mode 100644 .editorconfig create mode 100644 .gitignore create mode 100644 .npmrc create mode 100644 .trae/rules/project_rules.md create mode 100644 .trae/skills/antfu/SKILL.md create mode 100644 .trae/skills/antfu/references/antfu-eslint-config.md create mode 100644 .trae/skills/antfu/references/app-development.md create mode 100644 .trae/skills/antfu/references/github-actions.md create mode 100644 .trae/skills/antfu/references/gitignore.md create mode 100644 .trae/skills/antfu/references/library-development.md create mode 100644 .trae/skills/antfu/references/monorepo.md create mode 100644 .trae/skills/antfu/references/vscode-extensions.md create mode 100644 .trae/skills/pinia/GENERATION.md create mode 100644 .trae/skills/pinia/SKILL.md create mode 100644 .trae/skills/pinia/references/advanced-hmr.md create mode 100644 .trae/skills/pinia/references/advanced-nuxt.md create mode 100644 .trae/skills/pinia/references/advanced-ssr.md create mode 100644 .trae/skills/pinia/references/best-practices-outside-component.md create mode 100644 .trae/skills/pinia/references/best-practices-testing.md create mode 100644 .trae/skills/pinia/references/core-stores.md create mode 100644 .trae/skills/pinia/references/features-composables.md create mode 100644 .trae/skills/pinia/references/features-composing-stores.md create mode 100644 .trae/skills/pinia/references/features-plugins.md create mode 100644 .trae/skills/pnpm/GENERATION.md create mode 100644 .trae/skills/pnpm/SKILL.md create mode 100644 .trae/skills/pnpm/references/best-practices-ci.md create mode 100644 .trae/skills/pnpm/references/best-practices-migration.md create mode 100644 .trae/skills/pnpm/references/best-practices-performance.md create mode 100644 .trae/skills/pnpm/references/core-cli.md create mode 100644 .trae/skills/pnpm/references/core-config.md create mode 100644 .trae/skills/pnpm/references/core-store.md create mode 100644 .trae/skills/pnpm/references/core-workspaces.md create mode 100644 .trae/skills/pnpm/references/features-aliases.md create mode 100644 .trae/skills/pnpm/references/features-catalogs.md create mode 100644 .trae/skills/pnpm/references/features-hooks.md create mode 100644 .trae/skills/pnpm/references/features-overrides.md create mode 100644 .trae/skills/pnpm/references/features-patches.md create mode 100644 .trae/skills/pnpm/references/features-peer-deps.md create mode 100644 .trae/skills/unocss/GENERATION.md create mode 100644 .trae/skills/unocss/SKILL.md create mode 100644 .trae/skills/unocss/references/core-config.md create mode 100644 .trae/skills/unocss/references/core-extracting.md create mode 100644 .trae/skills/unocss/references/core-layers.md create mode 100644 .trae/skills/unocss/references/core-rules.md create mode 100644 .trae/skills/unocss/references/core-safelist.md create mode 100644 .trae/skills/unocss/references/core-shortcuts.md create mode 100644 .trae/skills/unocss/references/core-theme.md create mode 100644 .trae/skills/unocss/references/core-variants.md create mode 100644 .trae/skills/unocss/references/integrations-nuxt.md create mode 100644 .trae/skills/unocss/references/integrations-vite.md create mode 100644 .trae/skills/unocss/references/preset-attributify.md create mode 100644 .trae/skills/unocss/references/preset-icons.md create mode 100644 .trae/skills/unocss/references/preset-mini.md create mode 100644 .trae/skills/unocss/references/preset-rem-to-px.md create mode 100644 .trae/skills/unocss/references/preset-tagify.md create mode 100644 .trae/skills/unocss/references/preset-typography.md create mode 100644 .trae/skills/unocss/references/preset-web-fonts.md create mode 100644 .trae/skills/unocss/references/preset-wind3.md create mode 100644 .trae/skills/unocss/references/preset-wind4.md create mode 100644 .trae/skills/unocss/references/transformer-attributify-jsx.md create mode 100644 .trae/skills/unocss/references/transformer-compile-class.md create mode 100644 .trae/skills/unocss/references/transformer-directives.md create mode 100644 .trae/skills/unocss/references/transformer-variant-group.md create mode 100644 .trae/skills/vite/GENERATION.md create mode 100644 .trae/skills/vite/SKILL.md create mode 100644 .trae/skills/vite/references/advanced-api.md create mode 100644 .trae/skills/vite/references/advanced-backend.md create mode 100644 .trae/skills/vite/references/advanced-performance.md create mode 100644 .trae/skills/vite/references/advanced-plugin-api.md create mode 100644 .trae/skills/vite/references/build-library.md create mode 100644 .trae/skills/vite/references/build-production.md create mode 100644 .trae/skills/vite/references/build-ssr.md create mode 100644 .trae/skills/vite/references/core-cli.md create mode 100644 .trae/skills/vite/references/core-config.md create mode 100644 .trae/skills/vite/references/core-features.md create mode 100644 .trae/skills/vite/references/core-plugins.md create mode 100644 .trae/skills/vite/references/features-assets.md create mode 100644 .trae/skills/vite/references/features-css.md create mode 100644 .trae/skills/vite/references/features-dep-bundling.md create mode 100644 .trae/skills/vite/references/features-env.md create mode 100644 .trae/skills/vite/references/features-glob-import.md create mode 100644 .trae/skills/vite/references/features-hmr.md create mode 100644 .trae/skills/vite/references/features-workers.md create mode 100644 .trae/skills/vue-best-practices/LICENSE.md create mode 100644 .trae/skills/vue-best-practices/SKILL.md create mode 100644 .trae/skills/vue-best-practices/SYNC.md create mode 100644 .trae/skills/vue-best-practices/rules/codeactions-save-performance.md create mode 100644 .trae/skills/vue-best-practices/rules/data-attributes-config.md create mode 100644 .trae/skills/vue-best-practices/rules/deep-watch-numeric.md create mode 100644 .trae/skills/vue-best-practices/rules/define-model-update-event.md create mode 100644 .trae/skills/vue-best-practices/rules/duplicate-plugin-detection.md create mode 100644 .trae/skills/vue-best-practices/rules/extract-component-props.md create mode 100644 .trae/skills/vue-best-practices/rules/fallthrough-attributes.md create mode 100644 .trae/skills/vue-best-practices/rules/hmr-vue-ssr.md create mode 100644 .trae/skills/vue-best-practices/rules/module-resolution-bundler.md create mode 100644 .trae/skills/vue-best-practices/rules/pinia-store-mocking.md create mode 100644 .trae/skills/vue-best-practices/rules/script-setup-jsdoc.md create mode 100644 .trae/skills/vue-best-practices/rules/strict-css-modules.md create mode 100644 .trae/skills/vue-best-practices/rules/volar-3-breaking-changes.md create mode 100644 .trae/skills/vue-best-practices/rules/vue-directive-comments.md create mode 100644 .trae/skills/vue-best-practices/rules/vue-router-typed-params.md create mode 100644 .trae/skills/vue-best-practices/rules/vue-tsc-strict-templates.md create mode 100644 .trae/skills/vue-best-practices/rules/with-defaults-union-types.md create mode 100644 .trae/skills/vue/GENERATION.md create mode 100644 .trae/skills/vue/SKILL.md create mode 100644 .trae/skills/vue/references/advanced-async-suspense.md create mode 100644 .trae/skills/vue/references/advanced-provide-inject.md create mode 100644 .trae/skills/vue/references/components-emits.md create mode 100644 .trae/skills/vue/references/components-lifecycle.md create mode 100644 .trae/skills/vue/references/components-props.md create mode 100644 .trae/skills/vue/references/components-slots.md create mode 100644 .trae/skills/vue/references/components-v-model.md create mode 100644 .trae/skills/vue/references/core-reactivity.md create mode 100644 .trae/skills/vue/references/features-composables.md create mode 100644 .trae/skills/vue/references/features-directives.md create mode 100644 .trae/skills/vue/references/features-script-setup.md create mode 100644 .trae/skills/vue/references/features-template-refs.md create mode 100644 .trae/skills/vue/references/features-typescript.md create mode 100644 .vscode/extensions.json create mode 100644 .vscode/settings.json create mode 100644 .vscode/unocss.json create mode 100644 .vscode/vue3.code-snippets create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README-AGENT-SYSTEM.md create mode 100644 README.md create mode 100644 build/config/index.ts create mode 100644 build/config/proxy.ts create mode 100644 build/plugins/autoImport.ts create mode 100644 build/plugins/cleanImage.ts create mode 100644 build/plugins/component.ts create mode 100644 build/plugins/index.ts create mode 100644 build/plugins/mcp.ts create mode 100644 build/plugins/replaceUrl.ts create mode 100644 build/plugins/unocss.ts create mode 100644 build/plugins/visualizer.ts create mode 100644 check-tags.cjs create mode 100644 cz.config.js create mode 100644 docs/API.md create mode 100644 docs/企业卡授权列表和设备授权列表.md create mode 100644 docs/佣金和钱包.md create mode 100644 docs/停复机.md create mode 100644 docs/资产列表(代理调用的接口).md create mode 100644 docs/资产详情.md create mode 100644 env/.env create mode 100644 env/.env.development create mode 100644 env/.env.production create mode 100644 env/.env.test create mode 100644 eslint.config.js create mode 100644 index.html create mode 100644 package.json create mode 100644 pnpm-lock.yaml create mode 100644 scripts/mini-ci.js create mode 100644 scripts/post-upgrade.js create mode 100644 scripts/verify-commit.js create mode 100644 src/App.vue create mode 100644 src/api/assets.ts create mode 100644 src/api/auth.ts create mode 100644 src/api/carrier.ts create mode 100644 src/api/commission.ts create mode 100644 src/api/common/index.ts create mode 100644 src/api/common/types.ts create mode 100644 src/api/enterprise.ts create mode 100644 src/api/index.ts create mode 100644 src/api/user/index.ts create mode 100644 src/api/user/types.ts create mode 100644 src/api/wallet.ts create mode 100644 src/api/withdrawal.ts create mode 100644 src/components/.gitkeep create mode 100644 src/components/SimplePicker.vue create mode 100644 src/components/Skeleton.vue create mode 100644 src/components/agree-privacy/index.vue create mode 100644 src/components/lang-select/index.vue create mode 100644 src/components/theme-picker/index.vue create mode 100644 src/hooks/index.ts create mode 100644 src/hooks/use-clipboard/index.ts create mode 100644 src/hooks/use-loading/index.ts create mode 100644 src/hooks/use-location/index.ts create mode 100644 src/hooks/use-location/types.ts create mode 100644 src/hooks/use-modal/index.ts create mode 100644 src/hooks/use-permission/index.ts create mode 100644 src/hooks/use-share/index.ts create mode 100644 src/hooks/use-share/types.ts create mode 100644 src/hooks/use-theme/index.ts create mode 100644 src/locales/index.ts create mode 100644 src/locales/langs/en.ts create mode 100644 src/locales/langs/zh-Hans.ts create mode 100644 src/main.ts create mode 100644 src/manifest.json create mode 100644 src/pages.json create mode 100644 src/pages/agent-system/asset-detail/index.vue create mode 100644 src/pages/agent-system/asset-search/index.vue create mode 100644 src/pages/agent-system/asset-wallet/index.vue create mode 100644 src/pages/agent-system/assets/index.vue create mode 100644 src/pages/agent-system/change-password/index.vue create mode 100644 src/pages/agent-system/commission-center/index.vue create mode 100644 src/pages/agent-system/commission/index.vue create mode 100644 src/pages/agent-system/enterprise-cards/index.vue create mode 100644 src/pages/agent-system/enterprise-devices/index.vue create mode 100644 src/pages/agent-system/home/index.vue create mode 100644 src/pages/agent-system/index.vue create mode 100644 src/pages/agent-system/my-packages/index.vue create mode 100644 src/pages/agent-system/packages/index.vue create mode 100644 src/pages/agent-system/tags/index.vue create mode 100644 src/pages/agent-system/user-info/index.vue create mode 100644 src/pages/agent-system/utils.ts create mode 100644 src/pages/agent-system/withdraw/index.vue create mode 100644 src/pages/common/404/index.vue create mode 100644 src/pages/common/login/index.vue create mode 100644 src/pages/common/theme/index.vue create mode 100644 src/pages/common/webview/index.vue create mode 100644 src/pages/tab/home/index.vue create mode 100644 src/plugins/index.ts create mode 100644 src/plugins/permission.ts create mode 100644 src/plugins/ui.ts create mode 100644 src/router/index.ts create mode 100644 src/static/icons/.gitkeep create mode 100644 src/static/icons/preview-close-one.png create mode 100644 src/static/icons/preview-open.png create mode 100644 src/static/images/404.png create mode 100644 src/static/images/logo.png create mode 100644 src/static/images/pay.png create mode 100644 src/static/styles/common.scss create mode 100644 src/static/styles/theme.scss create mode 100644 src/store/index.ts create mode 100644 src/store/modules/app/index.ts create mode 100644 src/store/modules/app/types.ts create mode 100644 src/store/modules/user/index.ts create mode 100644 src/store/modules/user/types.ts create mode 100644 src/uni.scss create mode 100644 src/utils/auth/index.ts create mode 100644 src/utils/common/index.ts create mode 100644 src/utils/format.ts create mode 100644 src/utils/index.ts create mode 100644 src/utils/modals/index.ts create mode 100644 src/utils/modals/types.ts create mode 100644 src/utils/request/index.ts create mode 100644 src/utils/request/interceptors.ts create mode 100644 src/utils/request/status.ts create mode 100644 src/utils/request/types.ts create mode 100644 src/utils/storage/index.ts create mode 100644 stylelint.config.js create mode 100644 tsconfig.json create mode 100644 types/auto-imports.d.ts create mode 100644 types/components.d.ts create mode 100644 types/env.d.ts create mode 100644 types/global.d.ts create mode 100644 types/i18n.d.ts create mode 100644 types/module.d.ts create mode 100644 uno.config.ts create mode 100644 vite.config.ts create mode 100644 代理企业管理系统-移动端.md create mode 100644 套餐列表页面说明.md create mode 100644 套餐管理系统说明.md diff --git a/.agents/skills/antfu/SKILL.md b/.agents/skills/antfu/SKILL.md new file mode 100644 index 0000000..1086d73 --- /dev/null +++ b/.agents/skills/antfu/SKILL.md @@ -0,0 +1,222 @@ +--- +name: antfu +description: Anthony Fu's {Opinionated} preferences and best practices for web development +metadata: + author: Anthony Fu + version: "2026.1.28" +--- + +# Anthony Fu's Preferences + +This skill covers Anthony Fu's preferred tooling, configurations, and best practices for web development. This skill is opinionated. + +## Quick Summary + +| Category | Preference | +|----------|------------| +| Package Manager | pnpm | +| Language | TypeScript (strict mode) | +| Module System | ESM (`"type": "module"`) | +| Linting & Formatting | @antfu/eslint-config (no Prettier) | +| Testing | Vitest | +| Git Hooks | simple-git-hooks + lint-staged | +| Documentation | VitePress (in `docs/`) | + +--- + +## Core Stack + +### Package Manager (pnpm) + +Use pnpm as the package manager. + +For monorepo setups, use pnpm workspaces: + +```yaml +# pnpm-workspace.yaml +packages: + - 'packages/*' +``` + + +Use pnpm named catalogs in `pnpm-workspace.yaml` to manage dependency versions: + +| Catalog | Purpose | +|---------|---------| +| `prod` | Production dependencies | +| `inlined` | Dependencies inlined by bundler | +| `dev` | Development tools (linter, bundler, testing, dev-server) | +| `frontend` | Frontend libraries bundled into frontend | + +Catalog names are not limited to the above and can be adjusted based on needs. Avoid using default catalog. + +#### @antfu/ni + +Use `@antfu/ni` for unified package manager commands. It auto-detects the package manager (pnpm/npm/yarn/bun) based on lockfile. + +| Command | Description | +|---------|-------------| +| `ni` | Install dependencies | +| `ni ` | Add dependency | +| `ni -D ` | Add dev dependency | +| `nr +``` diff --git a/.agents/skills/antfu/references/github-actions.md b/.agents/skills/antfu/references/github-actions.md new file mode 100644 index 0000000..378fa6e --- /dev/null +++ b/.agents/skills/antfu/references/github-actions.md @@ -0,0 +1,68 @@ +--- +name: github-actions +description: Anthony Fu's preferred GitHub Actions workflows using sxzz/workflows +--- + +# GitHub Actions + +When setting up a new project, add these workflows. Skip if workflows already exist. + +## Autofix Workflow + +**`.github/workflows/autofix.yml`** - Auto-fix linting on PRs: + +```yaml +name: autofix.ci + +on: [pull_request] + +jobs: + autofix: + uses: sxzz/workflows/.github/workflows/autofix.yml@v1 + permissions: + contents: read +``` + +## Unit Test Workflow + +**`.github/workflows/unit-test.yml`** - Run tests on push/PR: + +```yaml +name: Unit Test + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: {} + +jobs: + unit-test: + uses: sxzz/workflows/.github/workflows/unit-test.yml@v1 +``` + +## Release Workflow + +**`.github/workflows/release.yml`** - Publish on tag (library projects only): + +```yaml +name: Release + +on: + push: + tags: + - 'v*' + +jobs: + release: + uses: sxzz/workflows/.github/workflows/release.yml@v1 + with: + publish: true + permissions: + contents: write + id-token: write +``` + +All workflows use [sxzz/workflows](https://github.com/sxzz/workflows) reusable workflows. diff --git a/.agents/skills/antfu/references/gitignore.md b/.agents/skills/antfu/references/gitignore.md new file mode 100644 index 0000000..725989a --- /dev/null +++ b/.agents/skills/antfu/references/gitignore.md @@ -0,0 +1,29 @@ +--- +name: gitignore +description: Anthony Fu's preferred .gitignore for JavaScript/TypeScript projects +--- + +# .gitignore + +When `.gitignore` is not present, create it with: + +``` +*.log +*.tgz +.cache +.DS_Store +.eslintcache +.idea +.env +.nuxt +.temp +.output +.turbo +cache +coverage +dist +lib-cov +logs +node_modules +temp +``` diff --git a/.agents/skills/antfu/references/library-development.md b/.agents/skills/antfu/references/library-development.md new file mode 100644 index 0000000..8417f41 --- /dev/null +++ b/.agents/skills/antfu/references/library-development.md @@ -0,0 +1,85 @@ +--- +name: library-development +description: Anthony Fu's preferences for building and publishing JavaScript/TypeScript libraries +--- + +# Library Development Preferences + +Preferences for bundling and publishing TypeScript libraries. + +## Key Decisions + +| Aspect | Choice | +|--------|--------| +| Bundler | tsdown | +| Output | Pure ESM only (no CJS) | +| DTS | Generated via tsdown | +| Exports | Auto-generated via tsdown | + +--- + +## tsdown Configuration + +Use tsdown with these options enabled: + +```ts +// tsdown.config.ts +import { defineConfig } from 'tsdown' + +export default defineConfig({ + entry: ['src/index.ts'], + format: ['esm'], + dts: true, + exports: true, +}) +``` + +| Option | Value | Purpose | +|--------|-------|---------| +| `format` | `['esm']` | Pure ESM, no CommonJS | +| `dts` | `true` | Generate `.d.ts` files | +| `exports` | `true` | Auto-update `exports` field in `package.json` | + +### Multiple Entry Points + +```ts +export default defineConfig({ + entry: [ + 'src/index.ts', + 'src/utils.ts', + ], + format: ['esm'], + dts: true, + exports: true, +}) +``` + +The `exports: true` option auto-generates the `exports` field in `package.json` when running `tsdown`. + +--- + +## package.json + +Required fields for pure ESM library: + +```json +{ + "type": "module", + "main": "./dist/index.mjs", + "module": "./dist/index.mjs", + "types": "./dist/index.d.mts", + "files": ["dist"], + "scripts": { + "build": "tsdown", + "prepack": "pnpm build", + "test": "vitest", + "release": "bumpp -r" + } +} +``` + +The `exports` field is managed by tsdown when `exports: true`. + +### prepack Script + +For each public package, add `"prepack": "pnpm build"` to `scripts`. This ensures the package is automatically built before publishing (e.g., when running `npm publish` or `pnpm publish`). This prevents accidentally publishing stale or missing build artifacts. diff --git a/.agents/skills/antfu/references/monorepo.md b/.agents/skills/antfu/references/monorepo.md new file mode 100644 index 0000000..f1a054a --- /dev/null +++ b/.agents/skills/antfu/references/monorepo.md @@ -0,0 +1,126 @@ +--- +name: monorepo +description: Anthony Fu's monorepo setup conventions using pnpm workspaces +--- + +# Monorepo Setup + +Conventions for setting up and managing monorepos. + +## pnpm Workspaces + +Use pnpm workspaces for monorepo management: + +```yaml +# pnpm-workspace.yaml +packages: + - 'packages/*' +``` + +## Scripts Convention + +Have scripts in each package, and use `-r` (recursive) flag at root, +Enable ESLint cache for faster linting in monorepos. + +```json +// root package.json +{ + "scripts": { + "build": "pnpm run -r build", + "test": "vitest", + "lint": "eslint . --cache --concurrency=auto" + } +} +``` + +In each package's `package.json`, add the scripts. + +```json +// packages/*/package.json +{ + "scripts": { + "build": "tsdown", + "prepack": "pnpm build" + } +} +``` + +## ESLint Cache + + +```json +{ + "scripts": { + "lint": "eslint . --cache --concurrency=auto" + } +} +``` + +## Turborepo (Optional) + +For monorepos with many packages or long build times, use Turborepo for task orchestration and caching. + +See the dedicated Turborepo skill for detailed configuration. + +## Centralized Alias + +For better DX across Vite, Nuxt, Vitest configs, create a centralized `alias.ts` at project root: + +```ts +// alias.ts +import fs from 'node:fs' +import { fileURLToPath } from 'node:url' +import { join, relative } from 'pathe' + +const root = fileURLToPath(new URL('.', import.meta.url)) +const r = (path: string) => fileURLToPath(new URL(`./packages/${path}`, import.meta.url)) + +export const alias = { + '@myorg/core': r('core/src/index.ts'), + '@myorg/utils': r('utils/src/index.ts'), + '@myorg/ui': r('ui/src/index.ts'), + // Add more aliases as needed +} + +// Auto-update tsconfig.alias.json paths +const raw = fs.readFileSync(join(root, 'tsconfig.alias.json'), 'utf-8').trim() +const tsconfig = JSON.parse(raw) +tsconfig.compilerOptions.paths = Object.fromEntries( + Object.entries(alias).map(([key, value]) => [key, [`./${relative(root, value)}`]]), +) +const newRaw = JSON.stringify(tsconfig, null, 2) +if (newRaw !== raw) + fs.writeFileSync(join(root, 'tsconfig.alias.json'), `${newRaw}\n`, 'utf-8') +``` + +Then update the `tsconfig.json` to use the alias file: + +```json +{ + "extends": [ + "./tsconfig.alias.json" + ] +} +``` + +### Using Alias in Configs + +Reference the centralized alias in all config files: + +```ts +// vite.config.ts +import { alias } from './alias' + +export default defineConfig({ + resolve: { alias }, +}) +``` + +```ts +// nuxt.config.ts +import { alias } from './alias' + +export default defineNuxtConfig({ + alias, +}) +``` diff --git a/.agents/skills/antfu/references/vscode-extensions.md b/.agents/skills/antfu/references/vscode-extensions.md new file mode 100644 index 0000000..274aa77 --- /dev/null +++ b/.agents/skills/antfu/references/vscode-extensions.md @@ -0,0 +1,34 @@ +--- +name: vscode-extensions +description: Recommended VS Code extensions +--- + +# VS Code Extensions + +## Recommended Extensions + +Configure in `.vscode/extensions.json` (choose based on the needs): + +```json +{ + "recommendations": [ + "dbaeumer.vscode-eslint", + "antfu.pnpm-catalog-lens", + "antfu.iconify", + "antfu.unocss", + "antfu.slidev", + "vue.volar" + ] +} +``` + +## Extension Details + +| Extension | Description | +|-----------|-------------| +| `dbaeumer.vscode-eslint` | ESLint integration for linting and formatting | +| `antfu.pnpm-catalog-lens` | Shows pnpm catalog version hints inline | +| `antfu.iconify` | Iconify icon preview and autocomplete | +| `antfu.unocss` | UnoCSS IntelliSense and syntax highlighting | +| `antfu.slidev` | Slidev preview and syntax highlighting for presentations | +| `vue.volar` | Vue Language Features (official Vue extension) | diff --git a/.agents/skills/pinia/GENERATION.md b/.agents/skills/pinia/GENERATION.md new file mode 100644 index 0000000..a2c0f71 --- /dev/null +++ b/.agents/skills/pinia/GENERATION.md @@ -0,0 +1,5 @@ +# Generation Info + +- **Source:** `sources/pinia` +- **Git SHA:** `55dbfc5c20d4461748996aa74d8c0913e89fb98e` +- **Generated:** 2026-01-28 diff --git a/.agents/skills/pinia/SKILL.md b/.agents/skills/pinia/SKILL.md new file mode 100644 index 0000000..89cfa7d --- /dev/null +++ b/.agents/skills/pinia/SKILL.md @@ -0,0 +1,59 @@ +--- +name: pinia +description: Pinia official Vue state management library, type-safe and extensible. Use when defining stores, working with state/getters/actions, or implementing store patterns in Vue apps. +metadata: + author: Anthony Fu + version: "2026.1.28" + source: Generated from https://github.com/vuejs/pinia, scripts located at https://github.com/antfu/skills +--- + +# Pinia + +Pinia is the official state management library for Vue, designed to be intuitive and type-safe. It supports both Options API and Composition API styles, with first-class TypeScript support and devtools integration. + +> The skill is based on Pinia v3.0.4, generated at 2026-01-28. + +## Core References + +| Topic | Description | Reference | +|-------|-------------|-----------| +| Stores | Defining stores, state, getters, actions, storeToRefs, subscriptions | [core-stores](references/core-stores.md) | + +## Features + +### Extensibility + +| Topic | Description | Reference | +|-------|-------------|-----------| +| Plugins | Extend stores with custom properties, state, and behavior | [features-plugins](references/features-plugins.md) | + +### Composability + +| Topic | Description | Reference | +|-------|-------------|-----------| +| Composables | Using Vue composables within stores (VueUse, etc.) | [features-composables](references/features-composables.md) | +| Composing Stores | Store-to-store communication, avoiding circular dependencies | [features-composing-stores](references/features-composing-stores.md) | + +## Best Practices + +| Topic | Description | Reference | +|-------|-------------|-----------| +| Testing | Unit testing with @pinia/testing, mocking, stubbing | [best-practices-testing](references/best-practices-testing.md) | +| Outside Components | Using stores in navigation guards, plugins, middlewares | [best-practices-outside-component](references/best-practices-outside-component.md) | + +## Advanced + +| Topic | Description | Reference | +|-------|-------------|-----------| +| SSR | Server-side rendering, state hydration | [advanced-ssr](references/advanced-ssr.md) | +| Nuxt | Nuxt integration, auto-imports, SSR best practices | [advanced-nuxt](references/advanced-nuxt.md) | +| HMR | Hot module replacement for development | [advanced-hmr](references/advanced-hmr.md) | + +## Key Recommendations + +- **Prefer Setup Stores** for complex logic, composables, and watchers +- **Use `storeToRefs()`** when destructuring state/getters to preserve reactivity +- **Actions can be destructured directly** - they're bound to the store +- **Call stores inside functions** not at module scope, especially for SSR +- **Add HMR support** to each store for better development experience +- **Use `@pinia/testing`** for component tests with mocked stores diff --git a/.agents/skills/pinia/references/advanced-hmr.md b/.agents/skills/pinia/references/advanced-hmr.md new file mode 100644 index 0000000..3eef5c7 --- /dev/null +++ b/.agents/skills/pinia/references/advanced-hmr.md @@ -0,0 +1,61 @@ +--- +name: hot-module-replacement +description: Enable HMR to preserve store state during development +--- + +# Hot Module Replacement (HMR) + +Pinia supports HMR to edit stores without page reload, preserving existing state. + +## Setup + +Add this snippet after each store definition: + +```ts +import { defineStore, acceptHMRUpdate } from 'pinia' + +export const useAuth = defineStore('auth', { + // store options... +}) + +if (import.meta.hot) { + import.meta.hot.accept(acceptHMRUpdate(useAuth, import.meta.hot)) +} +``` + +## Setup Store Example + +```ts +import { defineStore, acceptHMRUpdate } from 'pinia' + +export const useCounterStore = defineStore('counter', () => { + const count = ref(0) + const increment = () => count.value++ + return { count, increment } +}) + +if (import.meta.hot) { + import.meta.hot.accept(acceptHMRUpdate(useCounterStore, import.meta.hot)) +} +``` + +## Bundler Support + +- **Vite:** Officially supported via `import.meta.hot` +- **Webpack:** Uses `import.meta.webpackHot` +- Any bundler implementing the `import.meta.hot` spec should work + +## Nuxt + +With `@pinia/nuxt`, `acceptHMRUpdate` is auto-imported but you still need to add the HMR snippet manually. + +## Benefits + +- Edit store logic without losing state +- Add/remove state, actions, and getters on the fly +- Faster development iteration + + diff --git a/.agents/skills/pinia/references/advanced-nuxt.md b/.agents/skills/pinia/references/advanced-nuxt.md new file mode 100644 index 0000000..569da63 --- /dev/null +++ b/.agents/skills/pinia/references/advanced-nuxt.md @@ -0,0 +1,119 @@ +--- +name: nuxt-integration +description: Using Pinia with Nuxt - auto-imports, SSR, and best practices +--- + +# Nuxt Integration + +Pinia works seamlessly with Nuxt 3/4, handling SSR, serialization, and XSS protection automatically. + +## Installation + +```bash +npx nuxi@latest module add pinia +``` + +This installs both `@pinia/nuxt` and `pinia`. If `pinia` isn't installed, add it manually. + +> **npm users:** If you get `ERESOLVE unable to resolve dependency tree`, add to `package.json`: +> ```json +> "overrides": { "vue": "latest" } +> ``` + +## Configuration + +```ts +// nuxt.config.ts +export default defineNuxtConfig({ + modules: ['@pinia/nuxt'], +}) +``` + +## Auto Imports + +These are automatically available: +- `usePinia()` - get pinia instance +- `defineStore()` - define stores +- `storeToRefs()` - extract reactive refs +- `acceptHMRUpdate()` - HMR support + +**All stores in `app/stores/` (Nuxt 4) or `stores/` are auto-imported.** + +### Custom Store Directories + +```ts +// nuxt.config.ts +export default defineNuxtConfig({ + modules: ['@pinia/nuxt'], + pinia: { + storesDirs: ['./stores/**', './custom-folder/stores/**'], + }, +}) +``` + +## Fetching Data in Pages + +Use `callOnce()` for SSR-friendly data fetching: + +```vue + +``` + +### Refetch on Navigation + +```vue + +``` + +## Using Stores Outside Components + +In navigation guards, middlewares, or other stores, pass the `pinia` instance: + +```ts +// middleware/auth.ts +export default defineNuxtRouteMiddleware((to) => { + const nuxtApp = useNuxtApp() + const store = useStore(nuxtApp.$pinia) + + if (to.meta.requiresAuth && !store.isLoggedIn) { + return navigateTo('/login') + } +}) +``` + +Most of the time, you don't need this - just use stores in components or other injection-aware contexts. + +## Pinia Plugins with Nuxt + +Create a Nuxt plugin: + +```ts +// plugins/myPiniaPlugin.ts +import { PiniaPluginContext } from 'pinia' + +function MyPiniaPlugin({ store }: PiniaPluginContext) { + store.$subscribe((mutation) => { + console.log(`[🍍 ${mutation.storeId}]: ${mutation.type}`) + }) + return { creationTime: new Date() } +} + +export default defineNuxtPlugin(({ $pinia }) => { + $pinia.use(MyPiniaPlugin) +}) +``` + + diff --git a/.agents/skills/pinia/references/advanced-ssr.md b/.agents/skills/pinia/references/advanced-ssr.md new file mode 100644 index 0000000..2972f3a --- /dev/null +++ b/.agents/skills/pinia/references/advanced-ssr.md @@ -0,0 +1,121 @@ +--- +name: server-side-rendering +description: SSR setup, state hydration, and avoiding cross-request state pollution +--- + +# Server Side Rendering (SSR) + +Pinia works with SSR when stores are called at the top of `setup`, getters, or actions. + +> **Using Nuxt?** See the [Nuxt integration](advanced-nuxt.md) instead. + +## Basic Usage + +```vue + +``` + +## Using Store Outside setup() + +Pass the `pinia` instance explicitly: + +```ts +const pinia = createPinia() +const app = createApp(App) +app.use(router) +app.use(pinia) + +router.beforeEach((to) => { + // ✅ Pass pinia for correct SSR context + const main = useMainStore(pinia) + + if (to.meta.requiresAuth && !main.isLoggedIn) { + return '/login' + } +}) +``` + +## serverPrefetch() + +Access pinia via `this.$pinia`: + +```ts +export default { + serverPrefetch() { + const store = useStore(this.$pinia) + return store.fetchData() + }, +} +``` + +## onServerPrefetch() + +Works normally: + +```vue + +``` + +## State Hydration + +Serialize state on server and hydrate on client. + +### Server Side + +Use [devalue](https://github.com/Rich-Harris/devalue) for XSS-safe serialization: + +```ts +import devalue from 'devalue' +import { createPinia } from 'pinia' + +const pinia = createPinia() +const app = createApp(App) +app.use(router) +app.use(pinia) + +// After rendering, state is available +const serializedState = devalue(pinia.state.value) +// Inject into HTML as global variable +``` + +### Client Side + +Hydrate before any `useStore()` call: + +```ts +const pinia = createPinia() +const app = createApp(App) +app.use(pinia) + +// Hydrate from serialized state (e.g., from window.__pinia) +if (typeof window !== 'undefined') { + pinia.state.value = JSON.parse(window.__pinia) +} +``` + +## SSR Examples + +- [Vitesse template](https://github.com/antfu/vitesse/blob/main/src/modules/pinia.ts) +- [vite-plugin-ssr](https://vite-plugin-ssr.com/pinia) + +## Key Points + +1. Call stores inside functions, not at module scope +2. Pass `pinia` instance when using stores outside components in SSR +3. Hydrate state before calling any `useStore()` +4. Use `devalue` or similar for safe serialization +5. Avoid cross-request state pollution by creating fresh pinia per request + + diff --git a/.agents/skills/pinia/references/best-practices-outside-component.md b/.agents/skills/pinia/references/best-practices-outside-component.md new file mode 100644 index 0000000..126f7a6 --- /dev/null +++ b/.agents/skills/pinia/references/best-practices-outside-component.md @@ -0,0 +1,115 @@ +--- +name: using-stores-outside-components +description: Correctly using stores in navigation guards, plugins, and other non-component contexts +--- + +# Using Stores Outside Components + +Stores need the `pinia` instance, which is automatically injected in components. Outside components, you may need to provide it manually. + +## Single Page Applications + +Call stores **after** pinia is installed: + +```ts +import { useUserStore } from '@/stores/user' +import { createPinia } from 'pinia' +import { createApp } from 'vue' +import App from './App.vue' + +// ❌ Fails - pinia not created yet +const userStore = useUserStore() + +const pinia = createPinia() +const app = createApp(App) +app.use(pinia) + +// ✅ Works - pinia is active +const userStore = useUserStore() +``` + +## Navigation Guards + +**Wrong:** Call at module level + +```ts +import { createRouter } from 'vue-router' +const router = createRouter({ /* ... */ }) + +// ❌ May fail depending on import order +const store = useUserStore() + +router.beforeEach((to) => { + if (store.isLoggedIn) { /* ... */ } +}) +``` + +**Correct:** Call inside the guard + +```ts +router.beforeEach((to) => { + // ✅ Called after pinia is installed + const store = useUserStore() + + if (to.meta.requiresAuth && !store.isLoggedIn) { + return '/login' + } +}) +``` + +## SSR Applications + +Always pass the `pinia` instance to `useStore()`: + +```ts +const pinia = createPinia() +const app = createApp(App) +app.use(router) +app.use(pinia) + +router.beforeEach((to) => { + // ✅ Pass pinia instance + const main = useMainStore(pinia) + + if (to.meta.requiresAuth && !main.isLoggedIn) { + return '/login' + } +}) +``` + +## serverPrefetch() + +Access pinia via `this.$pinia`: + +```ts +export default { + serverPrefetch() { + const store = useStore(this.$pinia) + return store.fetchData() + }, +} +``` + +## onServerPrefetch() + +Works normally in ` +``` + +## Key Takeaway + +Defer `useStore()` calls to functions that run after pinia is installed, rather than calling at module scope. + + diff --git a/.agents/skills/pinia/references/best-practices-testing.md b/.agents/skills/pinia/references/best-practices-testing.md new file mode 100644 index 0000000..7227cd4 --- /dev/null +++ b/.agents/skills/pinia/references/best-practices-testing.md @@ -0,0 +1,212 @@ +--- +name: testing +description: Unit testing stores and components with @pinia/testing +--- + +# Testing Stores + +## Unit Testing Stores + +Create a fresh pinia instance for each test: + +```ts +import { setActivePinia, createPinia } from 'pinia' +import { useCounterStore } from '../src/stores/counter' + +describe('Counter Store', () => { + beforeEach(() => { + setActivePinia(createPinia()) + }) + + it('increments', () => { + const counter = useCounterStore() + expect(counter.n).toBe(0) + counter.increment() + expect(counter.n).toBe(1) + }) +}) +``` + +### With Plugins + +```ts +import { setActivePinia, createPinia } from 'pinia' +import { createApp } from 'vue' +import { somePlugin } from '../src/stores/plugin' + +const app = createApp({}) + +beforeEach(() => { + const pinia = createPinia().use(somePlugin) + app.use(pinia) + setActivePinia(pinia) +}) +``` + +## Testing Components + +Install `@pinia/testing`: + +```bash +npm i -D @pinia/testing +``` + +Use `createTestingPinia()`: + +```ts +import { mount } from '@vue/test-utils' +import { createTestingPinia } from '@pinia/testing' +import { useSomeStore } from '@/stores/myStore' + +const wrapper = mount(Counter, { + global: { + plugins: [createTestingPinia()], + }, +}) + +const store = useSomeStore() + +// Manipulate state directly +store.name = 'new name' +store.$patch({ name: 'new name' }) + +// Actions are stubbed by default +store.someAction() +expect(store.someAction).toHaveBeenCalledTimes(1) +``` + +## Initial State + +Set initial state for tests: + +```ts +const wrapper = mount(Counter, { + global: { + plugins: [ + createTestingPinia({ + initialState: { + counter: { n: 20 }, // Store name → initial state + }, + }), + ], + }, +}) +``` + +## Action Stubbing + +### Execute Real Actions + +```ts +createTestingPinia({ stubActions: false }) +``` + +### Selective Stubbing + +```ts +// Only stub specific actions +createTestingPinia({ + stubActions: ['increment', 'reset'], +}) + +// Or use a function +createTestingPinia({ + stubActions: (actionName, store) => { + if (actionName.startsWith('set')) return true + return false + }, +}) +``` + +### Mock Action Return Values + +```ts +import type { Mock } from 'vitest' + +// After getting store +store.someAction.mockResolvedValue('mocked value') +``` + +## Mocking Getters + +Getters are writable in tests: + +```ts +const pinia = createTestingPinia() +const counter = useCounterStore(pinia) + +counter.double = 3 // Override computed value + +// Reset to default behavior +counter.double = undefined +counter.double // Now computed normally +``` + +## Custom Spy Function + +If not using Jest/Vitest with globals: + +```ts +import { vi } from 'vitest' + +createTestingPinia({ + createSpy: vi.fn, +}) +``` + +With Sinon: + +```ts +import sinon from 'sinon' + +createTestingPinia({ + createSpy: sinon.spy, +}) +``` + +## Pinia Plugins in Tests + +Pass plugins to `createTestingPinia()`: + +```ts +import { somePlugin } from '../src/stores/plugin' + +createTestingPinia({ + stubActions: false, + plugins: [somePlugin], +}) +``` + +**Don't use** `testingPinia.use(MyPlugin)` - pass plugins in options. + +## Type-Safe Mocked Store + +```ts +import type { Mock } from 'vitest' +import type { Store, StoreDefinition } from 'pinia' + +function mockedStore unknown>( + useStore: TStoreDef +): TStoreDef extends StoreDefinition + ? Store, { + [K in keyof Actions]: Actions[K] extends (...args: any[]) => any + ? Mock + : Actions[K] + }> + : ReturnType { + return useStore() as any +} + +// Usage +const store = mockedStore(useSomeStore) +store.someAction.mockResolvedValue('value') // Typed! +``` + +## E2E Tests + +No special handling needed - Pinia works normally. + + diff --git a/.agents/skills/pinia/references/core-stores.md b/.agents/skills/pinia/references/core-stores.md new file mode 100644 index 0000000..ea6a72b --- /dev/null +++ b/.agents/skills/pinia/references/core-stores.md @@ -0,0 +1,389 @@ +--- +name: stores +description: Defining stores, state, getters, and actions in Pinia +--- + +# Pinia Stores + +Stores are defined using `defineStore()` with a unique name. Each store has three core concepts: **state**, **getters**, and **actions**. + +## Defining Stores + +### Option Stores + +Similar to Vue's Options API: + +```ts +import { defineStore } from 'pinia' + +export const useCounterStore = defineStore('counter', { + state: () => ({ + count: 0, + name: 'Eduardo', + }), + getters: { + doubleCount: (state) => state.count * 2, + }, + actions: { + increment() { + this.count++ + }, + }, +}) +``` + +Think of `state` as `data`, `getters` as `computed`, and `actions` as `methods`. + +### Setup Stores (Recommended) + +Uses Composition API syntax - more flexible and powerful: + +```ts +import { ref, computed } from 'vue' +import { defineStore } from 'pinia' + +export const useCounterStore = defineStore('counter', () => { + const count = ref(0) + const name = ref('Eduardo') + const doubleCount = computed(() => count.value * 2) + + function increment() { + count.value++ + } + + return { count, name, doubleCount, increment } +}) +``` + +In Setup Stores: `ref()` → state, `computed()` → getters, `function()` → actions. + +**Important:** You must return all state properties for Pinia to track them. + +### Using Stores + +```vue + +``` + +### Destructuring with storeToRefs + +```vue + +``` + +--- + +## State + +State is defined as a function returning the initial state. + +### TypeScript + +Type inference works automatically. For complex types: + +```ts +interface UserInfo { + name: string + age: number +} + +export const useUserStore = defineStore('user', { + state: () => ({ + userList: [] as UserInfo[], + user: null as UserInfo | null, + }), +}) +``` + +Or use an interface for the return type: + +```ts +interface State { + userList: UserInfo[] + user: UserInfo | null +} + +export const useUserStore = defineStore('user', { + state: (): State => ({ + userList: [], + user: null, + }), +}) +``` + +### Accessing and Modifying + +```ts +const store = useStore() +store.count++ +``` + +```vue + +``` + +### Mutating with $patch + +Apply multiple changes at once: + +```ts +// Object syntax +store.$patch({ + count: store.count + 1, + name: 'DIO', +}) + +// Function syntax (for complex mutations) +store.$patch((state) => { + state.items.push({ name: 'shoes', quantity: 1 }) + state.hasChanged = true +}) +``` + +### Resetting State + +Option Stores have built-in `$reset()`. For Setup Stores, implement your own: + +```ts +export const useCounterStore = defineStore('counter', () => { + const count = ref(0) + + function $reset() { + count.value = 0 + } + + return { count, $reset } +}) +``` + +### Subscribing to State Changes + +```ts +cartStore.$subscribe((mutation, state) => { + mutation.type // 'direct' | 'patch object' | 'patch function' + mutation.storeId // 'cart' + mutation.payload // patch object (only for 'patch object') + + localStorage.setItem('cart', JSON.stringify(state)) +}) + +// Options +cartStore.$subscribe(callback, { flush: 'sync' }) // Immediate +cartStore.$subscribe(callback, { detached: true }) // Keep after unmount +``` + +--- + +## Getters + +Getters are computed values, equivalent to Vue's `computed()`. + +### Basic Getters + +```ts +getters: { + doubleCount: (state) => state.count * 2, +} +``` + +### Accessing Other Getters + +Use `this` with explicit return type: + +```ts +getters: { + doubleCount: (state) => state.count * 2, + doublePlusOne(): number { + return this.doubleCount + 1 + }, +}, +``` + +### Getters with Arguments + +Return a function (note: loses caching): + +```ts +getters: { + getUserById: (state) => { + return (userId: string) => state.users.find((user) => user.id === userId) + }, +}, +``` + +Cache within parameterized getters: + +```ts +getters: { + getActiveUserById(state) { + const activeUsers = state.users.filter((user) => user.active) + return (userId: string) => activeUsers.find((user) => user.id === userId) + }, +}, +``` + +### Accessing Other Stores in Getters + +```ts +import { useOtherStore } from './other-store' + +getters: { + combined(state) { + const otherStore = useOtherStore() + return state.localData + otherStore.data + }, +}, +``` + +--- + +## Actions + +Actions are methods for business logic. Unlike getters, they can be asynchronous. + +### Defining Actions + +```ts +actions: { + increment() { + this.count++ + }, + randomizeCounter() { + this.count = Math.round(100 * Math.random()) + }, +}, +``` + +### Async Actions + +```ts +actions: { + async registerUser(login: string, password: string) { + try { + this.userData = await api.post({ login, password }) + } catch (error) { + return error + } + }, +}, +``` + +### Accessing Other Stores in Actions + +```ts +import { useAuthStore } from './auth-store' + +actions: { + async fetchUserPreferences() { + const auth = useAuthStore() + if (auth.isAuthenticated) { + this.preferences = await fetchPreferences() + } + }, +}, +``` + +**SSR:** Call all `useStore()` before any `await`: + +```ts +async orderCart() { + // ✅ Call stores before await + const user = useUserStore() + + await apiOrderCart(user.token, this.items) + // ❌ Don't call useStore() after await in SSR +} +``` + +### Subscribing to Actions + +```ts +const unsubscribe = someStore.$onAction( + ({ name, store, args, after, onError }) => { + const startTime = Date.now() + console.log(`Start "${name}" with params [${args.join(', ')}]`) + + after((result) => { + console.log(`Finished "${name}" after ${Date.now() - startTime}ms`) + }) + + onError((error) => { + console.warn(`Failed "${name}": ${error}`) + }) + } +) + +unsubscribe() // Cleanup +``` + +Keep subscription after component unmount: + +```ts +someStore.$onAction(callback, true) +``` + +--- + +## Options API Helpers + +```ts +import { mapState, mapWritableState, mapActions } from 'pinia' +import { useCounterStore } from '../stores/counter' + +export default { + computed: { + // Readonly state/getters + ...mapState(useCounterStore, ['count', 'doubleCount']), + // Writable state + ...mapWritableState(useCounterStore, ['count']), + }, + methods: { + ...mapActions(useCounterStore, ['increment']), + }, +} +``` + +--- + +## Accessing Global Providers in Setup Stores + +```ts +import { inject } from 'vue' +import { useRoute } from 'vue-router' +import { defineStore } from 'pinia' + +export const useSearchFilters = defineStore('search-filters', () => { + const route = useRoute() + const appProvided = inject('appProvided') + + // Don't return these - access them directly in components + return { /* ... */ } +}) +``` + + diff --git a/.agents/skills/pinia/references/features-composables.md b/.agents/skills/pinia/references/features-composables.md new file mode 100644 index 0000000..79f7d94 --- /dev/null +++ b/.agents/skills/pinia/references/features-composables.md @@ -0,0 +1,114 @@ +--- +name: composables-in-stores +description: Using Vue composables within Pinia stores +--- + +# Composables in Stores + +Pinia stores can leverage Vue composables for reusable stateful logic. + +## Option Stores + +Call composables inside the `state` property, but only those returning writable refs: + +```ts +import { defineStore } from 'pinia' +import { useLocalStorage } from '@vueuse/core' + +export const useAuthStore = defineStore('auth', { + state: () => ({ + user: useLocalStorage('pinia/auth/login', 'bob'), + }), +}) +``` + +**Works:** Composables returning `ref()`: +- `useLocalStorage` +- `useAsyncState` + +**Doesn't work in Option Stores:** +- Composables exposing functions +- Composables exposing readonly data + +## Setup Stores + +More flexible - can use almost any composable: + +```ts +import { defineStore } from 'pinia' +import { useMediaControls } from '@vueuse/core' +import { ref } from 'vue' + +export const useVideoPlayer = defineStore('video', () => { + const videoElement = ref() + const src = ref('/data/video.mp4') + const { playing, volume, currentTime, togglePictureInPicture } = + useMediaControls(videoElement, { src }) + + function loadVideo(element: HTMLVideoElement, newSrc: string) { + videoElement.value = element + src.value = newSrc + } + + return { + src, + playing, + volume, + currentTime, + loadVideo, + togglePictureInPicture, + } +}) +``` + +**Note:** Don't return non-serializable DOM refs like `videoElement` - they're internal implementation details. + +## SSR Considerations + +### Option Stores with hydrate() + +Define a `hydrate()` function to handle client-side hydration: + +```ts +import { defineStore } from 'pinia' +import { useLocalStorage } from '@vueuse/core' + +export const useAuthStore = defineStore('auth', { + state: () => ({ + user: useLocalStorage('pinia/auth/login', 'bob'), + }), + + hydrate(state, initialState) { + // Ignore server state, read from browser + state.user = useLocalStorage('pinia/auth/login', 'bob') + }, +}) +``` + +### Setup Stores with skipHydrate() + +Mark state that shouldn't hydrate from server: + +```ts +import { defineStore, skipHydrate } from 'pinia' +import { useEyeDropper, useLocalStorage } from '@vueuse/core' + +export const useColorStore = defineStore('colors', () => { + const { isSupported, open, sRGBHex } = useEyeDropper() + const lastColor = useLocalStorage('lastColor', sRGBHex) + + return { + // Skip hydration for client-only state + lastColor: skipHydrate(lastColor), + open, // Function - no hydration needed + isSupported, // Boolean - not reactive + } +}) +``` + +`skipHydrate()` only applies to state properties (refs), not functions or non-reactive values. + + diff --git a/.agents/skills/pinia/references/features-composing-stores.md b/.agents/skills/pinia/references/features-composing-stores.md new file mode 100644 index 0000000..948f8b5 --- /dev/null +++ b/.agents/skills/pinia/references/features-composing-stores.md @@ -0,0 +1,134 @@ +--- +name: composing-stores +description: Store-to-store communication and avoiding circular dependencies +--- + +# Composing Stores + +Stores can use each other for shared state and logic. + +## Rule: Avoid Circular Dependencies + +Two stores cannot directly read each other's state during setup: + +```ts +// ❌ Infinite loop +const useX = defineStore('x', () => { + const y = useY() + y.name // Don't read here! + return { name: ref('X') } +}) + +const useY = defineStore('y', () => { + const x = useX() + x.name // Don't read here! + return { name: ref('Y') } +}) +``` + +**Solution:** Read in getters, computed, or actions: + +```ts +const useX = defineStore('x', () => { + const y = useY() + + // ✅ Read in computed/actions + function doSomething() { + const yName = y.name + } + + return { name: ref('X'), doSomething } +}) +``` + +## Setup Stores: Use Store at Top + +```ts +import { defineStore } from 'pinia' +import { useUserStore } from './user' + +export const useCartStore = defineStore('cart', () => { + const user = useUserStore() + const list = ref([]) + + const summary = computed(() => { + return `Hi ${user.name}, you have ${list.value.length} items` + }) + + function purchase() { + return apiPurchase(user.id, list.value) + } + + return { list, summary, purchase } +}) +``` + +## Shared Getters + +Call `useStore()` inside a getter: + +```ts +import { useUserStore } from './user' + +export const useCartStore = defineStore('cart', { + getters: { + summary(state) { + const user = useUserStore() + return `Hi ${user.name}, you have ${state.list.length} items` + }, + }, +}) +``` + +## Shared Actions + +Call `useStore()` inside an action: + +```ts +import { useUserStore } from './user' +import { apiOrderCart } from './api' + +export const useCartStore = defineStore('cart', { + actions: { + async orderCart() { + const user = useUserStore() + + try { + await apiOrderCart(user.token, this.items) + this.emptyCart() + } catch (err) { + displayError(err) + } + }, + }, +}) +``` + +## SSR: Call Stores Before Await + +In async actions, call all stores before any `await`: + +```ts +actions: { + async orderCart() { + // ✅ All useStore() calls before await + const user = useUserStore() + const analytics = useAnalyticsStore() + + try { + await apiOrderCart(user.token, this.items) + // ❌ Don't call useStore() after await (SSR issue) + // const otherStore = useOtherStore() + } catch (err) { + displayError(err) + } + }, +} +``` + +This ensures the correct Pinia instance is used during SSR. + + diff --git a/.agents/skills/pinia/references/features-plugins.md b/.agents/skills/pinia/references/features-plugins.md new file mode 100644 index 0000000..c4355ac --- /dev/null +++ b/.agents/skills/pinia/references/features-plugins.md @@ -0,0 +1,203 @@ +--- +name: plugins +description: Extend stores with custom properties, methods, and behavior +--- + +# Plugins + +Plugins extend all stores with custom properties, methods, or behavior. + +## Basic Plugin + +```ts +import { createPinia } from 'pinia' + +function SecretPiniaPlugin() { + return { secret: 'the cake is a lie' } +} + +const pinia = createPinia() +pinia.use(SecretPiniaPlugin) + +// In any store +const store = useStore() +store.secret // 'the cake is a lie' +``` + +## Plugin Context + +Plugins receive a context object: + +```ts +import { PiniaPluginContext } from 'pinia' + +export function myPiniaPlugin(context: PiniaPluginContext) { + context.pinia // pinia instance + context.app // Vue app instance + context.store // store being augmented + context.options // store definition options +} +``` + +## Adding Properties + +Return an object to add properties (tracked in devtools): + +```ts +pinia.use(() => ({ hello: 'world' })) +``` + +Or set directly on store: + +```ts +pinia.use(({ store }) => { + store.hello = 'world' + // For devtools visibility in dev mode + if (process.env.NODE_ENV === 'development') { + store._customProperties.add('hello') + } +}) +``` + +## Adding State + +Add to both `store` and `store.$state` for SSR/devtools: + +```ts +import { toRef, ref } from 'vue' + +pinia.use(({ store }) => { + if (!store.$state.hasOwnProperty('hasError')) { + const hasError = ref(false) + store.$state.hasError = hasError + } + store.hasError = toRef(store.$state, 'hasError') +}) +``` + +## Adding External Properties + +Wrap non-reactive objects with `markRaw()`: + +```ts +import { markRaw } from 'vue' +import { router } from './router' + +pinia.use(({ store }) => { + store.router = markRaw(router) +}) +``` + +## Custom Store Options + +Define custom options consumed by plugins: + +```ts +// Store definition +defineStore('search', { + actions: { + searchContacts() { /* ... */ }, + }, + debounce: { + searchContacts: 300, + }, +}) + +// Plugin reads custom option +import debounce from 'lodash/debounce' + +pinia.use(({ options, store }) => { + if (options.debounce) { + return Object.keys(options.debounce).reduce((acc, action) => { + acc[action] = debounce(store[action], options.debounce[action]) + return acc + }, {}) + } +}) +``` + +For Setup Stores, pass options as third argument: + +```ts +defineStore( + 'search', + () => { /* ... */ }, + { + debounce: { searchContacts: 300 }, + } +) +``` + +## TypeScript Augmentation + +### Custom Properties + +```ts +import 'pinia' +import type { Router } from 'vue-router' + +declare module 'pinia' { + export interface PiniaCustomProperties { + router: Router + hello: string + } +} +``` + +### Custom State + +```ts +declare module 'pinia' { + export interface PiniaCustomStateProperties { + hasError: boolean + } +} +``` + +### Custom Options + +```ts +declare module 'pinia' { + export interface DefineStoreOptionsBase { + debounce?: Partial, number>> + } +} +``` + +## Subscribe in Plugins + +```ts +pinia.use(({ store }) => { + store.$subscribe(() => { + // React to state changes + }) + store.$onAction(() => { + // React to actions + }) +}) +``` + +## Nuxt Plugin + +Create a Nuxt plugin to add Pinia plugins: + +```ts +// plugins/myPiniaPlugin.ts +import { PiniaPluginContext } from 'pinia' + +function MyPiniaPlugin({ store }: PiniaPluginContext) { + store.$subscribe((mutation) => { + console.log(`[🍍 ${mutation.storeId}]: ${mutation.type}`) + }) + return { creationTime: new Date() } +} + +export default defineNuxtPlugin(({ $pinia }) => { + $pinia.use(MyPiniaPlugin) +}) +``` + + diff --git a/.agents/skills/pnpm/GENERATION.md b/.agents/skills/pnpm/GENERATION.md new file mode 100644 index 0000000..f650dd7 --- /dev/null +++ b/.agents/skills/pnpm/GENERATION.md @@ -0,0 +1,5 @@ +# Generation Info + +- **Source:** `sources/pnpm` +- **Git SHA:** `a1d6d5aef9d5f369fa2f0d8a54f1edbaff8b23b3` +- **Generated:** 2026-01-28 diff --git a/.agents/skills/pnpm/SKILL.md b/.agents/skills/pnpm/SKILL.md new file mode 100644 index 0000000..9b28506 --- /dev/null +++ b/.agents/skills/pnpm/SKILL.md @@ -0,0 +1,42 @@ +--- +name: pnpm +description: Node.js package manager with strict dependency resolution. Use when running pnpm specific commands, configuring workspaces, or managing dependencies with catalogs, patches, or overrides. +metadata: + author: Anthony Fu + version: "2026.1.28" + source: Generated from https://github.com/pnpm/pnpm, scripts located at https://github.com/antfu/skills +--- + +pnpm is a fast, disk space efficient package manager. It uses a content-addressable store to deduplicate packages across all projects on a machine, saving significant disk space. pnpm enforces strict dependency resolution by default, preventing phantom dependencies. Configuration should preferably be placed in `pnpm-workspace.yaml` for pnpm-specific settings. + +**Important:** When working with pnpm projects, agents should check for `pnpm-workspace.yaml` and `.npmrc` files to understand workspace structure and configuration. Always use `--frozen-lockfile` in CI environments. + +> The skill is based on pnpm 10.x, generated at 2026-01-28. + +## Core + +| Topic | Description | Reference | +|-------|-------------|-----------| +| CLI Commands | Install, add, remove, update, run, exec, dlx, and workspace commands | [core-cli](references/core-cli.md) | +| Configuration | pnpm-workspace.yaml, .npmrc settings, and package.json fields | [core-config](references/core-config.md) | +| Workspaces | Monorepo support with filtering, workspace protocol, and shared lockfile | [core-workspaces](references/core-workspaces.md) | +| Store | Content-addressable storage, hard links, and disk efficiency | [core-store](references/core-store.md) | + +## Features + +| Topic | Description | Reference | +|-------|-------------|-----------| +| Catalogs | Centralized dependency version management for workspaces | [features-catalogs](references/features-catalogs.md) | +| Overrides | Force specific versions of dependencies including transitive | [features-overrides](references/features-overrides.md) | +| Patches | Modify third-party packages with custom fixes | [features-patches](references/features-patches.md) | +| Aliases | Install packages under custom names using npm: protocol | [features-aliases](references/features-aliases.md) | +| Hooks | Customize resolution with .pnpmfile.cjs hooks | [features-hooks](references/features-hooks.md) | +| Peer Dependencies | Auto-install, strict mode, and dependency rules | [features-peer-deps](references/features-peer-deps.md) | + +## Best Practices + +| Topic | Description | Reference | +|-------|-------------|-----------| +| CI/CD Setup | GitHub Actions, GitLab CI, Docker, and caching strategies | [best-practices-ci](references/best-practices-ci.md) | +| Migration | Migrating from npm/Yarn, handling phantom deps, monorepo migration | [best-practices-migration](references/best-practices-migration.md) | +| Performance | Install optimizations, store caching, workspace parallelization | [best-practices-performance](references/best-practices-performance.md) | diff --git a/.agents/skills/pnpm/references/best-practices-ci.md b/.agents/skills/pnpm/references/best-practices-ci.md new file mode 100644 index 0000000..80c5d49 --- /dev/null +++ b/.agents/skills/pnpm/references/best-practices-ci.md @@ -0,0 +1,285 @@ +--- +name: pnpm-ci-cd-setup +description: Optimizing pnpm for continuous integration and deployment workflows +--- + +# pnpm CI/CD Setup + +Best practices for using pnpm in CI/CD environments for fast, reliable builds. + +## GitHub Actions + +### Basic Setup + +```yaml +name: CI + +on: [push, pull_request] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v4 + with: + version: 9 + + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'pnpm' + + - run: pnpm install --frozen-lockfile + - run: pnpm test + - run: pnpm build +``` + +### With Store Caching + +For larger projects, cache the pnpm store: + +```yaml +- uses: pnpm/action-setup@v4 + with: + version: 9 + +- name: Get pnpm store directory + shell: bash + run: | + echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV + +- uses: actions/cache@v4 + name: Setup pnpm cache + with: + path: ${{ env.STORE_PATH }} + key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-pnpm-store- + +- run: pnpm install --frozen-lockfile +``` + +### Matrix Testing + +```yaml +jobs: + test: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + node: [18, 20, 22] + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node }} + cache: 'pnpm' + - run: pnpm install --frozen-lockfile + - run: pnpm test +``` + +## GitLab CI + +```yaml +image: node:20 + +stages: + - install + - test + - build + +variables: + PNPM_HOME: /root/.local/share/pnpm + PATH: $PNPM_HOME:$PATH + +before_script: + - corepack enable + - corepack prepare pnpm@latest --activate + +cache: + key: ${CI_COMMIT_REF_SLUG} + paths: + - .pnpm-store + +install: + stage: install + script: + - pnpm config set store-dir .pnpm-store + - pnpm install --frozen-lockfile + +test: + stage: test + script: + - pnpm test + +build: + stage: build + script: + - pnpm build +``` + +## Docker + +### Multi-Stage Build + +```dockerfile +# Build stage +FROM node:20-slim AS builder + +# Enable corepack for pnpm +RUN corepack enable + +WORKDIR /app + +# Copy package files first for layer caching +COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./ +COPY packages/*/package.json ./packages/ + +# Install dependencies +RUN pnpm install --frozen-lockfile + +# Copy source and build +COPY . . +RUN pnpm build + +# Production stage +FROM node:20-slim AS runner + +RUN corepack enable +WORKDIR /app + +COPY --from=builder /app/dist ./dist +COPY --from=builder /app/package.json ./ +COPY --from=builder /app/pnpm-lock.yaml ./ + +# Production install +RUN pnpm install --frozen-lockfile --prod + +CMD ["node", "dist/index.js"] +``` + +### Optimized for Monorepos + +```dockerfile +FROM node:20-slim AS builder +RUN corepack enable +WORKDIR /app + +# Copy workspace config +COPY pnpm-lock.yaml pnpm-workspace.yaml ./ + +# Copy all package.json files maintaining structure +COPY packages/core/package.json ./packages/core/ +COPY packages/api/package.json ./packages/api/ + +# Install all dependencies +RUN pnpm install --frozen-lockfile + +# Copy source +COPY . . + +# Build specific package +RUN pnpm --filter @myorg/api build +``` + +## Key CI Flags + +### --frozen-lockfile + +**Always use in CI.** Fails if `pnpm-lock.yaml` needs updates: + +```bash +pnpm install --frozen-lockfile +``` + +### --prefer-offline + +Use cached packages when available: + +```bash +pnpm install --frozen-lockfile --prefer-offline +``` + +### --ignore-scripts + +Skip lifecycle scripts for faster installs (use cautiously): + +```bash +pnpm install --frozen-lockfile --ignore-scripts +``` + +## Corepack Integration + +Use Corepack to manage pnpm version: + +```json +// package.json +{ + "packageManager": "pnpm@9.0.0" +} +``` + +```yaml +# GitHub Actions +- run: corepack enable +- run: pnpm install --frozen-lockfile +``` + +## Monorepo CI Strategies + +### Build Changed Packages Only + +```yaml +- name: Build changed packages + run: | + pnpm --filter "...[origin/main]" build +``` + +### Parallel Jobs per Package + +```yaml +jobs: + detect-changes: + runs-on: ubuntu-latest + outputs: + packages: ${{ steps.changes.outputs.packages }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - id: changes + run: | + echo "packages=$(pnpm --filter '...[origin/main]' list --json | jq -c '[.[].name]')" >> $GITHUB_OUTPUT + + test: + needs: detect-changes + if: needs.detect-changes.outputs.packages != '[]' + runs-on: ubuntu-latest + strategy: + matrix: + package: ${{ fromJson(needs.detect-changes.outputs.packages) }} + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - run: pnpm install --frozen-lockfile + - run: pnpm --filter ${{ matrix.package }} test +``` + +## Best Practices Summary + +1. **Always use `--frozen-lockfile`** in CI +2. **Cache the pnpm store** for faster installs +3. **Use Corepack** for consistent pnpm versions +4. **Specify `packageManager`** in package.json +5. **Use `--filter`** in monorepos to build only what changed +6. **Multi-stage Docker builds** for smaller images + + diff --git a/.agents/skills/pnpm/references/best-practices-migration.md b/.agents/skills/pnpm/references/best-practices-migration.md new file mode 100644 index 0000000..16d7c55 --- /dev/null +++ b/.agents/skills/pnpm/references/best-practices-migration.md @@ -0,0 +1,291 @@ +--- +name: migration-to-pnpm +description: Migrating from npm or Yarn to pnpm with minimal friction +--- + +# Migration to pnpm + +Guide for migrating existing projects from npm or Yarn to pnpm. + +## Quick Migration + +### From npm + +```bash +# Remove npm lockfile and node_modules +rm -rf node_modules package-lock.json + +# Install with pnpm +pnpm install +``` + +### From Yarn + +```bash +# Remove yarn lockfile and node_modules +rm -rf node_modules yarn.lock + +# Install with pnpm +pnpm install +``` + +### Import Existing Lockfile + +pnpm can import existing lockfiles: + +```bash +# Import from npm or yarn lockfile +pnpm import + +# This creates pnpm-lock.yaml from: +# - package-lock.json (npm) +# - yarn.lock (yarn) +# - npm-shrinkwrap.json (npm) +``` + +## Handling Common Issues + +### Phantom Dependencies + +pnpm is strict about dependencies. If code imports a package not in `package.json`, it will fail. + +**Problem:** +```js +// Works with npm (hoisted), fails with pnpm +import lodash from 'lodash' // Not in dependencies, installed by another package +``` + +**Solution:** Add missing dependencies explicitly: +```bash +pnpm add lodash +``` + +### Missing Peer Dependencies + +pnpm reports peer dependency issues by default. + +**Option 1:** Let pnpm auto-install: +```ini +# .npmrc (default in pnpm v8+) +auto-install-peers=true +``` + +**Option 2:** Install manually: +```bash +pnpm add react react-dom +``` + +**Option 3:** Suppress warnings if acceptable: +```json +{ + "pnpm": { + "peerDependencyRules": { + "ignoreMissing": ["react"] + } + } +} +``` + +### Symlink Issues + +Some tools don't work with symlinks. Use hoisted mode: + +```ini +# .npmrc +node-linker=hoisted +``` + +Or hoist specific packages: + +```ini +public-hoist-pattern[]=*eslint* +public-hoist-pattern[]=*babel* +``` + +### Native Module Rebuilds + +If native modules fail, try: + +```bash +# Rebuild all native modules +pnpm rebuild + +# Or reinstall +rm -rf node_modules +pnpm install +``` + +## Monorepo Migration + +### From npm Workspaces + +1. Create `pnpm-workspace.yaml`: + ```yaml + packages: + - 'packages/*' + ``` + +2. Update internal dependencies to use workspace protocol: + ```json + { + "dependencies": { + "@myorg/utils": "workspace:^" + } + } + ``` + +3. Install: + ```bash + rm -rf node_modules packages/*/node_modules package-lock.json + pnpm install + ``` + +### From Yarn Workspaces + +1. Remove Yarn-specific files: + ```bash + rm yarn.lock .yarnrc.yml + rm -rf .yarn + ``` + +2. Create `pnpm-workspace.yaml` matching `workspaces` in package.json: + ```yaml + packages: + - 'packages/*' + ``` + +3. Update `package.json` - remove Yarn workspace config if not needed: + ```json + { + // Remove "workspaces" field (optional, pnpm uses pnpm-workspace.yaml) + } + ``` + +4. Convert workspace references: + ```json + // From Yarn + "@myorg/utils": "*" + + // To pnpm + "@myorg/utils": "workspace:*" + ``` + +### From Lerna + +pnpm can replace Lerna for most use cases: + +```bash +# Lerna: run script in all packages +lerna run build + +# pnpm equivalent +pnpm -r run build + +# Lerna: run in specific package +lerna run build --scope=@myorg/app + +# pnpm equivalent +pnpm --filter @myorg/app run build + +# Lerna: publish +lerna publish + +# pnpm: use changesets instead +pnpm add -Dw @changesets/cli +pnpm changeset +pnpm changeset version +pnpm publish -r +``` + +## Configuration Migration + +### .npmrc Settings + +Most npm/Yarn settings work in pnpm's `.npmrc`: + +```ini +# Registry settings (same as npm) +registry=https://registry.npmjs.org/ +@myorg:registry=https://npm.myorg.com/ + +# Auth tokens (same as npm) +//registry.npmjs.org/:_authToken=${NPM_TOKEN} + +# pnpm-specific additions +auto-install-peers=true +strict-peer-dependencies=false +``` + +### Scripts Migration + +Most scripts work unchanged. Update pnpm-specific patterns: + +```json +{ + "scripts": { + // npm: recursive scripts + "build:all": "npm run build --workspaces", + // pnpm: use -r flag + "build:all": "pnpm -r run build", + + // npm: run in specific workspace + "dev:app": "npm run dev -w packages/app", + // pnpm: use --filter + "dev:app": "pnpm --filter @myorg/app run dev" + } +} +``` + +## CI/CD Migration + +Update CI configuration: + +```yaml +# Before (npm) +- run: npm ci + +# After (pnpm) +- uses: pnpm/action-setup@v4 +- run: pnpm install --frozen-lockfile +``` + +Add to `package.json` for Corepack: +```json +{ + "packageManager": "pnpm@9.0.0" +} +``` + +## Gradual Migration + +For large projects, migrate gradually: + +1. **Start with CI**: Use pnpm in CI, keep npm/yarn locally +2. **Add pnpm-lock.yaml**: Run `pnpm import` to create lockfile +3. **Test thoroughly**: Ensure builds work with pnpm +4. **Update documentation**: Update README, CONTRIBUTING +5. **Remove old files**: Delete old lockfiles after team adoption + +## Rollback Plan + +If migration causes issues: + +```bash +# Remove pnpm files +rm -rf node_modules pnpm-lock.yaml pnpm-workspace.yaml + +# Restore npm +npm install + +# Or restore Yarn +yarn install +``` + +Keep old lockfile in git history for easy rollback. + + diff --git a/.agents/skills/pnpm/references/best-practices-performance.md b/.agents/skills/pnpm/references/best-practices-performance.md new file mode 100644 index 0000000..bf0c8cc --- /dev/null +++ b/.agents/skills/pnpm/references/best-practices-performance.md @@ -0,0 +1,284 @@ +--- +name: pnpm-performance-optimization +description: Tips and tricks for faster installs and better performance +--- + +# pnpm Performance Optimization + +pnpm is fast by default, but these optimizations can make it even faster. + +## Install Optimizations + +### Use Frozen Lockfile + +Skip resolution when lockfile exists: + +```bash +pnpm install --frozen-lockfile +``` + +This is faster because pnpm skips the resolution phase entirely. + +### Prefer Offline Mode + +Use cached packages when available: + +```bash +pnpm install --prefer-offline +``` + +Or configure globally: +```ini +# .npmrc +prefer-offline=true +``` + +### Skip Optional Dependencies + +If you don't need optional deps: + +```bash +pnpm install --no-optional +``` + +### Skip Scripts + +For CI or when scripts aren't needed: + +```bash +pnpm install --ignore-scripts +``` + +**Caution:** Some packages require postinstall scripts to work correctly. + +### Only Build Specific Dependencies + +Only run build scripts for specific packages: + +```ini +# .npmrc +onlyBuiltDependencies[]=esbuild +onlyBuiltDependencies[]=sharp +onlyBuiltDependencies[]=@swc/core +``` + +Or skip builds entirely for deps that don't need them: + +```json +{ + "pnpm": { + "neverBuiltDependencies": ["fsevents", "cpu-features"] + } +} +``` + +## Store Optimizations + +### Side Effects Cache + +Cache native module build results: + +```ini +# .npmrc +side-effects-cache=true +``` + +This caches the results of postinstall scripts, speeding up subsequent installs. + +### Shared Store + +Use a single store for all projects (default behavior): + +```ini +# .npmrc +store-dir=~/.pnpm-store +``` + +Benefits: +- Packages downloaded once for all projects +- Hard links save disk space +- Faster installs from cache + +### Store Maintenance + +Periodically clean unused packages: + +```bash +# Remove unreferenced packages +pnpm store prune + +# Check store integrity +pnpm store status +``` + +## Workspace Optimizations + +### Parallel Execution + +Run workspace scripts in parallel: + +```bash +pnpm -r --parallel run build +``` + +Control concurrency: +```ini +# .npmrc +workspace-concurrency=8 +``` + +### Stream Output + +See output in real-time: + +```bash +pnpm -r --stream run build +``` + +### Filter to Changed Packages + +Only build what changed: + +```bash +# Build packages changed since main branch +pnpm --filter "...[origin/main]" run build +``` + +### Topological Order + +Build dependencies before dependents: + +```bash +pnpm -r run build +# Automatically runs in topological order +``` + +For explicit sequential builds: +```bash +pnpm -r --workspace-concurrency=1 run build +``` + +## Network Optimizations + +### Configure Registry + +Use closest/fastest registry: + +```ini +# .npmrc +registry=https://registry.npmmirror.com/ +``` + +### HTTP Settings + +Tune network settings: + +```ini +# .npmrc +fetch-retries=3 +fetch-retry-mintimeout=10000 +fetch-retry-maxtimeout=60000 +network-concurrency=16 +``` + +### Proxy Configuration + +```ini +# .npmrc +proxy=http://proxy.company.com:8080 +https-proxy=http://proxy.company.com:8080 +``` + +## Lockfile Optimization + +### Single Lockfile (Monorepos) + +Use shared lockfile for all packages (default): + +```ini +# .npmrc +shared-workspace-lockfile=true +``` + +Benefits: +- Single source of truth +- Faster resolution +- Consistent versions across workspace + +### Lockfile-only Mode + +Only update lockfile without installing: + +```bash +pnpm install --lockfile-only +``` + +## Benchmarking + +### Compare Install Times + +```bash +# Clean install +rm -rf node_modules pnpm-lock.yaml +time pnpm install + +# Cached install (with lockfile) +rm -rf node_modules +time pnpm install --frozen-lockfile + +# With store cache +time pnpm install --frozen-lockfile --prefer-offline +``` + +### Profile Resolution + +Debug slow installs: + +```bash +# Verbose logging +pnpm install --reporter=append-only + +# Debug mode +DEBUG=pnpm:* pnpm install +``` + +## Configuration Summary + +Optimized `.npmrc` for performance: + +```ini +# Install behavior +prefer-offline=true +auto-install-peers=true + +# Build optimization +side-effects-cache=true +# Only build what's necessary +onlyBuiltDependencies[]=esbuild +onlyBuiltDependencies[]=@swc/core + +# Network +fetch-retries=3 +network-concurrency=16 + +# Workspace +workspace-concurrency=4 +``` + +## Quick Reference + +| Scenario | Command/Setting | +|----------|-----------------| +| CI installs | `pnpm install --frozen-lockfile` | +| Offline development | `--prefer-offline` | +| Skip native builds | `neverBuiltDependencies` | +| Parallel workspace | `pnpm -r --parallel run build` | +| Build changed only | `pnpm --filter "...[origin/main]" build` | +| Clean store | `pnpm store prune` | + + diff --git a/.agents/skills/pnpm/references/core-cli.md b/.agents/skills/pnpm/references/core-cli.md new file mode 100644 index 0000000..2286293 --- /dev/null +++ b/.agents/skills/pnpm/references/core-cli.md @@ -0,0 +1,229 @@ +--- +name: pnpm-cli-commands +description: Essential pnpm commands for package management, running scripts, and workspace operations +--- + +# pnpm CLI Commands + +pnpm provides a comprehensive CLI for package management with commands similar to npm/yarn but with unique features. + +## Installation Commands + +### Install all dependencies +```bash +pnpm install +# or +pnpm i +``` + +### Add a dependency +```bash +# Production dependency +pnpm add + +# Dev dependency +pnpm add -D +pnpm add --save-dev + +# Optional dependency +pnpm add -O + +# Global package +pnpm add -g + +# Specific version +pnpm add @ +pnpm add @next +pnpm add @^1.0.0 +``` + +### Remove a dependency +```bash +pnpm remove +pnpm rm +pnpm uninstall +pnpm un +``` + +### Update dependencies +```bash +# Update all +pnpm update +pnpm up + +# Update specific package +pnpm update + +# Update to latest (ignore semver) +pnpm update --latest +pnpm up -L + +# Interactive update +pnpm update --interactive +pnpm up -i +``` + +## Script Commands + +### Run scripts +```bash +pnpm run + +``` + +### React Setup + +Add before other scripts: + +```html + +``` + +### Asset Proxying + +Either: +1. Proxy static asset requests to Vite +2. Set `server.origin`: + +```ts +export default defineConfig({ + server: { + origin: 'http://localhost:5173' + } +}) +``` + +## Production + +Build generates `.vite/manifest.json`: + +```json +{ + "views/foo.js": { + "file": "assets/foo-BRBmoGS9.js", + "src": "views/foo.js", + "isEntry": true, + "imports": ["_shared-B7PI925R.js"], + "css": ["assets/foo-5UjPuW-k.css"] + }, + "_shared-B7PI925R.js": { + "file": "assets/shared-B7PI925R.js", + "css": ["assets/shared-ChJ_j-JJ.css"] + } +} +``` + +## Rendering Tags + +For entry `views/foo.js`, render in this order: + +```html + + + + + + + + + + + +``` + +## Manifest Structure + +```ts +interface ManifestChunk { + src?: string // Input file name + file: string // Output file name + css?: string[] // CSS files (JS chunks only) + assets?: string[] // Non-CSS assets (JS chunks only) + isEntry?: boolean // Is entry point + isDynamicEntry?: boolean // Is dynamic import + imports?: string[] // Static imports (manifest keys) + dynamicImports?: string[] // Dynamic imports (manifest keys) +} +``` + +## Processing Imports + +Recursively collect all imported chunks: + +```ts +function getImportedChunks(manifest, name) { + const seen = new Set() + const chunks = [] + + function collect(chunk) { + for (const file of chunk.imports ?? []) { + if (seen.has(file)) continue + seen.add(file) + + const importee = manifest[file] + collect(importee) + chunks.push(importee) + } + } + + collect(manifest[name]) + return chunks +} +``` + +## Existing Integrations + +Check [Awesome Vite](https://github.com/vitejs/awesome-vite#integrations-with-backends) for: +- Laravel (laravel-vite) +- Rails +- Django +- Flask +- And more + + diff --git a/.agents/skills/vite/references/advanced-performance.md b/.agents/skills/vite/references/advanced-performance.md new file mode 100644 index 0000000..8dea328 --- /dev/null +++ b/.agents/skills/vite/references/advanced-performance.md @@ -0,0 +1,168 @@ +--- +name: advanced-performance +description: Performance optimization tips for Vite dev server and builds +--- + +# Performance Optimization + +## Browser Setup + +- Use dev-only browser profile without extensions +- Disable "Disable Cache" in DevTools when using Vite +- Extensions can interfere with requests and slow startup + +## Audit Plugin Performance + +1. **Lazy load large dependencies** in plugins +2. **Avoid long operations** in `buildStart`, `config`, `configResolved` +3. **Optimize transform hooks** - check `id` extension before processing + +Debug transform times: + +```bash +vite --debug plugin-transform +``` + +Use [vite-plugin-inspect](https://github.com/antfu/vite-plugin-inspect) to inspect transforms. + +## Profiling + +```bash +vite --profile +# Visit site, press 'p + enter' to record .cpuprofile +# Open in https://www.speedscope.app +``` + +## Reduce Resolve Operations + +Be explicit with extensions to avoid filesystem checks: + +```ts +// Slow: checks .mjs, .js, .mts, .ts, .jsx, .tsx, .json +import Component from './Component' + +// Fast: direct hit +import Component from './Component.tsx' +``` + +Enable TypeScript path resolution for explicit imports: + +```json +{ + "compilerOptions": { + "moduleResolution": "bundler", + "allowImportingTsExtensions": true + } +} +``` + +## Avoid Barrel Files + +Barrel files (`index.js` re-exporting everything) cause all files to load: + +```ts +// Slow: loads all utils +import { slash } from './utils' + +// Fast: loads only slash.js +import { slash } from './utils/slash.js' +``` + +## Warm Up Frequently Used Files + +Pre-transform files that are always loaded: + +```ts +export default defineConfig({ + server: { + warmup: { + clientFiles: [ + './src/components/BigComponent.vue', + './src/utils/big-utils.js' + ], + ssrFiles: ['./src/server/modules/*.js'] + } + } +}) +``` + +Find files to warm up: + +```bash +vite --debug transform +``` + +## Use Native/Less Tooling + +**Do less work:** +- CSS instead of Sass/Less (PostCSS has nesting) +- Don't transform SVGs to components - import as strings/URLs +- Skip Babel in `@vitejs/plugin-react` if not needed + +**Use native tools:** +- Try Lightning CSS for faster CSS processing + +```ts +export default defineConfig({ + css: { + transformer: 'lightningcss' + } +}) +``` + +## Server Options + +### Open Browser Automatically + +Triggers warmup of entry point: + +```ts +export default defineConfig({ + server: { + open: true + } +}) +``` + +### Limit File Watching + +```ts +export default defineConfig({ + server: { + watch: { + ignored: ['**/large-folder/**'] + } + } +}) +``` + +## Build Performance + +### Disable Reporting + +Skip gzip size calculation for large projects: + +```ts +export default defineConfig({ + build: { + reportCompressedSize: false + } +}) +``` + +### Sourcemaps + +Disable if not needed: + +```ts +export default defineConfig({ + build: { + sourcemap: false + } +}) +``` + + diff --git a/.agents/skills/vite/references/advanced-plugin-api.md b/.agents/skills/vite/references/advanced-plugin-api.md new file mode 100644 index 0000000..c9a30a4 --- /dev/null +++ b/.agents/skills/vite/references/advanced-plugin-api.md @@ -0,0 +1,258 @@ +--- +name: advanced-plugin-api +description: Creating Vite plugins, hooks, virtual modules, and client-server communication +--- + +# Plugin API + +Vite plugins extend Rolldown's plugin interface with Vite-specific hooks. + +## Basic Plugin Structure + +```ts +export default function myPlugin(options = {}) { + return { + name: 'vite-plugin-my-plugin', + + // Hooks... + } +} +``` + +## Naming Conventions + +- Vite-only plugins: `vite-plugin-*` +- Rollup-compatible: `rollup-plugin-*` +- Framework-specific: `vite-plugin-vue-*`, `vite-plugin-react-*` + +## Universal Hooks (from Rolldown) + +Called on server start: +- `options` - Modify Rolldown options +- `buildStart` - Build starting + +Called per module request: +- `resolveId` - Resolve import paths +- `load` - Load module content +- `transform` - Transform module code + +Called on server close: +- `buildEnd` +- `closeBundle` + +## Vite-Specific Hooks + +### `config` + +Modify config before resolution: + +```ts +{ + name: 'modify-config', + config(config, { command, mode }) { + if (command === 'build') { + return { + resolve: { + alias: { foo: 'bar' } + } + } + } + } +} +``` + +### `configResolved` + +Access final resolved config: + +```ts +{ + name: 'read-config', + configResolved(config) { + this.config = config + } +} +``` + +### `configureServer` + +Add dev server middleware: + +```ts +{ + name: 'configure-server', + configureServer(server) { + // Before Vite's middlewares + server.middlewares.use((req, res, next) => { + // Handle request + next() + }) + + // Return function to run after Vite's middlewares + return () => { + server.middlewares.use((req, res, next) => { + // Post middleware + }) + } + } +} +``` + +### `transformIndexHtml` + +Transform HTML files: + +```ts +{ + name: 'html-transform', + transformIndexHtml(html) { + return html.replace(/(.*?)<\/title>/, '<title>New Title') + } +} +``` + +Inject tags: + +```ts +{ + name: 'html-inject', + transformIndexHtml() { + return { + tags: [ + { + tag: 'script', + attrs: { src: '/inject.js' }, + injectTo: 'body' // 'head' | 'body' | 'head-prepend' | 'body-prepend' + } + ] + } + } +} +``` + +### `handleHotUpdate` + +Custom HMR handling: + +```ts +{ + name: 'custom-hmr', + handleHotUpdate({ file, server, modules }) { + if (file.endsWith('.custom')) { + server.ws.send({ + type: 'custom', + event: 'custom-update', + data: { file } + }) + return [] // Prevent default HMR + } + } +} +``` + +## Virtual Modules + +Provide build-time information to source code: + +```ts +export default function myPlugin() { + const virtualModuleId = 'virtual:my-module' + const resolvedId = '\0' + virtualModuleId + + return { + name: 'virtual-module', + + resolveId(id) { + if (id === virtualModuleId) { + return resolvedId + } + }, + + load(id) { + if (id === resolvedId) { + return `export const msg = "from virtual module"` + } + } + } +} +``` + +Usage: + +```ts +import { msg } from 'virtual:my-module' +``` + +## Client-Server Communication + +### Server to Client + +```ts +{ + configureServer(server) { + server.ws.on('connection', () => { + server.ws.send('my:greetings', { msg: 'hello' }) + }) + } +} +``` + +Client receives: + +```ts +if (import.meta.hot) { + import.meta.hot.on('my:greetings', (data) => { + console.log(data.msg) + }) +} +``` + +### Client to Server + +```ts +// Client +if (import.meta.hot) { + import.meta.hot.send('my:from-client', { msg: 'Hey!' }) +} + +// Server (in plugin) +{ + configureServer(server) { + server.ws.on('my:from-client', (data, client) => { + console.log(data.msg) + client.send('my:reply', { msg: 'Got it!' }) + }) + } +} +``` + +## Transform with Filtering + +```ts +{ + name: 'transform-js', + transform: { + filter: { + id: /\.js$/ // Only .js files + }, + handler(code, id) { + return transformCode(code) + } + } +} +``` + +## Path Normalization + +Use POSIX separators for cross-platform compatibility: + +```ts +import { normalizePath } from 'vite' + +normalizePath('foo\\bar') // 'foo/bar' +``` + + diff --git a/.agents/skills/vite/references/build-library.md b/.agents/skills/vite/references/build-library.md new file mode 100644 index 0000000..e259c56 --- /dev/null +++ b/.agents/skills/vite/references/build-library.md @@ -0,0 +1,172 @@ +--- +name: build-library +description: Building libraries with Vite including proper package.json exports +--- + +# Library Mode + +Build browser-oriented libraries for distribution. + +## Basic Configuration + +```ts +import { resolve } from 'path' +import { defineConfig } from 'vite' + +export default defineConfig({ + build: { + lib: { + entry: resolve(__dirname, 'lib/main.js'), + name: 'MyLib', // Global variable name for UMD + fileName: 'my-lib' // Output filename (without extension) + }, + rolldownOptions: { + external: ['vue'], // Don't bundle these + output: { + globals: { + vue: 'Vue' // Global var for externals in UMD + } + } + } + } +}) +``` + +## Multiple Entry Points + +```ts +export default defineConfig({ + build: { + lib: { + entry: { + 'my-lib': resolve(__dirname, 'lib/main.js'), + 'secondary': resolve(__dirname, 'lib/secondary.js') + }, + name: 'MyLib' + } + } +}) +``` + +## Output Formats + +Single entry defaults: `['es', 'umd']` +Multiple entries defaults: `['es', 'cjs']` + +```ts +export default defineConfig({ + build: { + lib: { + entry: resolve(__dirname, 'lib/main.js'), + formats: ['es', 'cjs', 'umd', 'iife'] + } + } +}) +``` + +## Custom File Names + +```ts +export default defineConfig({ + build: { + lib: { + entry: resolve(__dirname, 'lib/main.js'), + fileName: (format, entryName) => `${entryName}.${format}.js`, + cssFileName: 'styles' // For bundled CSS + } + } +}) +``` + +## Package.json Configuration + +### Single Entry + +```json +{ + "name": "my-lib", + "type": "module", + "files": ["dist"], + "main": "./dist/my-lib.umd.cjs", + "module": "./dist/my-lib.js", + "exports": { + ".": { + "import": "./dist/my-lib.js", + "require": "./dist/my-lib.umd.cjs" + } + } +} +``` + +### Multiple Entries + +```json +{ + "name": "my-lib", + "type": "module", + "files": ["dist"], + "main": "./dist/my-lib.cjs", + "module": "./dist/my-lib.js", + "exports": { + ".": { + "import": "./dist/my-lib.js", + "require": "./dist/my-lib.cjs" + }, + "./secondary": { + "import": "./dist/secondary.js", + "require": "./dist/secondary.cjs" + } + } +} +``` + +### With CSS + +```json +{ + "exports": { + ".": { + "import": "./dist/my-lib.js", + "require": "./dist/my-lib.umd.cjs" + }, + "./style.css": "./dist/my-lib.css" + } +} +``` + +## Library Entry File + +```ts +// lib/main.js +import Foo from './Foo.vue' +import Bar from './Bar.vue' + +export { Foo, Bar } +``` + +## Environment Variables + +In library mode: +- `import.meta.env.*` is statically replaced +- `process.env.*` is NOT replaced (consumers can change it) + +To replace `process.env`: + +```ts +export default defineConfig({ + define: { + 'process.env.NODE_ENV': '"production"' + } +}) +``` + +## Notes + +- `assetsInlineLimit` is ignored - assets always inlined +- `cssCodeSplit` defaults to `false` +- For non-browser libraries, consider using [tsdown](https://tsdown.dev/) or Rolldown directly + + diff --git a/.agents/skills/vite/references/build-production.md b/.agents/skills/vite/references/build-production.md new file mode 100644 index 0000000..f4152f5 --- /dev/null +++ b/.agents/skills/vite/references/build-production.md @@ -0,0 +1,220 @@ +--- +name: build-production +description: Building for production including targets, multi-page apps, and optimizations +--- + +# Building for Production + +## Basic Build + +```bash +vite build +``` + +Uses `/index.html` as entry point, outputs to `dist/`. + +## Browser Compatibility + +Default target: Baseline Widely Available browsers (Chrome 111+, Edge 111+, Firefox 114+, Safari 16.4+). + +```ts +export default defineConfig({ + build: { + target: 'es2020', // Or specific browsers + // target: ['chrome64', 'firefox78', 'safari12'] + } +}) +``` + +For legacy browsers: + +```bash +npm add -D @vitejs/plugin-legacy +``` + +```ts +import legacy from '@vitejs/plugin-legacy' + +export default defineConfig({ + plugins: [ + legacy({ + targets: ['defaults', 'not IE 11'] + }) + ] +}) +``` + +## Output Configuration + +```ts +export default defineConfig({ + build: { + outDir: 'dist', // Output directory + assetsDir: 'assets', // Assets subdirectory + emptyOutDir: true, // Clear outDir before build + sourcemap: true, // Generate sourcemaps + // sourcemap: 'inline' | 'hidden' + } +}) +``` + +## Public Base Path + +For deploying under a subpath: + +```ts +export default defineConfig({ + base: '/my-app/' +}) +``` + +Relative base (works anywhere): + +```ts +export default defineConfig({ + base: './' +}) +``` + +Access in code: + +```ts +const base = import.meta.env.BASE_URL +``` + +## Multi-Page App + +```ts +import { resolve } from 'path' + +export default defineConfig({ + build: { + rolldownOptions: { + input: { + main: resolve(__dirname, 'index.html'), + nested: resolve(__dirname, 'nested/index.html') + } + } + } +}) +``` + +## Minification + +```ts +export default defineConfig({ + build: { + minify: 'oxc', // Default, fastest + // minify: 'terser', // More options, slower + // minify: false, // Disable + + terserOptions: { // If using terser + compress: { + drop_console: true + } + } + } +}) +``` + +## Chunk Strategy + +```ts +export default defineConfig({ + build: { + rolldownOptions: { + output: { + codeSplitting: { + // Manual chunks configuration + } + } + }, + chunkSizeWarningLimit: 500 // KB + } +}) +``` + +## CSS Options + +```ts +export default defineConfig({ + build: { + cssCodeSplit: true, // CSS per async chunk + cssMinify: 'lightningcss', // or 'esbuild' + cssTarget: 'chrome61' // Different from JS target + } +}) +``` + +## Asset Handling + +```ts +export default defineConfig({ + build: { + assetsInlineLimit: 4096, // Inline assets < 4KB as base64 + copyPublicDir: true // Copy public/ to outDir + } +}) +``` + +## Manifest + +Generate manifest for backend integration: + +```ts +export default defineConfig({ + build: { + manifest: true // .vite/manifest.json + } +}) +``` + +## Watch Mode + +Rebuild on file changes: + +```bash +vite build --watch +``` + +```ts +export default defineConfig({ + build: { + watch: {} // Enable programmatically + } +}) +``` + +## Load Error Handling + +Handle dynamic import failures (e.g., after deployment): + +```ts +window.addEventListener('vite:preloadError', (event) => { + window.location.reload() +}) +``` + +## Build Optimizations (Automatic) + +- **CSS code splitting** - CSS per async chunk +- **Preload directives** - `` +- **Async chunk optimization** - Parallel fetching of dependencies + +## License Generation + +Generate license file for dependencies: + +```ts +export default defineConfig({ + build: { + license: true // .vite/license.md + } +}) +``` + + diff --git a/.agents/skills/vite/references/build-ssr.md b/.agents/skills/vite/references/build-ssr.md new file mode 100644 index 0000000..b847946 --- /dev/null +++ b/.agents/skills/vite/references/build-ssr.md @@ -0,0 +1,194 @@ +--- +name: build-ssr +description: Server-side rendering setup and configuration with Vite +--- + +# Server-Side Rendering (SSR) + +Low-level API for framework authors. For applications, use higher-level tools from [Awesome Vite SSR](https://github.com/vitejs/awesome-vite#ssr). + +## Project Structure + +``` +├── index.html +├── server.js # Express/Node server +└── src/ + ├── main.js # Universal app code + ├── entry-client.js # Mounts app to DOM + └── entry-server.js # Renders app with SSR API +``` + +## index.html + +```html + + + +
+ + + +``` + +## Development Server + +```ts +// server.js +import express from 'express' +import { createServer as createViteServer } from 'vite' + +async function createServer() { + const app = express() + + const vite = await createViteServer({ + server: { middlewareMode: true }, + appType: 'custom' + }) + + app.use(vite.middlewares) + + app.use('*all', async (req, res, next) => { + const url = req.originalUrl + + try { + // 1. Read index.html + let template = fs.readFileSync( + path.resolve(__dirname, 'index.html'), + 'utf-8' + ) + + // 2. Apply Vite transforms + template = await vite.transformIndexHtml(url, template) + + // 3. Load server entry + const { render } = await vite.ssrLoadModule('/src/entry-server.js') + + // 4. Render app HTML + const appHtml = await render(url) + + // 5. Inject into template + const html = template.replace('', appHtml) + + res.status(200).set({ 'Content-Type': 'text/html' }).end(html) + } catch (e) { + vite.ssrFixStacktrace(e) + next(e) + } + }) + + app.listen(5173) +} + +createServer() +``` + +## Conditional Logic + +```ts +if (import.meta.env.SSR) { + // Server-only code (tree-shaken on client) +} +``` + +## Production Build + +```json +{ + "scripts": { + "build:client": "vite build --outDir dist/client", + "build:server": "vite build --outDir dist/server --ssr src/entry-server.js" + } +} +``` + +### Production Server + +```ts +// Differences from dev: +// 1. Use dist/client/index.html as template +// 2. Use import('./dist/server/entry-server.js') instead of ssrLoadModule +// 3. Serve static files from dist/client +``` + +## SSR Manifest + +For preload directives: + +```bash +vite build --outDir dist/client --ssrManifest +``` + +Generates `dist/client/.vite/ssr-manifest.json` with module-to-chunk mappings. + +## SSR Externals + +Dependencies are externalized by default. To transform with Vite: + +```ts +export default defineConfig({ + ssr: { + noExternal: ['package-that-needs-transform'], + external: ['package-to-externalize'] + } +}) +``` + +## SSR-specific Plugin Logic + +```ts +export function mySSRPlugin() { + return { + name: 'my-ssr', + transform(code, id, options) { + if (options?.ssr) { + // SSR-specific transform + } + } + } +} +``` + +## SSR Target + +```ts +export default defineConfig({ + ssr: { + target: 'node', // Default + // target: 'webworker' // For edge runtimes + } +}) +``` + +## SSR Bundle + +Bundle all dependencies (for workers): + +```ts +export default defineConfig({ + ssr: { + noExternal: true // Bundle everything + } +}) +``` + +## Resolve Conditions + +```ts +export default defineConfig({ + ssr: { + resolve: { + conditions: ['node'], + externalConditions: ['node'] + } + } +}) +``` + +## Pre-Rendering / SSG + +Pre-render routes with known data into static HTML at build time. + + diff --git a/.agents/skills/vite/references/core-cli.md b/.agents/skills/vite/references/core-cli.md new file mode 100644 index 0000000..fb2b762 --- /dev/null +++ b/.agents/skills/vite/references/core-cli.md @@ -0,0 +1,137 @@ +--- +name: core-cli +description: Vite CLI commands for development, building, and previewing +--- + +# Vite CLI + +## Dev Server + +Start the development server: + +```bash +vite [root] +vite dev [root] # alias +vite serve [root] # alias +``` + +### Dev Server Options + +| Option | Description | +|--------|-------------| +| `--host [host]` | Specify hostname (use `0.0.0.0` for LAN access) | +| `--port ` | Specify port (default: 5173) | +| `--open [path]` | Open browser on startup | +| `--cors` | Enable CORS | +| `--strictPort` | Exit if port is in use | +| `--force` | Force optimizer to re-bundle dependencies | +| `-c, --config ` | Use specified config file | +| `--base ` | Public base path | +| `-m, --mode ` | Set env mode | +| `-l, --logLevel ` | info \| warn \| error \| silent | +| `--clearScreen` | Allow/disable clear screen when logging | + +## Build + +Build for production: + +```bash +vite build [root] +``` + +### Build Options + +| Option | Description | +|--------|-------------| +| `--target ` | Transpile target (default: `"modules"`) | +| `--outDir ` | Output directory (default: `dist`) | +| `--assetsDir ` | Assets directory under outDir (default: `"assets"`) | +| `--assetsInlineLimit ` | Inline threshold in bytes (default: 4096) | +| `--ssr [entry]` | Build for SSR | +| `--sourcemap [output]` | Generate source maps (`boolean \| "inline" \| "hidden"`) | +| `--minify [minifier]` | Minifier (`boolean \| "oxc" \| "terser" \| "esbuild"`) | +| `--manifest [name]` | Generate build manifest JSON | +| `--ssrManifest [name]` | Generate SSR manifest JSON | +| `--emptyOutDir` | Force empty outDir | +| `-w, --watch` | Watch mode for rebuilding | + +## Preview + +Locally preview the production build: + +```bash +vite preview [root] +``` + +### Preview Options + +| Option | Description | +|--------|-------------| +| `--host [host]` | Specify hostname | +| `--port ` | Specify port | +| `--strictPort` | Exit if port is in use | +| `--open [path]` | Open browser on startup | +| `--outDir ` | Output directory (default: `dist`) | + +## Package Scripts + +Typical `package.json` scripts: + +```json +{ + "scripts": { + "dev": "vite", + "build": "vite build", + "preview": "vite preview" + } +} +``` + +## Running Vite + +```bash +# With npm +npx vite + +# With pnpm +pnpm vite + +# With yarn +yarn vite + +# With bun +bunx vite +``` + +## Scaffolding New Project + +```bash +# Interactive prompts +npm create vite@latest + +# With project name and template +npm create vite@latest my-app -- --template vue-ts + +# Available templates: vanilla, vanilla-ts, vue, vue-ts, react, react-ts, +# react-swc, react-swc-ts, preact, preact-ts, lit, lit-ts, svelte, svelte-ts, +# solid, solid-ts, qwik, qwik-ts +``` + +## Debugging + +```bash +# Debug plugin transforms +vite --debug plugin-transform + +# Debug with profiling +vite --profile +# Then press 'p + enter' to record .cpuprofile + +# Filter debug logs +vite --debug -f plugin-transform +``` + + diff --git a/.agents/skills/vite/references/core-config.md b/.agents/skills/vite/references/core-config.md new file mode 100644 index 0000000..bbe6fee --- /dev/null +++ b/.agents/skills/vite/references/core-config.md @@ -0,0 +1,176 @@ +--- +name: core-config +description: Vite configuration file setup, defineConfig helper, conditional and async configs +--- + +# Vite Configuration + +Vite automatically resolves a config file named `vite.config.*` in the project root. + +## Basic Configuration + +```ts +// vite.config.ts +import { defineConfig } from 'vite' + +export default defineConfig({ + // config options +}) +``` + +Use `defineConfig` for TypeScript intellisense. Alternatively, use JSDoc annotations: + +```js +/** @type {import('vite').UserConfig} */ +export default { + // config options +} +``` + +## Conditional Config + +Export a function to conditionally determine options based on command, mode, or build type: + +```ts +import { defineConfig } from 'vite' + +export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => { + if (command === 'serve') { + // dev specific config + return { + define: { + __DEV__: true + } + } + } else { + // build specific config + return { + define: { + __DEV__: false + } + } + } +}) +``` + +- `command` is `'serve'` during dev (`vite`, `vite dev`, `vite serve`) and `'build'` for production +- `mode` defaults to `'development'` for serve, `'production'` for build + +## Async Config + +```ts +import { defineConfig } from 'vite' + +export default defineConfig(async ({ command, mode }) => { + const data = await fetchRemoteConfig() + return { + // config using fetched data + } +}) +``` + +## Key Configuration Options + +### Root and Base + +```ts +export default defineConfig({ + root: './src', // Project root directory (where index.html is) + base: '/my-app/', // Public base path for assets + publicDir: 'public', // Static assets directory + cacheDir: 'node_modules/.vite' // Cache directory +}) +``` + +### Resolve Aliases + +```ts +import { resolve } from 'path' + +export default defineConfig({ + resolve: { + alias: { + '@': resolve(__dirname, 'src'), + '~': resolve(__dirname, 'src/components') + }, + // File extensions to try for imports without extension + extensions: ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json'] + } +}) +``` + +### Define Global Constants + +```ts +export default defineConfig({ + define: { + __APP_VERSION__: JSON.stringify('1.0.0'), + __API_URL__: JSON.stringify('https://api.example.com') + } +}) +``` + +Values must be JSON-serializable or a single identifier. Add TypeScript declarations: + +```ts +// vite-env.d.ts +declare const __APP_VERSION__: string +declare const __API_URL__: string +``` + +### JSON Handling + +```ts +export default defineConfig({ + json: { + namedExports: true, // Support named imports from JSON + stringify: 'auto' // Stringify large JSON for performance + } +}) +``` + +## Using Environment Variables in Config + +Variables from `.env` files are NOT automatically available in config. Use `loadEnv`: + +```ts +import { defineConfig, loadEnv } from 'vite' + +export default defineConfig(({ mode }) => { + // Load env vars from .env files + const env = loadEnv(mode, process.cwd(), '') + + return { + define: { + __APP_ENV__: JSON.stringify(env.APP_ENV) + }, + server: { + port: env.APP_PORT ? Number(env.APP_PORT) : 5173 + } + } +}) +``` + +## Specifying Config File + +```bash +vite --config my-config.ts +``` + +## Config Loading Methods + +```bash +# Default: bundle with Rolldown (may have issues in monorepos) +vite + +# Use module runner (no temp file, transforms on the fly) +vite --configLoader runner + +# Use native runtime (requires Node.js with TypeScript support) +vite --configLoader native +``` + + diff --git a/.agents/skills/vite/references/core-features.md b/.agents/skills/vite/references/core-features.md new file mode 100644 index 0000000..8a3d79b --- /dev/null +++ b/.agents/skills/vite/references/core-features.md @@ -0,0 +1,170 @@ +--- +name: core-features +description: Core Vite features including TypeScript, JSX, CSS, and HTML processing +--- + +# Core Features + +## TypeScript + +Vite supports `.ts` files out of the box with transpilation via Oxc Transformer (20-30x faster than tsc). + +### Important: Transpile Only + +Vite does NOT perform type checking. Run type checking separately: + +```bash +# Production build +tsc --noEmit && vite build + +# During development (separate process) +tsc --noEmit --watch + +# Or use vite-plugin-checker for browser error reporting +``` + +### TypeScript Configuration + +Required `tsconfig.json` settings: + +```json +{ + "compilerOptions": { + "isolatedModules": true, + "useDefineForClassFields": true, + "skipLibCheck": true + } +} +``` + +### Client Types + +Add Vite's client types for `import.meta.env` and asset imports: + +```json +{ + "compilerOptions": { + "types": ["vite/client"] + } +} +``` + +This provides types for: +- Asset imports (`.svg`, `.png`, etc.) +- `import.meta.env` constants +- `import.meta.hot` HMR API + +### Custom Type Overrides + +Override default asset import types: + +```ts +// vite-env-override.d.ts +declare module '*.svg' { + const content: React.FC> + export default content +} +``` + +### Path Aliases with tsconfig + +Enable tsconfig paths resolution: + +```ts +// vite.config.ts +export default defineConfig({ + resolve: { + tsconfigPaths: true + } +}) +``` + +## JSX + +`.jsx` and `.tsx` files are supported out of the box. Custom JSX configuration: + +```ts +export default defineConfig({ + oxc: { + jsx: { + runtime: 'classic', // or 'automatic' + pragma: 'h', + pragmaFrag: 'Fragment' + }, + // Auto-inject JSX helpers + jsxInject: `import React from 'react'` + } +}) +``` + +## HTML + +`index.html` is the entry point, not tucked away in `public/`. Vite processes it as part of the module graph. + +### Supported Elements + +Vite processes these HTML element attributes: + +- ` +``` + +### Multi-Page Apps + +Access any HTML file by its path: + +- `/index.html` → `http://localhost:5173/` +- `/about.html` → `http://localhost:5173/about.html` +- `/blog/index.html` → `http://localhost:5173/blog/index.html` + +## JSON + +Direct import with named exports support: + +```ts +// Import entire object +import json from './data.json' + +// Named imports (tree-shakeable) +import { field } from './data.json' +``` + +## Framework Support + +Official framework plugins: + +| Framework | Plugin | +|-----------|--------| +| Vue 3 | `@vitejs/plugin-vue` | +| Vue 3 JSX | `@vitejs/plugin-vue-jsx` | +| React | `@vitejs/plugin-react` | +| React (SWC) | `@vitejs/plugin-react-swc` | +| React Server Components | `@vitejs/plugin-rsc` | +| Legacy browsers | `@vitejs/plugin-legacy` | + +## Content Security Policy + +Configure nonce for CSP: + +```ts +export default defineConfig({ + html: { + cspNonce: 'PLACEHOLDER' // Replace per-request + } +}) +``` + + diff --git a/.agents/skills/vite/references/core-plugins.md b/.agents/skills/vite/references/core-plugins.md new file mode 100644 index 0000000..6fde148 --- /dev/null +++ b/.agents/skills/vite/references/core-plugins.md @@ -0,0 +1,154 @@ +--- +name: core-plugins +description: Adding, configuring, and ordering Vite plugins +--- + +# Using Plugins + +Vite extends Rolldown's plugin interface with extra Vite-specific options. + +## Adding Plugins + +Install and add to config: + +```bash +npm add -D @vitejs/plugin-vue +``` + +```ts +// vite.config.ts +import vue from '@vitejs/plugin-vue' +import { defineConfig } from 'vite' + +export default defineConfig({ + plugins: [vue()] +}) +``` + +## Plugin Arrays + +Plugins can return arrays (for complex features): + +```ts +// Framework plugin returning multiple plugins +export default function framework(config) { + return [ + frameworkRefresh(config), + frameworkDevtools(config) + ] +} +``` + +## Conditional Plugins + +Falsy values are ignored: + +```ts +export default defineConfig({ + plugins: [ + vue(), + process.env.ANALYZE && visualizer() // Only if ANALYZE is set + ] +}) +``` + +## Enforcing Plugin Order + +Control when plugin runs relative to Vite core: + +```ts +export default defineConfig({ + plugins: [ + { + ...somePlugin(), + enforce: 'pre' // Before Vite core plugins + }, + { + ...anotherPlugin(), + enforce: 'post' // After Vite build plugins + } + ] +}) +``` + +**Order:** +1. Alias +2. Plugins with `enforce: 'pre'` +3. Vite core plugins +4. Plugins without enforce +5. Vite build plugins +6. Plugins with `enforce: 'post'` +7. Vite post-build plugins (minify, manifest) + +## Conditional Application + +Apply only during serve or build: + +```ts +export default defineConfig({ + plugins: [ + { + ...typescript2(), + apply: 'build' // Only during build + }, + { + ...devOnlyPlugin(), + apply: 'serve' // Only during dev + } + ] +}) +``` + +Function form for more control: + +```ts +{ + ...myPlugin(), + apply(config, { command }) { + // Apply only on build but not for SSR + return command === 'build' && !config.build.ssr + } +} +``` + +## Finding Plugins + +1. Check [Vite Features Guide](https://vite.dev/guide/features.html) - many use cases are built-in +2. Official plugins in [Vite Plugins](https://vite.dev/plugins/) +3. Community plugins in [awesome-vite](https://github.com/vitejs/awesome-vite#plugins) +4. Search npm for `vite-plugin-*` or `rollup-plugin-*` + +## Official Plugins + +| Plugin | Purpose | +|--------|---------| +| `@vitejs/plugin-vue` | Vue 3 SFC support | +| `@vitejs/plugin-vue-jsx` | Vue 3 JSX support | +| `@vitejs/plugin-react` | React with Babel/Oxc | +| `@vitejs/plugin-react-swc` | React with SWC | +| `@vitejs/plugin-rsc` | React Server Components | +| `@vitejs/plugin-legacy` | Legacy browser support | + +## Rollup/Rolldown Plugin Compatibility + +Many Rollup plugins work directly with Vite if they: +- Don't use `moduleParsed` hook +- Don't rely on Rolldown-specific options +- Don't have strong coupling between bundle and output phases + +For build-only Rollup plugins: + +```ts +export default defineConfig({ + build: { + rolldownOptions: { + plugins: [rollupPluginForBuildOnly()] + } + } +}) +``` + + diff --git a/.agents/skills/vite/references/features-assets.md b/.agents/skills/vite/references/features-assets.md new file mode 100644 index 0000000..584407a --- /dev/null +++ b/.agents/skills/vite/references/features-assets.md @@ -0,0 +1,138 @@ +--- +name: features-assets +description: Static asset handling in Vite including imports, public directory, and URL handling +--- + +# Static Asset Handling + +## Importing Assets as URL + +```ts +import imgUrl from './img.png' +document.getElementById('hero-img').src = imgUrl +// Dev: /src/img.png +// Build: /assets/img.2d8efhg.png +``` + +Common image, media, and font types are detected automatically. + +## Import Queries + +### Explicit URL Import + +```ts +import workletURL from './worklet.js?url' +CSS.paintWorklet.addModule(workletURL) +``` + +### Import as String (Raw) + +```ts +import shaderString from './shader.glsl?raw' +``` + +### Control Inlining + +```ts +import imgUrl1 from './img.svg?no-inline' // Never inline +import imgUrl2 from './img.png?inline' // Always inline as base64 +``` + +## Asset Inlining + +Assets smaller than `assetsInlineLimit` (default 4KB) are inlined as base64: + +```ts +export default defineConfig({ + build: { + assetsInlineLimit: 4096, // 4KB + // Or use callback for fine control + assetsInlineLimit: (filePath) => { + return !filePath.endsWith('.svg') + } + } +}) +``` + +## The `public` Directory + +Files in `public/` are: +- Served at root path `/` during dev +- Copied as-is to `dist/` root during build +- Not processed or hashed + +``` +public/ + favicon.ico → /favicon.ico + robots.txt → /robots.txt +``` + +Reference with absolute paths in source: + +```html + +``` + +Configure directory: + +```ts +export default defineConfig({ + publicDir: 'static' // or false to disable +}) +``` + +## Extending Asset Types + +```ts +export default defineConfig({ + assetsInclude: ['**/*.gltf', '**/*.hdr'] +}) +``` + +## Dynamic URLs with import.meta.url + +```ts +// Works natively in modern browsers +const imgUrl = new URL('./img.png', import.meta.url).href + +// Dynamic pattern (limited) +function getImageUrl(name) { + return new URL(`./dir/${name}.png`, import.meta.url).href +} +``` + +**Limitations:** +- URL string must be static for build analysis +- Does not work with SSR (different semantics in Node.js vs browser) + +## TypeScript Support + +Add `vite/client` to types for asset import recognition: + +```json +{ + "compilerOptions": { + "types": ["vite/client"] + } +} +``` + +## URL Handling in CSS + +```css +.hero { + background: url('./img.png'); /* Processed and rebased */ +} +``` + +For dynamically constructed SVG URLs: + +```ts +import imgUrl from './img.svg' +element.style.background = `url("${imgUrl}")` // Note double quotes +``` + + diff --git a/.agents/skills/vite/references/features-css.md b/.agents/skills/vite/references/features-css.md new file mode 100644 index 0000000..705950c --- /dev/null +++ b/.agents/skills/vite/references/features-css.md @@ -0,0 +1,215 @@ +--- +name: features-css +description: CSS handling in Vite including modules, pre-processors, PostCSS, and Lightning CSS +--- + +# CSS Handling + +Vite provides rich CSS support with HMR, `@import` inlining, and automatic URL rebasing. + +## Basic CSS Import + +```ts +import './styles.css' // Injected into page with HMR support +``` + +## CSS Modules + +Files ending with `.module.css` are treated as CSS modules: + +```css +/* example.module.css */ +.red { + color: red; +} +``` + +```ts +import classes from './example.module.css' +element.className = classes.red +``` + +### Named Imports with camelCase + +```ts +// vite.config.ts +export default defineConfig({ + css: { + modules: { + localsConvention: 'camelCaseOnly' + } + } +}) +``` + +```ts +// .apply-color -> applyColor +import { applyColor } from './example.module.css' +``` + +## CSS Pre-processors + +Install the pre-processor, no Vite plugin needed: + +```bash +# Sass (sass-embedded recommended for performance) +npm add -D sass-embedded + +# Less +npm add -D less + +# Stylus +npm add -D stylus +``` + +Use by file extension: + +```ts +import './styles.scss' +import './styles.less' +import './styles.styl' +``` + +### Pre-processor Options + +```ts +export default defineConfig({ + css: { + preprocessorOptions: { + scss: { + additionalData: `$injectedColor: orange;`, + importers: [/* ... */] + }, + less: { + math: 'parens-division' + } + }, + preprocessorMaxWorkers: true // Use multiple threads + } +}) +``` + +### Combined with CSS Modules + +```ts +import styles from './component.module.scss' +``` + +## PostCSS + +Automatically applied if `postcss.config.js` exists: + +```js +// postcss.config.js +export default { + plugins: [ + require('postcss-nesting'), + require('autoprefixer') + ] +} +``` + +Or configure inline: + +```ts +export default defineConfig({ + css: { + postcss: { + plugins: [ + postcssNesting(), + autoprefixer() + ] + } + } +}) +``` + +## Lightning CSS + +Experimental faster CSS processing: + +```bash +npm add -D lightningcss +``` + +```ts +export default defineConfig({ + css: { + transformer: 'lightningcss', + lightningcss: { + targets: { + chrome: 111 + }, + cssModules: { + // Lightning CSS modules config + } + } + } +}) +``` + +Use Lightning CSS for minification only: + +```ts +export default defineConfig({ + build: { + cssMinify: 'lightningcss' + } +}) +``` + +## Disable CSS Injection + +Import CSS as string without injecting: + +```ts +import styles from './styles.css?inline' // Returns CSS string, not injected +``` + +## Source Maps + +Enable CSS source maps in development: + +```ts +export default defineConfig({ + css: { + devSourcemap: true + } +}) +``` + +## CSS Code Splitting + +By default, CSS is extracted per async chunk. Disable to get single CSS file: + +```ts +export default defineConfig({ + build: { + cssCodeSplit: false // Single CSS file for entire app + } +}) +``` + +## CSS Target + +Set different browser target for CSS: + +```ts +export default defineConfig({ + build: { + cssTarget: 'chrome61' // For Android WeChat WebView + } +}) +``` + +## @import and URL Handling + +- `@import` statements are inlined automatically +- Vite aliases work in `@import` +- `url()` references are rebased for correctness +- Works across Sass/Less files in different directories + + diff --git a/.agents/skills/vite/references/features-dep-bundling.md b/.agents/skills/vite/references/features-dep-bundling.md new file mode 100644 index 0000000..fe830ab --- /dev/null +++ b/.agents/skills/vite/references/features-dep-bundling.md @@ -0,0 +1,148 @@ +--- +name: features-dep-bundling +description: Dependency pre-bundling configuration and caching +--- + +# Dependency Pre-Bundling + +Vite pre-bundles dependencies on first run for faster dev server startup. + +## Why Pre-Bundling + +1. **CommonJS/UMD to ESM** - Convert non-ESM dependencies +2. **Performance** - Bundle many internal modules into single file (e.g., lodash-es has 600+ modules) + +```ts +// Works thanks to smart import analysis +import React, { useState } from 'react' +``` + +## Automatic Discovery + +Vite crawls source code to find bare imports and pre-bundles them with Rolldown. + +New dependencies discovered after server start trigger re-bundling. + +## Including Dependencies + +Force pre-bundling for dependencies not auto-discovered: + +```ts +export default defineConfig({ + optimizeDeps: { + include: [ + 'some-package', + 'another-package/nested' // Deep imports + ] + } +}) +``` + +**When to include:** +- Dynamically imported (via plugin transform) +- Large dependencies with many internal modules +- CommonJS dependencies + +## Excluding Dependencies + +Skip pre-bundling for small ESM-only dependencies: + +```ts +export default defineConfig({ + optimizeDeps: { + exclude: ['small-esm-dep'] + } +}) +``` + +## Monorepo Linked Dependencies + +Linked packages are treated as source code by default. If not ESM: + +```ts +export default defineConfig({ + optimizeDeps: { + include: ['linked-dep'] + } +}) +``` + +Restart with `--force` after making changes to linked deps. + +## Custom Rolldown Options + +```ts +export default defineConfig({ + optimizeDeps: { + rolldownOptions: { + plugins: [/* Rolldown plugins */], + // Other Rolldown options + } + } +}) +``` + +## Caching + +### File System Cache + +Located in `node_modules/.vite`. Re-runs when: + +- Package lockfile changes (`package-lock.json`, `pnpm-lock.yaml`, etc.) +- Patches folder modified +- `vite.config.js` changes +- `NODE_ENV` changes + +Force re-bundle: + +```bash +vite --force +# Or delete node_modules/.vite +``` + +### Browser Cache + +Pre-bundled deps are cached with `max-age=31536000,immutable`. + +To debug dependencies with local edits: + +1. Disable cache in browser DevTools Network tab +2. Restart Vite with `--force` +3. Reload page + +## Entries + +Specify custom entry points for discovery: + +```ts +export default defineConfig({ + optimizeDeps: { + entries: [ + 'src/main.ts', + 'src/other-entry.ts' + ] + } +}) +``` + +By default, all HTML files are used as entries. + +## esbuildOptions (Deprecated) + +Use `rolldownOptions` instead: + +```ts +export default defineConfig({ + optimizeDeps: { + // Deprecated + esbuildOptions: {}, + // Use instead + rolldownOptions: {} + } +}) +``` + + diff --git a/.agents/skills/vite/references/features-env.md b/.agents/skills/vite/references/features-env.md new file mode 100644 index 0000000..32320f7 --- /dev/null +++ b/.agents/skills/vite/references/features-env.md @@ -0,0 +1,161 @@ +--- +name: features-env +description: Environment variables, .env files, and modes in Vite +--- + +# Environment Variables and Modes + +## Built-in Constants + +Available via `import.meta.env`: + +| Constant | Description | +|----------|-------------| +| `import.meta.env.MODE` | App mode (`'development'` or `'production'`) | +| `import.meta.env.BASE_URL` | Base URL from `base` config | +| `import.meta.env.PROD` | `true` in production | +| `import.meta.env.DEV` | `true` in development | +| `import.meta.env.SSR` | `true` in server-side rendering | + +```ts +if (import.meta.env.DEV) { + console.log('Development mode') + // Tree-shaken in production +} +``` + +## Custom Environment Variables + +Only variables prefixed with `VITE_` are exposed to client code: + +```bash +# .env +VITE_API_URL=https://api.example.com +DB_PASSWORD=secret # NOT exposed to client +``` + +```ts +console.log(import.meta.env.VITE_API_URL) // "https://api.example.com" +console.log(import.meta.env.DB_PASSWORD) // undefined +``` + +### Custom Prefix + +```ts +export default defineConfig({ + envPrefix: ['VITE_', 'APP_'] // Expose VITE_* and APP_* +}) +``` + +## .env Files + +Load order (later has higher priority): + +``` +.env # Always loaded +.env.local # Always loaded, gitignored +.env.[mode] # Only in specified mode +.env.[mode].local # Only in specified mode, gitignored +``` + +### Variable Expansion + +```bash +# .env +KEY=123 +EXPANDED=test$KEY # test123 +ESCAPED=test\$foo # test$foo (escaped) +``` + +## Modes + +```bash +# Development mode (default for dev) +vite + +# Production mode (default for build) +vite build + +# Custom mode +vite build --mode staging +``` + +Create mode-specific env file: + +```bash +# .env.staging +VITE_APP_TITLE=My App (staging) +NODE_ENV=production # Still production build +``` + +### NODE_ENV vs Mode + +| Command | NODE_ENV | Mode | +|---------|----------|------| +| `vite build` | `production` | `production` | +| `vite build --mode development` | `production` | `development` | +| `NODE_ENV=development vite build` | `development` | `production` | + +## TypeScript IntelliSense + +Create type declarations for custom env variables: + +```ts +// vite-env.d.ts +interface ImportMetaEnv { + readonly VITE_APP_TITLE: string + readonly VITE_API_URL: string +} + +interface ImportMeta { + readonly env: ImportMetaEnv +} +``` + +For strict typing (disallow unknown keys): + +```ts +interface ViteTypeOptions { + strictImportMetaEnv: unknown +} +``` + +## HTML Replacement + +Use `%VARIABLE%` syntax in HTML: + +```html +%VITE_APP_TITLE% +

Mode: %MODE%

+``` + +Non-existent variables are left as-is (not replaced with `undefined`). + +## Loading Env in Config + +Env vars are NOT available in `vite.config.ts` automatically: + +```ts +import { defineConfig, loadEnv } from 'vite' + +export default defineConfig(({ mode }) => { + const env = loadEnv(mode, process.cwd(), '') // '' loads all vars + + return { + define: { + __APP_ENV__: JSON.stringify(env.APP_ENV) + } + } +}) +``` + +## Security Notes + +- Add `*.local` to `.gitignore` +- `VITE_*` variables end up in client bundle - no secrets +- Never set `envPrefix` to `''` (exposes everything) + + diff --git a/.agents/skills/vite/references/features-glob-import.md b/.agents/skills/vite/references/features-glob-import.md new file mode 100644 index 0000000..b24576a --- /dev/null +++ b/.agents/skills/vite/references/features-glob-import.md @@ -0,0 +1,161 @@ +--- +name: features-glob-import +description: Vite's import.meta.glob for batch importing modules and dynamic imports +--- + +# Glob Import + +## Basic Usage + +Import multiple modules using glob patterns: + +```ts +const modules = import.meta.glob('./dir/*.js') +// Transformed to: +// { +// './dir/foo.js': () => import('./dir/foo.js'), +// './dir/bar.js': () => import('./dir/bar.js'), +// } +``` + +Iterate and load: + +```ts +for (const path in modules) { + modules[path]().then((mod) => { + console.log(path, mod) + }) +} +``` + +## Eager Loading + +Load all modules immediately (no dynamic import): + +```ts +const modules = import.meta.glob('./dir/*.js', { eager: true }) +// Transformed to: +// import * as __glob_0 from './dir/foo.js' +// import * as __glob_1 from './dir/bar.js' +// const modules = { +// './dir/foo.js': __glob_0, +// './dir/bar.js': __glob_1, +// } +``` + +## Multiple Patterns + +```ts +const modules = import.meta.glob([ + './dir/*.js', + './another/*.js' +]) +``` + +## Negative Patterns + +Exclude files with `!` prefix: + +```ts +const modules = import.meta.glob([ + './dir/*.js', + '!**/bar.js' // Exclude bar.js +]) +``` + +## Named Imports + +Import specific exports for tree-shaking: + +```ts +const modules = import.meta.glob('./dir/*.js', { + import: 'setup' +}) +// './dir/foo.js': () => import('./dir/foo.js').then(m => m.setup) +``` + +Import default export: + +```ts +const modules = import.meta.glob('./dir/*.js', { + import: 'default', + eager: true +}) +``` + +## Custom Queries + +Import as raw strings or URLs: + +```ts +const moduleStrings = import.meta.glob('./dir/*.svg', { + query: '?raw', + import: 'default' +}) + +const moduleUrls = import.meta.glob('./dir/*.svg', { + query: '?url', + import: 'default' +}) +``` + +Custom queries for plugins: + +```ts +const modules = import.meta.glob('./dir/*.js', { + query: { foo: 'bar', bar: true } +}) +``` + +## Base Path + +Change the base path for imports: + +```ts +const modules = import.meta.glob('./**/*.js', { + base: './base' +}) +// Keys: './dir/foo.js' +// Imports: './base/dir/foo.js' +``` + +## Important Caveats + +1. **Vite-only feature** - Not a web standard +2. **Patterns must be literals** - Cannot use variables +3. **Relative or absolute** - Must start with `./`, `/`, or use an alias +4. **Glob matching** - Uses [tinyglobby](https://github.com/SuperchupuDev/tinyglobby) + +## Dynamic Import with Variables + +Limited dynamic import support: + +```ts +const module = await import(`./dir/${file}.js`) +``` + +**Rules:** +- Must start with `./` or `../` +- Must end with file extension +- Variable represents only one level (no `foo/bar`) +- Own directory needs filename pattern: `./prefix-${foo}.js` not `./${foo}.js` + +## Practical Example: Loading Route Components + +```ts +// Lazy load all page components +const pages = import.meta.glob('./pages/*.vue') + +const routes = Object.keys(pages).map((path) => { + const name = path.match(/\.\/pages\/(.*)\.vue$/)[1] + return { + path: `/${name.toLowerCase()}`, + component: pages[path] // Lazy loaded + } +}) +``` + + diff --git a/.agents/skills/vite/references/features-hmr.md b/.agents/skills/vite/references/features-hmr.md new file mode 100644 index 0000000..a87b9d6 --- /dev/null +++ b/.agents/skills/vite/references/features-hmr.md @@ -0,0 +1,200 @@ +--- +name: features-hmr +description: Vite's Hot Module Replacement (HMR) client API +--- + +# HMR API + +The HMR API is exposed via `import.meta.hot`. Primarily for framework and tooling authors. + +## Conditional Guard + +Always guard HMR code for tree-shaking in production: + +```ts +if (import.meta.hot) { + // HMR code +} +``` + +## TypeScript Support + +Add to `tsconfig.json`: + +```json +{ + "compilerOptions": { + "types": ["vite/client"] + } +} +``` + +## Self-Accepting Module + +Module handles its own updates: + +```ts +export const count = 1 + +if (import.meta.hot) { + import.meta.hot.accept((newModule) => { + if (newModule) { + console.log('updated: count is now', newModule.count) + } + }) +} +``` + +## Accept Dependency Updates + +React to changes in dependencies without self-reload: + +```ts +import { foo } from './foo.js' + +foo() + +if (import.meta.hot) { + // Single dependency + import.meta.hot.accept('./foo.js', (newFoo) => { + newFoo?.foo() + }) + + // Multiple dependencies + import.meta.hot.accept( + ['./foo.js', './bar.js'], + ([newFooModule, newBarModule]) => { + // Handle updates + } + ) +} +``` + +## Cleanup on Update + +Clean up side effects before module is replaced: + +```ts +function setupSideEffect() { + const interval = setInterval(() => {}, 1000) + return interval +} + +const interval = setupSideEffect() + +if (import.meta.hot) { + import.meta.hot.dispose((data) => { + clearInterval(interval) + }) +} +``` + +## Prune Callback + +Called when module is no longer imported: + +```ts +if (import.meta.hot) { + import.meta.hot.prune((data) => { + // Cleanup when module is removed from page + }) +} +``` + +## Persistent Data + +Pass data between module instances: + +```ts +if (import.meta.hot) { + // Mutate properties, don't reassign data itself + import.meta.hot.data.count = (import.meta.hot.data.count || 0) + 1 +} +``` + +## Invalidate + +Force propagation to importers: + +```ts +if (import.meta.hot) { + import.meta.hot.accept((module) => { + if (cannotHandleUpdate(module)) { + import.meta.hot.invalidate() // Propagate to importers + } + }) +} +``` + +## HMR Events + +Listen to built-in events: + +```ts +if (import.meta.hot) { + import.meta.hot.on('vite:beforeUpdate', (payload) => { + console.log('Update incoming') + }) + + import.meta.hot.on('vite:afterUpdate', (payload) => { + console.log('Update applied') + }) + + import.meta.hot.on('vite:beforeFullReload', () => { + console.log('Full reload') + }) + + import.meta.hot.on('vite:error', (error) => { + console.error('HMR error', error) + }) + + import.meta.hot.on('vite:ws:connect', () => { + console.log('WebSocket connected') + }) + + import.meta.hot.on('vite:ws:disconnect', () => { + console.log('WebSocket disconnected') + }) +} +``` + +## Custom Events + +Send events to server: + +```ts +// Client +if (import.meta.hot) { + import.meta.hot.send('my:event', { msg: 'Hello from client' }) +} +``` + +Receive from server: + +```ts +// Client +if (import.meta.hot) { + import.meta.hot.on('my:response', (data) => { + console.log(data.msg) + }) +} +``` + +## TypeScript for Custom Events + +```ts +// events.d.ts +import 'vite/types/customEvent.d.ts' + +declare module 'vite/types/customEvent.d.ts' { + interface CustomEventMap { + 'my:event': { msg: string } + 'my:response': { msg: string } + } +} +``` + + diff --git a/.agents/skills/vite/references/features-workers.md b/.agents/skills/vite/references/features-workers.md new file mode 100644 index 0000000..0bd5efb --- /dev/null +++ b/.agents/skills/vite/references/features-workers.md @@ -0,0 +1,115 @@ +--- +name: features-workers +description: Web Worker support in Vite +--- + +# Web Workers + +## Constructor Syntax (Recommended) + +Standard Web Worker creation: + +```ts +const worker = new Worker(new URL('./worker.js', import.meta.url)) +``` + +Module worker: + +```ts +const worker = new Worker(new URL('./worker.js', import.meta.url), { + type: 'module' +}) +``` + +Shared Worker: + +```ts +const sharedWorker = new SharedWorker( + new URL('./shared-worker.js', import.meta.url) +) +``` + +**Note:** The `new URL()` must be used directly inside `new Worker()` for detection. + +## Query Suffix Syntax + +Import with `?worker` suffix: + +```ts +import MyWorker from './worker?worker' + +const worker = new MyWorker() +``` + +Shared worker: + +```ts +import MySharedWorker from './worker?sharedworker' + +const worker = new MySharedWorker() +``` + +### Inline Worker + +Inline as base64 string (no separate chunk): + +```ts +import MyWorker from './worker?worker&inline' + +const worker = new MyWorker() +``` + +### Worker URL Only + +Get URL instead of constructor: + +```ts +import workerUrl from './worker?worker&url' +``` + +## Worker Script + +Workers can use ESM `import` statements: + +```ts +// worker.js +import { heavyComputation } from './utils' + +self.onmessage = (e) => { + const result = heavyComputation(e.data) + self.postMessage(result) +} +``` + +## Worker Options + +Configure worker bundling: + +```ts +// vite.config.ts +export default defineConfig({ + worker: { + format: 'es', // or 'iife' + plugins: () => [/* worker-specific plugins */], + rollupOptions: { + // Rollup options for worker bundle + } + } +}) +``` + +## WebAssembly in Workers + +```ts +// worker.js +import init from './module.wasm?init' + +init().then((instance) => { + instance.exports.compute() +}) +``` + + diff --git a/.agents/skills/vue-best-practices/LICENSE.md b/.agents/skills/vue-best-practices/LICENSE.md new file mode 100644 index 0000000..6ce1e3b --- /dev/null +++ b/.agents/skills/vue-best-practices/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 hyf0 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/.agents/skills/vue-best-practices/SKILL.md b/.agents/skills/vue-best-practices/SKILL.md new file mode 100644 index 0000000..94516e4 --- /dev/null +++ b/.agents/skills/vue-best-practices/SKILL.md @@ -0,0 +1,38 @@ +--- +name: vue-best-practices +description: Vue 3 and Vue.js best practices for TypeScript, vue-tsc, and Volar. This skill should be used when writing, reviewing, or refactoring Vue components to ensure correct typing patterns. Triggers on tasks involving Vue components, props extraction, wrapper components, template type checking, or Volar configuration. +license: MIT +metadata: + author: hyf0 + version: "8.0.0" +--- + +## Capability Rules + +| Rule | Keywords | Description | +|------|----------|-------------| +| [extract-component-props](rules/extract-component-props.md) | get props type, wrapper component, extend props, inherit props, ComponentProps | Extract types from .vue components | +| [vue-tsc-strict-templates](rules/vue-tsc-strict-templates.md) | undefined component, template error, strictTemplates | Catch undefined components in templates | +| [fallthrough-attributes](rules/fallthrough-attributes.md) | fallthrough, $attrs, wrapper component | Type-check fallthrough attributes | +| [strict-css-modules](rules/strict-css-modules.md) | css modules, $style, typo | Catch CSS module class typos | +| [data-attributes-config](rules/data-attributes-config.md) | data-*, strictTemplates, attribute | Allow data-* attributes | +| [volar-3-breaking-changes](rules/volar-3-breaking-changes.md) | volar, vue-language-server, editor | Fix Volar 3.0 upgrade issues | +| [module-resolution-bundler](rules/module-resolution-bundler.md) | cannot find module, @vue/tsconfig, moduleResolution | Fix module resolution errors | +| [define-model-update-event](rules/define-model-update-event.md) | defineModel, update event, undefined | Fix model update errors | +| [with-defaults-union-types](rules/with-defaults-union-types.md) | withDefaults, union type, default | Fix union type defaults | +| [deep-watch-numeric](rules/deep-watch-numeric.md) | watch, deep, array, Vue 3.5 | Efficient array watching | +| [vue-directive-comments](rules/vue-directive-comments.md) | @vue-ignore, @vue-skip, template | Control template type checking | +| [vue-router-typed-params](rules/vue-router-typed-params.md) | route params, typed router, unplugin | Fix route params typing | + +## Efficiency Rules + +| Rule | Keywords | Description | +|------|----------|-------------| +| [hmr-vue-ssr](rules/hmr-vue-ssr.md) | hmr, ssr, hot reload | Fix HMR in SSR apps | +| [pinia-store-mocking](rules/pinia-store-mocking.md) | pinia, mock, vitest, store | Mock Pinia stores | + +## Reference + +- [Vue Language Tools](https://github.com/vuejs/language-tools) +- [vue-component-type-helpers](https://github.com/vuejs/language-tools/tree/master/packages/component-type-helpers) +- [Vue 3 Documentation](https://vuejs.org/) diff --git a/.agents/skills/vue-best-practices/SYNC.md b/.agents/skills/vue-best-practices/SYNC.md new file mode 100644 index 0000000..13f0206 --- /dev/null +++ b/.agents/skills/vue-best-practices/SYNC.md @@ -0,0 +1,5 @@ +# Sync Info + +- **Source:** `vendor/vue-best-practices/skills/vue-best-practices` +- **Git SHA:** `ee0ceda40b7fabeb0713caf8b4db5ea438069fb5` +- **Synced:** 2026-01-28 diff --git a/.agents/skills/vue-best-practices/rules/codeactions-save-performance.md b/.agents/skills/vue-best-practices/rules/codeactions-save-performance.md new file mode 100644 index 0000000..03ea819 --- /dev/null +++ b/.agents/skills/vue-best-practices/rules/codeactions-save-performance.md @@ -0,0 +1,79 @@ +--- +title: Fix Slow Save Times with Code Actions Setting +impact: HIGH +impactDescription: fixes 30-60 second save delays in large Vue projects +type: capability +tags: performance, save-time, vscode, code-actions, volar +--- + +# Fix Slow Save Times with Code Actions Setting + +**Impact: HIGH** - fixes 30-60 second save delays in large Vue projects + +In large Vue projects, saving files can take 30-60+ seconds due to VSCode's code actions triggering expensive TypeScript state synchronization. + +## Problem + +Symptoms: +- Save operation takes 30+ seconds +- Editor becomes unresponsive during save +- CPU spikes when saving Vue files +- Happens more in larger projects + +## Root Cause + +VSCode emits document change events multiple times during save cycles. Each event triggers Volar to synchronize with TypeScript, causing expensive re-computation. + +## Solution + +Disable code actions or limit their timeout: + +**Option 1: Disable code actions (fastest)** +```json +// .vscode/settings.json +{ + "vue.codeActions.enabled": false +} +``` + +**Option 2: Limit code action time** +```json +// .vscode/settings.json +{ + "vue.codeActions.savingTimeLimit": 1000 +} +``` + +**Option 3: Disable specific code actions** +```json +// .vscode/settings.json +{ + "vue.codeActions.enabled": true, + "editor.codeActionsOnSave": { + "source.organizeImports": "never" + } +} +``` + +## VSCode Version Requirement + +VSCode 1.81.0+ includes fixes that reduce save time issues. Upgrade if using an older version. + +## Additional Optimizations + +```json +// .vscode/settings.json +{ + "vue.codeActions.enabled": false, + "editor.formatOnSave": true, + "editor.codeActionsOnSave": {}, + "[vue]": { + "editor.formatOnSave": true, + "editor.defaultFormatter": "Vue.volar" + } +} +``` + +## Reference + +- [Vue Language Tools Discussion #2740](https://github.com/vuejs/language-tools/discussions/2740) diff --git a/.agents/skills/vue-best-practices/rules/data-attributes-config.md b/.agents/skills/vue-best-practices/rules/data-attributes-config.md new file mode 100644 index 0000000..60c4630 --- /dev/null +++ b/.agents/skills/vue-best-practices/rules/data-attributes-config.md @@ -0,0 +1,74 @@ +--- +title: Allow Data Attributes with Strict Templates +impact: MEDIUM +impactDescription: fixes data-testid and data-* attribute errors in strict mode +type: capability +tags: dataAttributes, vueCompilerOptions, strictTemplates, data-testid, testing +--- + +# Allow Data Attributes with Strict Templates + +**Impact: MEDIUM** - fixes data-testid and data-* attribute errors in strict mode + +With `strictTemplates` enabled, `data-*` attributes on components cause type errors. Use the `dataAttributes` option to allow specific patterns. + +## Problem + +```vue + +``` + +## Solution + +Configure `dataAttributes` to allow specific patterns: + +```json +// tsconfig.json or tsconfig.app.json +{ + "vueCompilerOptions": { + "strictTemplates": true, + "dataAttributes": ["data-*"] + } +} +``` + +Now all `data-*` attributes are allowed on any component. + +## Specific Patterns + +You can be more selective: + +```json +{ + "vueCompilerOptions": { + "dataAttributes": [ + "data-testid", + "data-cy", + "data-test-*" + ] + } +} +``` + +This only allows the specified patterns, not all data attributes. + +## Common Testing Attributes + +For testing libraries, allow their specific attributes: + +| Library | Attribute | Pattern | +|---------|-----------|---------| +| Testing Library | `data-testid` | `"data-testid"` | +| Cypress | `data-cy` | `"data-cy"` | +| Playwright | `data-testid` | `"data-testid"` | +| Generic | All data attributes | `"data-*"` | + +## Reference + +- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options) diff --git a/.agents/skills/vue-best-practices/rules/deep-watch-numeric.md b/.agents/skills/vue-best-practices/rules/deep-watch-numeric.md new file mode 100644 index 0000000..ee2d502 --- /dev/null +++ b/.agents/skills/vue-best-practices/rules/deep-watch-numeric.md @@ -0,0 +1,97 @@ +--- +title: Vue 3.5+ Deep Watch Numeric Depth +impact: MEDIUM +impactDescription: enables efficient array mutation watching with numeric deep option +type: capability +tags: watch, deep, vue-3.5, array, mutation, performance +--- + +# Vue 3.5+ Deep Watch Numeric Depth + +**Impact: MEDIUM** - enables efficient array mutation watching with numeric deep option + +Vue 3.5 introduced `deep: number` for watch depth control. This allows watching array mutations without the performance cost of deep traversal. + +## Symptoms + +- Array mutations not triggering watch callback +- Deep watch causing performance issues on large nested objects +- Unaware of new Vue 3.5 feature + +> **Note:** TypeScript error "Type 'number' is not assignable to type 'boolean'" no longer occurs with Vue 3.5+ and current TypeScript versions. The types now correctly support numeric `deep` values. + +## The Feature + +```typescript +// Vue 3.5+ only +watch(items, (newVal) => { + // Triggered on array mutations (push, pop, splice, etc.) +}, { deep: 1 }) +``` + +| deep value | Behavior | +|------------|----------| +| `true` | Full recursive traversal (original behavior) | +| `false` | Only reference changes | +| `1` | One level deep - array mutations, not nested objects | +| `2` | Two levels deep | +| `n` | N levels deep | + +## Fix + +**Step 1: Ensure Vue 3.5+** +```bash +npm install vue@^3.5.0 +``` + +**Step 2: Use numeric depth** +```typescript +import { watch, ref } from 'vue' + +const items = ref([{ id: 1, data: { nested: 'value' } }]) + +// Watch array mutations only (push, pop, etc.) +watch(items, (newItems) => { + console.log('Array mutated') +}, { deep: 1 }) + +// Won't trigger on: items.value[0].data.nested = 'new' +// Will trigger on: items.value.push(newItem) +``` + +## Performance Comparison + +```typescript +const largeNestedData = ref({ /* deeply nested structure */ }) + +// SLOW - traverses entire structure +watch(largeNestedData, handler, { deep: true }) + +// FAST - only watches top-level changes +watch(largeNestedData, handler, { deep: 1 }) + +// FASTEST - only reference changes +watch(largeNestedData, handler, { deep: false }) +``` + +## Alternative: watchEffect for Selective Tracking + +```typescript +// Only tracks properties actually accessed +watchEffect(() => { + // Only re-runs when items.value.length or first item changes + console.log(items.value.length, items.value[0]?.id) +}) +``` + +## TypeScript Note + +If TypeScript complains about numeric deep, ensure: +1. Vue version is 3.5+ +2. TypeScript version is current (types are included with `vue` package) +3. tsconfig targets correct node_modules types + +## Reference + +- [Vue Watchers Docs](https://vuejs.org/guide/essentials/watchers.html) +- [Vue 3.5 Release Notes](https://blog.vuejs.org/posts/vue-3-5) diff --git a/.agents/skills/vue-best-practices/rules/define-model-update-event.md b/.agents/skills/vue-best-practices/rules/define-model-update-event.md new file mode 100644 index 0000000..2f4d5af --- /dev/null +++ b/.agents/skills/vue-best-practices/rules/define-model-update-event.md @@ -0,0 +1,79 @@ +--- +title: defineModel Fires Update Event with Undefined +impact: MEDIUM +impactDescription: fixes runtime errors from unexpected undefined in model updates +type: capability +tags: defineModel, v-model, update-event, undefined, vue-3.5 +--- + +# defineModel Fires Update Event with Undefined + +**Impact: MEDIUM** - fixes runtime errors from unexpected undefined in model updates + +> **Version Note:** This issue may be resolved in Vue 3.5+. Testing with Vue 3.5.26 could not reproduce the double emission with `undefined`. If you're on Vue 3.5+, verify the issue exists in your specific scenario before applying workarounds. + +Components using `defineModel` may fire the `@update:model-value` event with `undefined` in certain edge cases. TypeScript types don't always reflect this behavior, potentially causing runtime errors when the parent expects a non-nullable value. + +## Symptoms + +- Parent component receives `undefined` unexpectedly +- Runtime error: "Cannot read property of undefined" +- Type mismatch between expected `T` and received `T | undefined` +- Issue appears when clearing/resetting the model value + +## Root Cause + +`defineModel` returns `Ref` by default, even when `T` is non-nullable. The update event can fire with `undefined` when: +- Component unmounts +- Model is explicitly cleared +- Internal state resets + +## Fix + +**Option 1: Use required option (Vue 3.5+)** +```typescript +// Returns Ref instead of Ref +const model = defineModel({ required: true }) +``` + +**Option 2: Type parent handler to accept undefined** +```vue + + + +``` + +**Option 3: Use default value in defineModel** +```typescript +const model = defineModel({ default: '' }) +``` + +## Type Declaration Pattern + +```typescript +// In child component +interface Props { + modelValue: Item +} +const model = defineModel({ required: true }) + +// Emits will be typed as (value: Item) not (value: Item | undefined) +``` + +## Reference + +- [vuejs/core#12817](https://github.com/vuejs/core/issues/12817) +- [vuejs/core#10103](https://github.com/vuejs/core/issues/10103) +- [defineModel docs](https://vuejs.org/api/sfc-script-setup.html#definemodel) diff --git a/.agents/skills/vue-best-practices/rules/duplicate-plugin-detection.md b/.agents/skills/vue-best-practices/rules/duplicate-plugin-detection.md new file mode 100644 index 0000000..3fbbb99 --- /dev/null +++ b/.agents/skills/vue-best-practices/rules/duplicate-plugin-detection.md @@ -0,0 +1,102 @@ +--- +title: Duplicate Vue Plugin Detection +impact: MEDIUM +impactDescription: fixes cryptic build errors from Vue plugin registered twice +type: capability +tags: vite, plugin, vue, duplicate, config, inline +--- + +# Duplicate Vue Plugin Detection + +**Impact: MEDIUM** - fixes cryptic build errors from Vue plugin registered twice + +When using Vite's JavaScript API, if the Vue plugin is loaded in `vite.config.js` and specified again in `inlineConfig`, it gets registered twice, causing cryptic build errors. + +## Symptoms + +- Build produces unexpected output or fails silently +- "Cannot read property of undefined" during build +- Different build behavior between CLI and JavaScript API +- Vue components render incorrectly after build + +## Root Cause + +Vite doesn't deduplicate plugins by name when merging configs. The Vue plugin's internal state gets corrupted when registered twice. + +## Fix + +**Option 1: Use configFile: false with inline plugins** +```typescript +import { build } from 'vite' +import vue from '@vitejs/plugin-vue' + +await build({ + configFile: false, // Don't load vite.config.js + plugins: [vue()], + // ... rest of config +}) +``` + +**Option 2: Don't specify plugins in inlineConfig** +```typescript +// vite.config.js already has vue plugin +import { build } from 'vite' + +await build({ + // Don't add vue plugin here - it's in vite.config.js + root: './src', + build: { outDir: '../dist' } +}) +``` + +**Option 3: Filter out Vue plugin before merging** +```typescript +import { build, loadConfigFromFile } from 'vite' +import vue from '@vitejs/plugin-vue' + +const { config } = await loadConfigFromFile({ command: 'build', mode: 'production' }) + +// Remove existing Vue plugin +const filteredPlugins = config.plugins?.filter( + p => !p || (Array.isArray(p) ? false : p.name !== 'vite:vue') +) || [] + +await build({ + ...config, + plugins: [...filteredPlugins, vue({ /* your options */ })] +}) +``` + +## Detection Script + +Add this to debug plugin registration: +```typescript +// vite.config.ts +export default defineConfig({ + plugins: [ + vue(), + { + name: 'debug-plugins', + configResolved(config) { + const vuePlugins = config.plugins.filter(p => p.name?.includes('vue')) + if (vuePlugins.length > 1) { + console.warn('WARNING: Multiple Vue plugins detected:', vuePlugins.map(p => p.name)) + } + } + } + ] +}) +``` + +## Common Scenarios + +| Scenario | Solution | +|----------|----------| +| Using `vite.createServer()` | Use `configFile: false` | +| Build script with custom config | Don't duplicate plugins | +| Monorepo with shared config | Check for plugin inheritance | + +## Reference + +- [Vite Issue #5335](https://github.com/vitejs/vite/issues/5335) +- [Vite JavaScript API](https://vite.dev/guide/api-javascript.html) diff --git a/.agents/skills/vue-best-practices/rules/extract-component-props.md b/.agents/skills/vue-best-practices/rules/extract-component-props.md new file mode 100644 index 0000000..a94c70c --- /dev/null +++ b/.agents/skills/vue-best-practices/rules/extract-component-props.md @@ -0,0 +1,57 @@ +--- +title: Extract Component Props +impact: HIGH +impactDescription: extract props, emits, slots types from .vue components +type: capability +tags: typescript, props, emits, slots, vue-component-type-helpers, wrapper, ComponentProps +--- + +# Extract Component Props + +**Impact: HIGH** - extract props, emits, slots types from .vue components + +Use `vue-component-type-helpers` to extract types from `.vue` components: + +```bash +npm install -D vue-component-type-helpers +``` + +```typescript +import type { ComponentProps, ComponentEmit, ComponentSlots, ComponentExposed } from 'vue-component-type-helpers' +import MyButton from './MyButton.vue' + +type Props = ComponentProps +type Emits = ComponentEmit +type Slots = ComponentSlots +type Exposed = ComponentExposed +``` + +## Wrapper Component Pattern + +```typescript +import type { ComponentProps } from 'vue-component-type-helpers' +import BaseButton from './BaseButton.vue' + +type BaseProps = ComponentProps + +interface Props extends BaseProps { + size: 'sm' | 'md' | 'lg' +} + +defineProps() +``` + +## Do NOT Use + +```typescript +// ❌ Includes Vue internal properties (onUpdate:*, class, style, etc.) +type Props = InstanceType['$props'] +``` + +## Note + +Vue's built-in `ExtractPropTypes` is for runtime props objects (`props: { foo: String }`), not for `.vue` components. + +## Reference + +- [vue-component-type-helpers](https://github.com/vuejs/language-tools/tree/master/packages/component-type-helpers) diff --git a/.agents/skills/vue-best-practices/rules/fallthrough-attributes.md b/.agents/skills/vue-best-practices/rules/fallthrough-attributes.md new file mode 100644 index 0000000..5771ffc --- /dev/null +++ b/.agents/skills/vue-best-practices/rules/fallthrough-attributes.md @@ -0,0 +1,63 @@ +--- +title: Enable Fallthrough Attributes Type Checking +impact: MEDIUM +impactDescription: enables IDE autocomplete for fallthrough attributes in wrapper components +type: capability +tags: fallthroughAttributes, vueCompilerOptions, component-library, wrapper-components +--- + +# Enable Fallthrough Attributes Type Checking + +**Impact: MEDIUM** - enables type-aware attribute forwarding in component libraries + +When building component libraries with wrapper components, enable `fallthroughAttributes` to get IDE autocomplete for attributes that will be forwarded to child elements. + +## What It Does + +Wrapper components that pass attributes to child elements can benefit from type-aware completion: + +```vue + + +``` + +## Solution + +Enable `fallthroughAttributes` in your tsconfig: + +```json +// tsconfig.json or tsconfig.app.json +{ + "vueCompilerOptions": { + "fallthroughAttributes": true + } +} +``` + +## How It Works + +When `fallthroughAttributes: true`: +- Vue Language Server analyzes which element receives `$attrs` +- IDE autocomplete suggests valid attributes for the target element +- Helps developers discover available attributes + +> **Note:** This primarily enables IDE autocomplete for valid fallthrough attributes. It does NOT reject invalid attributes as type errors - arbitrary attributes are still allowed. + +## Related Options + +Combine with `strictTemplates` for comprehensive checking: + +```json +{ + "vueCompilerOptions": { + "strictTemplates": true, + "fallthroughAttributes": true + } +} +``` + +## Reference + +- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options) diff --git a/.agents/skills/vue-best-practices/rules/hmr-vue-ssr.md b/.agents/skills/vue-best-practices/rules/hmr-vue-ssr.md new file mode 100644 index 0000000..db1e427 --- /dev/null +++ b/.agents/skills/vue-best-practices/rules/hmr-vue-ssr.md @@ -0,0 +1,124 @@ +--- +title: HMR Debugging for Vue SSR +impact: MEDIUM +impactDescription: fixes Hot Module Replacement breaking in Vue SSR applications +type: efficiency +tags: vite, hmr, ssr, vue, hot-reload, server-side-rendering +--- + +# HMR Debugging for Vue SSR + +**Impact: MEDIUM** - fixes Hot Module Replacement breaking in Vue SSR applications + +Hot Module Replacement breaks when modifying Vue component ` +``` + +JSDoc comments inside ` + + +``` + +## How It Works + +- The regular ` + + + + +``` + +The typo `buttn` instead of `button` silently fails at runtime. + +## Solution + +Enable `strictCssModules` in your tsconfig: + +```json +// tsconfig.json or tsconfig.app.json +{ + "vueCompilerOptions": { + "strictCssModules": true + } +} +``` + +Now `$style.buttn` will show a type error because `buttn` doesn't exist in the CSS module. + +## What Gets Checked + +| Access | With strictCssModules | +|--------|----------------------| +| `$style.validClass` | OK | +| `$style.typo` | Error: Property 'typo' does not exist | +| `$style['dynamic']` | OK (dynamic access not checked) | + +## Limitations + +- Only checks static property access (`$style.className`) +- Dynamic access (`$style[variable]`) is not validated +- Only works with `,import './Card.css',Low, +15,Styling,Use scoped styles by default,Astro scopes styles to component automatically, (scoped),,,Medium, +17,Styling,Integrate Tailwind properly,Use @astrojs/tailwind integration,Official Tailwind integration,Manual Tailwind setup,npx astro add tailwind,Manual PostCSS config,Low,https://docs.astro.build/en/guides/integrations-guide/tailwind/ +18,Styling,Use CSS variables for theming,Define tokens in :root,CSS custom properties for themes,Hardcoded colors everywhere,:root { --primary: #3b82f6; },color: #3b82f6; everywhere,Medium, +19,Data,Fetch in frontmatter,Data fetching in component frontmatter,Top-level await in frontmatter,useEffect for initial data,const data = await fetch(url),client-side fetch on mount,High,https://docs.astro.build/en/guides/data-fetching/ +20,Data,Use Astro.glob for local files,Import multiple local files,Astro.glob for markdown/data files,Manual imports for each file,const posts = await Astro.glob('./posts/*.md'),"import post1; import post2;",Medium, +21,Data,Prefer content collections over glob,Type-safe collections for structured content,getCollection() for blog/docs,Astro.glob for structured content,await getCollection('blog'),await Astro.glob('./blog/*.md'),High, +22,Data,Use environment variables correctly,Import.meta.env for env vars,PUBLIC_ prefix for client vars,Expose secrets to client,import.meta.env.PUBLIC_API_URL,import.meta.env.SECRET in client,High,https://docs.astro.build/en/guides/environment-variables/ +23,Performance,Preload critical assets,Use link preload for important resources,Preload fonts above-fold images,No preload hints,"",No preload for critical assets,Medium, +24,Performance,Optimize images with astro:assets,Built-in image optimization, component for optimization, for local images,"import { Image } from 'astro:assets';","",High,https://docs.astro.build/en/guides/images/ +25,Performance,Use picture for responsive images,Multiple formats and sizes, for art direction,Single image size for all screens, with multiple sources, with single size,Medium, +26,Performance,Lazy load below-fold content,Defer loading non-critical content,loading=lazy for images client:visible for components,Load everything immediately,"",No lazy loading,Medium, +27,Performance,Minimize client directives,Each directive adds JS bundle,Audit client: usage regularly,Sprinkle client:load everywhere,Only interactive components hydrated,Every component with client:load,High, +28,ViewTransitions,Enable View Transitions,Smooth page transitions, in head,Full page reloads,"import { ViewTransitions } from 'astro:transitions';",No transition API,Medium,https://docs.astro.build/en/guides/view-transitions/ +29,ViewTransitions,Use transition:name,Named elements for morphing,transition:name for persistent elements,Unnamed transitions,"
",
without name,Low, +30,ViewTransitions,Handle transition:persist,Keep state across navigations,transition:persist for media players,Re-initialize on every navigation,"