Nuxt Hatchly Pages Module

Module to easily integrate with Hatchly pages

Installation

yarn add @hatchly/nuxt-pages-module

Register the module in your nuxt applications config file:

module.exports = {
    // Nuxt config
    modules: [
        // Other Modules
        ['@hatchly/nuxt-pages-module', {
            // Options
        }],
    ],

    hatchly: {
        pages: {
            // Options can also be defined here
        },
    },
};

Options

The options object can contain the following values:

{
    cacheTimeout: Number,
    disableBackgroundFetch: Boolean,
},

Each option is described below.

cacheTimeout

The duration, in seconds, until the cached date is refreshed. The cache can be disabled completely by passing a falsey value.

• Default: 3600 (1 hour)
• Type: number|boolean

disableBackgroundFetch

By default, if the cache is enabled, all requests will still happen regardless, but will instead happen asynchronously on the server side after the cached data has been returned. Set this option to true to prevent this functionality entirely, and always rely on traditional caching.

• Default: false
• Type: boolean

Runtime Config

By default, this package will utilise API_URL and API_URL_BROWSER variables as defined in your env. These are injected as runtime variables for you.

You can supply your graphql endpoint manually to the module via the publicRuntimeConfig and privateRuntimeConfig objects, e.g.:

module.exports = {
    /** ... */
    publicRuntimeConfig: {
        /** ... */
        GRAPHQL_ENDPOINT: process.env.API_GRAPHQL_URL_BROWSER,
    },
    /** ... */
    privateRuntimeConfig: {
        /** ... */
        GRAPHQL_ENDPOINT: process.env.API_GRAPHQL_URL,
    },
};

If the api is accessible on an internal address, you can skip dns lookup and replace the env variable in privateRuntimeConfig object with a different variable pointing to this address.

Features

GraphqlQL request client

This module will automatically install and register the nuxt-graphql-request module and set up the client.

It will also provide a helper for interacting with the client:

export default {
    async asyncData({ app }) {
        const data = await app.$hatchlyGraphQL(HomepageQuery, {
            uri: $route.params.article,
        });
    
        return data;
    },
};

This method accepts the following arguments:

$hatchlyGraphQL(query, variables)

query

The GraphQL query for the client.

• Default: undefined
• Type: string or GraphQL AST
• required

variables

Variables to pass into the query.

• Default: {}
• Type: object

$attr Helper

This module provides an $attr() helper method to the Vue instance. This is the safer way of accessing attributes. This is essentially a wrapper around the lodash/get method, with a bit of extra flavour.

Usage

The default usage for this component assumes that your page data is available as this.page within your page-level component, so ensure your data from GraphQL is returned in this form for this usage.

<!-- Get a single value -->
<h1>{{ $attr('header.title') }}</h1>

<!-- Get a single value with fallback value -->
<h2>{{ $attr('header.subtitle', 'My subtitle') }}</h2>

<!-- This is especially useful when performing loops where the data may not exist -->
<ul>
    <li 
        v-for="item in $attr('content.items', [])" 
        :key="item.title"
    >
        {{ item.title }}
    </li>
</ul>

If your top level data is different to page you can specify a different object as the first argument, and the other arguments will shift accordingly.

<h1>{{ $attr(pageData, 'header.title') }}</h1>

You can also use this in sub components/loops as a safe alternative to nested data structures, where the first argument would be whatever dataset you were accessing.

<ul>
    <li 
        v-for="item in $attr('content.items', [])" 
        :key="item.title"
    >
        {{ $attr(item, 'image.name') }}
    </li>
</ul>

Convenience modifiers

By default this method will do the following things to certain attribute types:

• RepeatableSections will return the instance automatically instead of having to access the full $attr('attribute.path.instance', []) path.
• If accessing a page uri, it will automatically prefix the path with a / in order to ensure correct navigations within the router.
• If accessing a page-link object, it will automatically prefix the uri with a / in order to ensure correct navigations within the router.
• For attributes that return a nested value property, we return this by default instead of having to access the full $attr('attribute.path.value') path.

WYSIWYG Attribute Component

When using WYSIWYG attributes, it's recommended to use the provided <wysiwyg-attr /> component rather than manually binding to an element with v-html. This component will convert the html to render functions and return the content within a tag you have provided, or div by default. Using render functions allows the html to be rendered as elements within the virtual dom that can easily inherit styling. It also allows for converting internal links to router transitions, rather than forcing an entirely new page load.

<wysiwyg-attr
    :html="$attr('body.content')"
/>

This component accepts two props:

html

The value of your wysiwyg attribute.

• Default: ''
• Type: string

tag

The tag of the wrapper component.

• Default: 'div'
• Type: string

Storybook

This module exposes a storybook integration to add the $attr global and the WysiwygAttr component. Simply pull the following module into your project, in the preview.js file for example:

import '@hatchly/nuxt-pages-module/storybook';