@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

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:

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

Environment Variables

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.

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

Composables

useCraftEntry()

Fetch Craft entries with caching and error handling.

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

useCraftSEO()

Generate SEO metadata from Craft entry data.

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

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

GraphQL Queries

Place your .gql files in the queries/ directory:

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

Use them in your components:

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

Server Utils

createCacheTags()

Generate cache tags for multi-cache integration:

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:

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

Development

# 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 example for a complete implementation.

Extending

You can further customize this layer:

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