ads-fe 0.0.1

package/skills/nuxt/references/advanced-hooks.md

@@ -0,0 +1,289 @@
+---
+name: lifecycle-hooks
+description: Nuxt and Nitro hooks for extending build-time and runtime behavior
+---
+
+# Lifecycle Hooks
+
+Nuxt provides hooks to tap into the build process, application lifecycle, and server runtime.
+
+## Build-time Hooks (Nuxt)
+
+Used in `nuxt.config.ts` or modules:
+
+### In nuxt.config.ts
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  hooks: {
+    'build:before': () => {
+      console.log('Build starting...')
+    },
+    'pages:extend': (pages) => {
+      // Add custom pages
+      pages.push({
+        name: 'custom',
+        path: '/custom',
+        file: '~/pages/custom.vue',
+      })
+    },
+    'components:dirs': (dirs) => {
+      // Add component directories
+      dirs.push({ path: '~/extra-components' })
+    },
+  },
+})
+```
+
+### In Modules
+
+```ts
+// modules/my-module.ts
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    nuxt.hook('ready', async (nuxt) => {
+      console.log('Nuxt is ready')
+    })
+
+    nuxt.hook('close', async (nuxt) => {
+      console.log('Nuxt is closing')
+    })
+
+    nuxt.hook('modules:done', () => {
+      console.log('All modules loaded')
+    })
+  },
+})
+```
+
+### Common Build Hooks
+
+| Hook | When |
+|------|------|
+| `ready` | Nuxt initialization complete |
+| `close` | Nuxt is closing |
+| `modules:done` | All modules installed |
+| `build:before` | Before build starts |
+| `build:done` | Build complete |
+| `pages:extend` | Pages routes resolved |
+| `components:dirs` | Component dirs being resolved |
+| `imports:extend` | Auto-imports being resolved |
+| `nitro:config` | Before Nitro config finalized |
+| `vite:extend` | Vite context created |
+| `vite:extendConfig` | Before Vite config finalized |
+
+## App Hooks (Runtime)
+
+Used in plugins and composables:
+
+### In Plugins
+
+```ts
+// plugins/lifecycle.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('app:created', (vueApp) => {
+    console.log('Vue app created')
+  })
+
+  nuxtApp.hook('app:mounted', (vueApp) => {
+    console.log('App mounted')
+  })
+
+  nuxtApp.hook('page:start', () => {
+    console.log('Page navigation starting')
+  })
+
+  nuxtApp.hook('page:finish', () => {
+    console.log('Page navigation finished')
+  })
+
+  nuxtApp.hook('page:loading:start', () => {
+    console.log('Page loading started')
+  })
+
+  nuxtApp.hook('page:loading:end', () => {
+    console.log('Page loading ended')
+  })
+})
+```
+
+### Common App Hooks
+
+| Hook | When |
+|------|------|
+| `app:created` | Vue app created |
+| `app:mounted` | Vue app mounted (client only) |
+| `app:error` | Fatal error occurred |
+| `page:start` | Page navigation starting |
+| `page:finish` | Page navigation finished |
+| `page:loading:start` | Loading indicator should show |
+| `page:loading:end` | Loading indicator should hide |
+| `link:prefetch` | Link is being prefetched |
+
+### Using Runtime Hooks
+
+```ts
+// composables/usePageTracking.ts
+export function usePageTracking() {
+  const nuxtApp = useNuxtApp()
+
+  nuxtApp.hook('page:finish', () => {
+    trackPageView(useRoute().path)
+  })
+}
+```
+
+## Server Hooks (Nitro)
+
+Used in server plugins:
+
+```ts
+// server/plugins/hooks.ts
+export default defineNitroPlugin((nitroApp) => {
+  // Modify HTML before sending
+  nitroApp.hooks.hook('render:html', (html, { event }) => {
+    html.head.push('<meta name="custom" content="value">')
+    html.bodyAppend.push('<script>console.log("injected")</script>')
+  })
+
+  // Modify response
+  nitroApp.hooks.hook('render:response', (response, { event }) => {
+    console.log('Sending response:', response.statusCode)
+  })
+
+  // Before request
+  nitroApp.hooks.hook('request', (event) => {
+    console.log('Request:', event.path)
+  })
+
+  // After response
+  nitroApp.hooks.hook('afterResponse', (event) => {
+    console.log('Response sent')
+  })
+})
+```
+
+### Common Nitro Hooks
+
+| Hook | When |
+|------|------|
+| `request` | Request received |
+| `beforeResponse` | Before sending response |
+| `afterResponse` | After response sent |
+| `render:html` | Before HTML is sent |
+| `render:response` | Before response is finalized |
+| `error` | Error occurred |
+
+## Custom Hooks
+
+### Define Custom Hook Types
+
+```ts
+// types/hooks.d.ts
+import type { HookResult } from '@nuxt/schema'
+
+declare module '#app' {
+  interface RuntimeNuxtHooks {
+    'my-app:event': (data: MyEventData) => HookResult
+  }
+}
+
+declare module '@nuxt/schema' {
+  interface NuxtHooks {
+    'my-module:init': () => HookResult
+  }
+}
+
+declare module 'nitropack/types' {
+  interface NitroRuntimeHooks {
+    'my-server:event': (data: any) => void
+  }
+}
+```
+
+### Call Custom Hooks
+
+```ts
+// In a plugin
+export default defineNuxtPlugin((nuxtApp) => {
+  // Call custom hook
+  nuxtApp.callHook('my-app:event', { type: 'custom' })
+})
+
+// In a module
+export default defineNuxtModule({
+  setup(options, nuxt) {
+    nuxt.callHook('my-module:init')
+  },
+})
+```
+
+## useRuntimeHook
+
+Call hooks at runtime from components:
+
+```vue
+<script setup lang="ts">
+// Register a callback for a runtime hook
+useRuntimeHook('app:error', (error) => {
+  console.error('App error:', error)
+})
+</script>
+```
+
+## Hook Examples
+
+### Page View Tracking
+
+```ts
+// plugins/analytics.client.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('page:finish', () => {
+    const route = useRoute()
+    analytics.track('pageview', {
+      path: route.path,
+      title: document.title,
+    })
+  })
+})
+```
+
+### Performance Monitoring
+
+```ts
+// plugins/performance.client.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  let navigationStart: number
+
+  nuxtApp.hook('page:start', () => {
+    navigationStart = performance.now()
+  })
+
+  nuxtApp.hook('page:finish', () => {
+    const duration = performance.now() - navigationStart
+    console.log(`Navigation took ${duration}ms`)
+  })
+})
+```
+
+### Inject HTML
+
+```ts
+// server/plugins/inject.ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('render:html', (html) => {
+    html.head.push(`
+      <script>
+        window.APP_CONFIG = ${JSON.stringify(config)}
+      </script>
+    `)
+  })
+})
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/guide/going-further/hooks
+- https://nuxt.com/docs/api/advanced/hooks
+-->

