aico-cli 2.1.1 → 2.1.23

package/templates/skills/nuxt/references/core-modules.md

@@ -0,0 +1,292 @@
+---
+name: nuxt-modules
+description: Creating and using Nuxt modules to extend framework functionality
+---
+
+# Nuxt Modules
+
+Modules extend Nuxt's core functionality. They run at build time and can add components, composables, plugins, and configuration.
+
+## Using Modules
+
+Install and add to `nuxt.config.ts`:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    // npm package
+    '@nuxt/ui',
+    // Local module
+    './modules/my-module',
+    // Inline module
+    (options, nuxt) => {
+      console.log('Inline module')
+    },
+    // With options
+    ['@nuxt/image', { provider: 'cloudinary' }],
+  ],
+})
+```
+
+## Creating Modules
+
+### Basic Module
+
+```ts
+// modules/my-module.ts
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule',
+  },
+  defaults: {
+    enabled: true,
+  },
+  setup(options, nuxt) {
+    if (!options.enabled) return
+
+    console.log('My module is running!')
+  },
+})
+```
+
+### Adding Components
+
+```ts
+// modules/ui/index.ts
+import { addComponent, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+
+    // Add single component
+    addComponent({
+      name: 'MyButton',
+      filePath: resolve('./runtime/components/MyButton.vue'),
+    })
+
+    // Add components directory
+    addComponentsDir({
+      path: resolve('./runtime/components'),
+      prefix: 'My',
+    })
+  },
+})
+```
+
+### Adding Composables
+
+```ts
+// modules/utils/index.ts
+import { addImports, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const { resolve } = createResolver(import.meta.url)
+
+    // Add auto-imported composable
+    addImports({
+      name: 'useMyUtil',
+      from: resolve('./runtime/composables/useMyUtil'),
+    })
+
+    // Add directory for auto-imports
+    addImportsDir(resolve('./runtime/composables'))
+  },
+})
+```
+
+### Adding Plugins
+
+```ts
+// modules/analytics/index.ts
+import { addPlugin, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const { resolve } = createResolver(import.meta.url)
+
+    addPlugin({
+      src: resolve('./runtime/plugin'),
+      mode: 'client', // 'client', 'server', or 'all'
+    })
+  },
+})
+```
+
+Plugin file:
+
+```ts
+// modules/analytics/runtime/plugin.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('page:finish', () => {
+    console.log('Page loaded')
+  })
+})
+```
+
+### Adding Server Routes
+
+```ts
+// modules/api/index.ts
+import { addServerHandler, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup() {
+    const { resolve } = createResolver(import.meta.url)
+
+    addServerHandler({
+      route: '/api/my-endpoint',
+      handler: resolve('./runtime/server/api/my-endpoint'),
+    })
+  },
+})
+```
+
+### Extending Config
+
+```ts
+// modules/config/index.ts
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    // Add CSS
+    nuxt.options.css.push('my-module/styles.css')
+
+    // Add runtime config
+    nuxt.options.runtimeConfig.public.myModule = {
+      apiUrl: options.apiUrl,
+    }
+
+    // Extend Vite config
+    nuxt.options.vite.optimizeDeps ||= {}
+    nuxt.options.vite.optimizeDeps.include ||= []
+    nuxt.options.vite.optimizeDeps.include.push('some-package')
+  },
+})
+```
+
+## Module Hooks
+
+```ts
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    // Build-time hooks
+    nuxt.hook('modules:done', () => {
+      console.log('All modules loaded')
+    })
+
+    nuxt.hook('components:dirs', (dirs) => {
+      dirs.push({ path: '~/extra-components' })
+    })
+
+    nuxt.hook('pages:extend', (pages) => {
+      pages.push({
+        name: 'custom-page',
+        path: '/custom',
+        file: resolve('./runtime/pages/custom.vue'),
+      })
+    })
+
+    nuxt.hook('imports:extend', (imports) => {
+      imports.push({ name: 'myHelper', from: 'my-package' })
+    })
+  },
+})
+```
+
+## Module Options
+
+Type-safe options with defaults:
+
+```ts
+export interface ModuleOptions {
+  apiKey: string
+  enabled?: boolean
+  prefix?: string
+}
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule',
+  },
+  defaults: {
+    enabled: true,
+    prefix: 'My',
+  },
+  setup(options, nuxt) {
+    // options is typed as ModuleOptions
+    if (!options.apiKey) {
+      console.warn('API key not provided')
+    }
+  },
+})
+```
+
+Usage:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['my-module'],
+  myModule: {
+    apiKey: 'xxx',
+    prefix: 'Custom',
+  },
+})
+```
+
+## Local Modules
+
+Place in `modules/` directory:
+
+```
+modules/
+├── my-module/
+│   ├── index.ts
+│   └── runtime/
+│       ├── components/
+│       ├── composables/
+│       └── plugin.ts
+```
+
+Auto-registered or manually added:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '~/modules/my-module', // Explicit
+  ],
+})
+```
+
+## Module Dependencies
+
+```ts
+export default defineNuxtModule({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies: {
+    '@nuxt/image': {
+      version: '>=1.0.0',
+      defaults: {
+        provider: 'ipx',
+      },
+    },
+  },
+  setup() {
+    // @nuxt/image is guaranteed to be installed
+  },
+})
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/guide/modules
+- https://nuxt.com/docs/guide/modules/module-anatomy
+- https://nuxt.com/docs/api/kit
+-->

