Skip to content

Latest commit

 

History

History
92 lines (68 loc) · 4.64 KB

README.md

File metadata and controls

92 lines (68 loc) · 4.64 KB
Raw

@cloak-app/craft

Craft CMS API client and static site generation conventions.

Features

  • Globally injected $craft helper object for executing queries that are scoped to a Craft site.
  • Helper factory methods for constructing $craft outside of Nuxt runtime code.
  • Automatic static generate of dynamic routes using pageTypenames.
  • Automatic creation of Netlify _redirects file from Craft "Redirects" section.

Install

  1. Install with yarn add @cloak-app/craft
  2. Add to nuxt.config with modules: ['@cloak-app/craft']

Module Options

Set these properties within cloak: { craft: { ... } } in the nuxt.config.js:

  • endpoint - The Craft CMS API endpoint, for example: https://cms.domain.com/api. Defaults to process.env.CMS_ENDPOINT.
  • site - The Craft CMS Site handle to restrict queries to. If populated, it gets automatically passed into all GraphQL queries as a variable called site. Defaults to process.env.CMS_SITE.
  • pageTypenames - An array of GraphQL typenames of Craft entry types whose URIs should be generated as pages. For example: ['towers_tower_Entry']. Defaults to [].
  • generateRedirects - If true, adds redirect to the static/_redirects file using a redirects Craft section.
  • payloadTransformers - An array of addPayloadTransformer callbacks (see below)
  • mocks - An array of objects for use with mockAxiosGql.
  • injectClient - Boolean for whether to inject the $craft client globally. Defaults to true. You would set this to false when this module is a depedency of another module (like @cloak-app/algolia) that is creating $craft a different way.

Usage

Inside of Nuxt app

The craft-client Nuxt plugin injects $craft globally. This is an Axios instance with it's baseUrl set to cloak.craft.endpoint. In addition, you can call:

  • $craft.execute({ query, variables }) - Executes a GraphQL request that automatically adds a site GraphQL variable with the value from the cloak.craft.site value.
  • $craft.getEntries({ query, variables }) - Sugar for $craft.execute() that returns the entries property of the GraphQL response.
  • $craft.getEntry({ query, variables }) - Sugar for $craft.execute() that returns the entry property of the GraphQL response.
  • $craft.setSite(site) - Updates the site variable for all future requests at runtime.
  • $craft.addPayloadTransformer(callback) - Adds a transforming callback. A callback has a type of ({ query: string, variables?: object}) => { query: string, variables?: object}. Example: $craft.addPayloadTransformer((payload) => payload.variables.category = 'pants').
# A page component
export default
  asyncData: ({ $craft, params }) ->
    page = await $craft.getEntry
      variables: uri: params.tower
      query: '''
        query getTower($uri:[String], $site:[String]) {
          entry(uri:$uri, site:$site) {
            title
          }
        }
      '''
    return { page }

Inside of Nuxt module

You can use the makeModuleCraftClient() factory method within a Nuxt module to build a $craft instance. In a module, we can't use the instance that is injected by the craft-client plugin because that is constructed later in the lifecycle.

// A Nuxt module
import { makeModuleCraftClient } from '@cloak-app/craft/factories'
export default function() {
  const $craft = makeModuleCraftClient(this)
}

Outside of Nuxt

You can make an instance of the Craft Axios client when outside of Nuxt (like in a Netlify function) as follows:

// The entry point of a non-Nuxt app
import Vue from 'vue'
import { makeCraftClient } from '@cloak-app/craft/factories'
Vue.prototype.$craft = makeCraftClient({
  endpoint: process.env.CMS_ENDPOINT,
  site: process.env.CMS_SITE,
})

Regarding fallback

This package enables the generate.fallback option.. This is done so that admins can use Craft previews on new pages that haven't been statically generated yet. When the fallback is rendered, data that would normally be pre-fetched into Vuex via nuxtServerInit won't exist before the page is mounted. Thus, you need to be careful to add v-if test conditions for dependent Vuex data, like the header and footer.

Contributing

Run yarn dev to open a Nuxt dev build of the demo directory.