package/skills/nuxt/references/advanced-layers.md

@@ -0,0 +1,299 @@
+---
+name: nuxt-layers
+description: Extending Nuxt applications with layers for code sharing and reusability
+---
+
+# Nuxt Layers
+
+Layers allow sharing and reusing partial Nuxt applications across projects. They can include components, composables, pages, layouts, and configuration.
+
+## Using Layers
+
+### From npm Package
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [
+    '@my-org/base-layer',
+    '@nuxtjs/ui-layer',
+  ],
+})
+```
+
+### From Git Repository
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [
+    'github:username/repo',
+    'github:username/repo/base', // Subdirectory
+    'github:username/repo#v1.0', // Specific tag
+    'github:username/repo#dev', // Branch
+    'gitlab:username/repo',
+    'bitbucket:username/repo',
+  ],
+})
+```
+
+### From Local Directory
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [
+    '../base-layer',
+    './layers/shared',
+  ],
+})
+```
+
+### Auto-scanned Layers
+
+Place in `layers/` directory for automatic discovery:
+
+```
+my-app/
+├── layers/
+│   ├── base/
+│   │   └── nuxt.config.ts
+│   └── ui/
+│       └── nuxt.config.ts
+└── nuxt.config.ts
+```
+
+## Creating a Layer
+
+Minimal layer structure:
+
+```
+my-layer/
+├── nuxt.config.ts       # Required
+├── app/
+│   ├── components/      # Auto-merged
+│   ├── composables/     # Auto-merged
+│   ├── layouts/         # Auto-merged
+│   ├── middleware/      # Auto-merged
+│   ├── pages/           # Auto-merged
+│   ├── plugins/         # Auto-merged
+│   └── app.config.ts    # Merged
+├── server/              # Auto-merged
+└── package.json
+```
+
+### Layer nuxt.config.ts
+
+```ts
+// my-layer/nuxt.config.ts
+export default defineNuxtConfig({
+  // Layer configuration
+  app: {
+    head: {
+      title: 'My Layer App',
+    },
+  },
+  // Shared modules
+  modules: ['@nuxt/ui'],
+})
+```
+
+### Layer Components
+
+```vue
+<!-- my-layer/app/components/BaseButton.vue -->
+<template>
+  <button class="base-btn">
+    <slot />
+  </button>
+</template>
+```
+
+Use in consuming project:
+
+```vue
+<template>
+  <BaseButton>Click me</BaseButton>
+</template>
+```
+
+### Layer Composables
+
+```ts
+// my-layer/app/composables/useTheme.ts
+export function useTheme() {
+  const isDark = useState('theme-dark', () => false)
+  const toggle = () => isDark.value = !isDark.value
+  return { isDark, toggle }
+}
+```
+
+## Layer Priority
+
+Override order (highest to lowest):
+1. Your project files
+2. Auto-scanned layers (alphabetically, Z > A)
+3. `extends` array (first > last)
+
+Control order with prefixes:
+
+```
+layers/
+├── 1.base/      # Lower priority
+└── 2.theme/     # Higher priority
+```
+
+## Layer Aliases
+
+Access layer files:
+
+```ts
+// Auto-scanned layers get aliases
+import Component from '#layers/base/components/Component.vue'
+```
+
+Named aliases:
+
+```ts
+// my-layer/nuxt.config.ts
+export default defineNuxtConfig({
+  $meta: {
+    name: 'my-layer',
+  },
+})
+```
+
+```ts
+// In consuming project
+import { something } from '#layers/my-layer/utils'
+```
+
+## Publishing Layers
+
+### As npm Package
+
+```json
+{
+  "name": "my-nuxt-layer",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "dependencies": {
+    "@nuxt/ui": "^2.0.0"
+  },
+  "devDependencies": {
+    "nuxt": "^3.0.0"
+  }
+}
+```
+
+### Private Layers
+
+For private git repos:
+
+```bash
+export GIGET_AUTH=<github-token>
+```
+
+## Layer Best Practices
+
+### Use Resolved Paths
+
+```ts
+// my-layer/nuxt.config.ts
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const currentDir = dirname(fileURLToPath(import.meta.url))
+
+export default defineNuxtConfig({
+  css: [
+    join(currentDir, './assets/main.css'),
+  ],
+})
+```
+
+### Install Dependencies
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [
+    ['github:user/layer', { install: true }],
+  ],
+})
+```
+
+### Disable Layer Modules
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['./base-layer'],
+  // Disable modules from layer
+  image: false, // Disables @nuxt/image
+  pinia: false, // Disables @pinia/nuxt
+})
+```
+
+## Starter Template
+
+Create a new layer:
+
+```bash
+npx nuxi init --template layer my-layer
+```
+
+## Example: Theme Layer
+
+```
+theme-layer/
+├── nuxt.config.ts
+├── app/
+│   ├── app.config.ts
+│   ├── components/
+│   │   ├── ThemeButton.vue
+│   │   └── ThemeCard.vue
+│   ├── composables/
+│   │   └── useTheme.ts
+│   └── assets/
+│       └── theme.css
+└── package.json
+```
+
+```ts
+// theme-layer/nuxt.config.ts
+export default defineNuxtConfig({
+  css: ['~/assets/theme.css'],
+})
+```
+
+```ts
+// theme-layer/app/app.config.ts
+export default defineAppConfig({
+  theme: {
+    primaryColor: '#00dc82',
+    darkMode: false,
+  },
+})
+```
+
+```ts
+// consuming-app/nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['theme-layer'],
+})
+
+// consuming-app/app/app.config.ts
+export default defineAppConfig({
+  theme: {
+    primaryColor: '#ff0000', // Override
+  },
+})
+```
+
+<!-- 
+Source references:
+- https://nuxt.com/docs/getting-started/layers
+- https://nuxt.com/docs/guide/going-further/layers
+-->