package/templates/skills/nuxt/references/core-routing.md

@@ -0,0 +1,226 @@
+---
+name: routing
+description: File-based routing, dynamic routes, navigation, and middleware in Nuxt
+---
+
+# Routing
+
+Nuxt uses file-system routing based on vue-router. Files in `app/pages/` automatically create routes.
+
+## Basic Routing
+
+```
+pages/
+├── index.vue      → /
+├── about.vue      → /about
+└── posts/
+    ├── index.vue  → /posts
+    └── [id].vue   → /posts/:id
+```
+
+## Dynamic Routes
+
+Use brackets for dynamic segments:
+
+```
+pages/
+├── users/
+│   └── [id].vue       → /users/:id
+├── posts/
+│   └── [...slug].vue  → /posts/* (catch-all)
+└── [[optional]].vue   → /:optional? (optional param)
+```
+
+Access route parameters:
+
+```vue
+<script setup lang="ts">
+const route = useRoute()
+// /posts/123 → route.params.id = '123'
+console.log(route.params.id)
+</script>
+```
+
+## Navigation
+
+### NuxtLink Component
+
+```vue
+<template>
+  <nav>
+    <NuxtLink to="/">Home</NuxtLink>
+    <NuxtLink to="/about">About</NuxtLink>
+    <NuxtLink :to="{ name: 'posts-id', params: { id: 1 } }">Post 1</NuxtLink>
+  </nav>
+</template>
+```
+
+NuxtLink automatically prefetches linked pages when they enter the viewport.
+
+### Programmatic Navigation
+
+```vue
+<script setup lang="ts">
+const router = useRouter()
+
+function goToPost(id: number) {
+  navigateTo(`/posts/${id}`)
+  // or
+  router.push({ name: 'posts-id', params: { id } })
+}
+</script>
+```
+
+## Route Middleware
+
+### Named Middleware
+
+```ts
+// middleware/auth.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  const isAuthenticated = false // Your auth logic
+
+  if (!isAuthenticated) {
+    return navigateTo('/login')
+  }
+})
+```
+
+Apply to pages:
+
+```vue
+<script setup lang="ts">
+definePageMeta({
+  middleware: 'auth',
+  // or multiple: middleware: ['auth', 'admin']
+})
+</script>
+```
+
+### Global Middleware
+
+Name files with `.global` suffix:
+
+```ts
+// middleware/logging.global.ts
+export default defineNuxtRouteMiddleware((to, from) => {
+  console.log('Navigating to:', to.path)
+})
+```
+
+### Inline Middleware
+
+```vue
+<script setup lang="ts">
+definePageMeta({
+  middleware: [
+    function (to, from) {
+      // Inline middleware logic
+    },
+  ],
+})
+</script>
+```
+
+## Page Meta
+
+Configure page-level options:
+
+```vue
+<script setup lang="ts">
+definePageMeta({
+  title: 'My Page',
+  layout: 'custom',
+  middleware: 'auth',
+  validate: (route) => {
+    // Return false for 404, or object with status/statusText
+    return /^\d+$/.test(route.params.id as string)
+  },
+})
+</script>
+```
+
+## Route Validation
+
+```vue
+<script setup lang="ts">
+definePageMeta({
+  validate: (route) => {
+    // Must return boolean or object with status
+    return typeof route.params.id === 'string' && /^\d+$/.test(route.params.id)
+  },
+})
+</script>
+```
+
+## Layouts
+
+Define layouts in `app/layouts/`:
+
+```vue
+<!-- layouts/default.vue -->
+<template>
+  <div>
+    <header>Header</header>
+    <slot />
+    <footer>Footer</footer>
+  </div>
+</template>
+```
+
+```vue
+<!-- layouts/admin.vue -->
+<template>
+  <div class="admin">
+    <AdminSidebar />
+    <main>
+      <slot />
+    </main>
+  </div>
+</template>
+```
+
+Use in pages:
+
+```vue
+<script setup lang="ts">
+definePageMeta({
+  layout: 'admin',
+})
+</script>
+```
+
+Dynamic layout:
+
+```vue
+<script setup lang="ts">
+const layout = ref('default')
+
+function enableAdmin() {
+  setPageLayout('admin')
+}
+</script>
+```
+
+## Navigation Hooks
+
+```vue
+<script setup lang="ts">
+onBeforeRouteLeave((to, from) => {
+  // Confirm before leaving
+  const answer = window.confirm('Leave?')
+  if (!answer) return false
+})
+
+onBeforeRouteUpdate((to, from) => {
+  // Called when route changes but component is reused
+})
+</script>
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/getting-started/routing
+- https://nuxt.com/docs/directory-structure/app/pages
+- https://nuxt.com/docs/directory-structure/app/middleware
+-->