npm package: @studio-fes/layer-craft
Description: Nuxt layer for Craft CMS integration with GraphQL and advanced caching capabilities. Extends `@studio-fes/layer-base`.
Author: studio fes
Latest version: 0.2.17

# @studio-fes/layer-craft

Nuxt layer for Craft CMS integration with GraphQL and advanced caching capabilities. Extends `@studio-fes/layer-base`.

## Features

### 🔌 GraphQL Integration
- **nuxt-graphql-middleware**: Full-featured GraphQL client
- **Automatic Query Imports**: Auto-import `.gql` files from `queries/` directories
- **Type-Safe**: Full TypeScript support with generated types
- **Schema Download**: Automatic GraphQL schema download in development

### ⚡ Caching
- **nuxt-multi-cache**: Multi-level caching system
- **Smart Cache Tags**: Automatic cache tag generation
- **Server-side Caching**: Optimize performance with intelligent caching

### 🎨 Craft-Specific Features
- **CraftImage Component**: Optimized image handling for Craft assets
- **SEO Composables**: Easy SEO management with `useCraftSEO`
- **Entry Composables**: Simplified entry fetching with `useCraftEntry`
- **Preview Mode**: Built-in Craft preview token support

## Installation

```bash
npm install @studio-fes/layer-craft
```

This will automatically include `@studio-fes/layer-base` and its features.

## Usage

Extend this layer in your `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  extends: ['@studio-fes/layer-craft'],
  
  graphqlMiddleware: {
    graphqlEndpoint: 'https://your-craft-site.com/api',
    downloadSchema: true,
  }
})
```

## Environment Variables

```env
NUXT_GRAPHQL_MIDDLEWARE_GRAPHQL_ENDPOINT=https://your-craft-site.com/api
NUXT_CACHE_ENABLED=true
```

## Components

### `<CraftImage>`
Optimized image component for Craft CMS assets with transforms.

```vue
<template>
  <CraftImage 
    :image="entry.image" 
    :transform="{ width: 800, height: 600 }" 
    alt="Image description"
  />
</template>
```

## Composables

### `useCraftEntry()`
Fetch Craft entries with caching and error handling.

```typescript
const { data: entry, error } = await useCraftEntry({
  slug: route.params.slug,
  section: 'pages'
})
```

### `useCraftSEO()`
Generate SEO metadata from Craft entry data.

```typescript
const { title, description, image } = useCraftSEO(entry)

useHead({
  title: title,
  meta: [
    { name: 'description', content: description }
  ]
})
```

## GraphQL Queries

Place your `.gql` files in the `queries/` directory:

```graphql
# queries/Entry.gql
query Entry($slug: [String]) {
  entry(slug: $slug) {
    id
    title
    ... on pages_page_Entry {
      content
      seoTitle
      seoDescription
    }
  }
}
```

Use them in your components:

```typescript
const { data } = await useAsyncQuery(Entry, {
  slug: route.params.slug
})
```

## Server Utils

### `createCacheTags()`
Generate cache tags for multi-cache integration:

```typescript
import { createCacheTags } from '#cache-utils'

const tags = createCacheTags('entry', entryId)
```

## Preview Mode

The layer includes automatic support for Craft's preview tokens. Preview requests are handled automatically through the preview plugin.

## Configuration

The layer extends the base configuration with:

```typescript
{
  modules: [
    'nuxt-graphql-middleware',
    'nuxt-multi-cache'
  ],
  graphqlMiddleware: {
    serverApiPrefix: '/gql',
    clientCache: {
      enabled: true
    },
    autoImportPatterns: ['./queries/**/*.gql']
  }
}
```

## Development

```bash
# Install dependencies
pnpm install

# Develop with playground
pnpm dev

# Download GraphQL schema
# Set graphqlEndpoint in nuxt.config.ts, then run:
pnpm dev

# Build
pnpm build

# Lint
pnpm lint
```

## Example Usage

See the [Craft starter](../../examples/starter-craft) for a complete implementation.

## Extending

You can further customize this layer:

```typescript
export default defineNuxtConfig({
  extends: ['@studio-fes/layer-craft'],
  
  graphqlMiddleware: {
    graphqlEndpoint: process.env.NUXT_GRAPHQL_MIDDLEWARE_GRAPHQL_ENDPOINT,
    downloadSchema: 'dev-only',
    clientCache: {
      enabled: true,
      maxAge: 1000 * 60 * 5 // 5 minutes
    }
  },
  
  runtimeConfig: {
    multiCacheEnabled: true
  }
})
```

## License

MIT