@endgame/oscar v1.0.3

O.S.C.A.R.

Operative Strategies Centralizing Annoying Requirements

Installation

npm i -D @endgame/oscar

The setup

Add the module to your nuxt.config.js.

🚨 Nota bene
This module won't work without nuxt-i18n.
See the module's setup.

{
  modules: [
      '@endgame/oscar',
  ],
  oscar: {
      /**
       * This is the default one...
       * so you don't need to declare your CMS
       * if you're using DatoCMS.
       */
      cms: 'datocms'
  }
}

The supported CMSs values are:

• datocms

Then you'll need to add your OSCAR_CMS_TOKEN (which is your DatoCMS read only token 😉) into your .env file, otherwise OSCAR won't be able to communicate with DatoCMS.

The features

👉 Easy Data

👉 Global Data

👉 Crawler

👉 Staticify

👉 Redirect

Easy Data

OSCAR will help you ease your data fetching process.

In order to enable this function you'll need to pass a query to your ~/pages component.

Under the hood OSCAR will handle the Nuxt's asyncData function for you.

... <pages-name>.vue
oscar: {
    query: gql`
        query HomePage($lang: SiteLocale) {
            homePage(locale: $lang) {
                entityTitle
            }
        }
    `,
},
...

SEO

You can also handle SEO easily 😏 OSCAR will set a seo property into your component.

You'll be able to access it via this.seo... after passing your seoQuery in OSCAR component's options.

... <pages-name>.vue
oscar: {
    query: homePageQuery,
    seoQuery: gql`
        query HomePage($lang: SiteLocale) {
            homePage(locale: $lang) {
                seo {
                    title
                    description
                    image {
                        url
                        alt
                        width
                        height
                    }
                    twitterCard
                }
            }
        }
    `
},
head() {
    return {
        ...this.seo
    };
}
...

Global Data

Getting global data for your global SEO, header, footer, etc. has never been that simple! 👌

In your src directory (by default that's your projet's root directory 😉) create the following folder structure ~/app/oscar/queries.

Then, within it, add globalDataQueries.js.

In this file you'll need to expose two variables:

• layoutDataQuery
• globalSeoQuery

You'll find the generated json files into the directory ~/oscar/data.

Example:

import gql from 'graphql-tag';

export const layoutDataQuery = gql`
    query Layout($lang: SiteLocale) {
        header(locale: $lang) {
            menuLinks {
                linkText
            }
        }
        footer(locale: $lang) {
            icons {
                iconTitle
            }
        }
    }
`;

export const globalSeoQuery = gql`
    query GlobalSeo($lang: SiteLocale) {
        _site {
            globalSeo(locale: $lang) {
                facebookPageUrl
                siteName
                titleSuffix
                twitterAccount
                fallbackSeo {
                    description
                    title
                    twitterCard
                    image {
                        url
                        alt
                        width
                        height
                    }
                }
            }
        }
    }
`;

Crawler

Configuring dynamic pages generation can be difficult... especially if you want to blacklist some pages without too much configuration.

OSCAR is here to help you!

You will need two things:

• The query that will find your pages' slugs and specific keys (page's id).
• The routes configuration file that will link the pages' keys with your nuxt-i18n routes declaration.

The query

In your src directory (by default that's your projet's root directory 😉) create the following folder structure ~/app/oscar/queries.

Then, within it, add crawlerQuery.js.

In this file you'll need to expose only one thing: the query responsible for getting your pages' info.

import gql from 'graphql-tag';

/**
 * In this example you can see that we're getting two pages model info.
 * For each one we'll need:
 * - their slugs, in order to generate their url.
 * - their _modelApiKey (which is their type id)
 * to link Dato's logic with your i18n's logic.
 */
export default gql`
    query Crawler($lang: SiteLocale) {
        allBasicPages(locale: $lang) {
            slug
            _modelApiKey
        }
        allDynamicSinglePages(locale: $lang) {
            slug
            _modelApiKey
        }
    }
`;

Routes configuration

In your src directory (by default that's your projet's root directory 😉) create the following folder structure ~/app/oscar/routes.

Then, within it, add index.js.

In this file you'll need to expose multiple variables:

• routes: this will be your routes list.
• routeByApiModels: this will be the mapping between your _modelApiKey and your routes definitions.
• excludedDynamicRoutes (optionnal): this will be an array of regular expressions allowing you to exclude specific routes.

Example:

// 🚦Routing constants
export const routes = {
    basicPage: {
        i18nFormat: '_slug',
        routerFormat: 'slug'
    },
    dynamicSinglePage: {
        i18nFormat: 'dynamic/_dynamic',
        routerFormat: 'dynamic-dynamic'
    }
};

export const routeByApiModels = {
    basic_page: routes.basicPage,
    dynamic_single_page: routes.dynamicSinglePage
};

// NOTE: You can prevent dynamic routes from being generated only in production for example 😏
const prodBlacklist = [/\/dynamic/];

const generalBlackList = [];

export const excludedDynamicRoutes = (isProdEnv = process.env.isProdEnv) =>
    isProdEnv ? prodBlacklist : generalBlackList;

Staticify

OSCAR is a cool dude, by default he will generate fully static routes for you! You don't need to do anything... no more API calls between route changes 😏

But... I know you... you'll ask me:

"What if I don't want to 'staticify' a specific page? 🤔"

BOOYA! I thought about that 😏

Prevent staticifying specific routes

In your src directory (by default that's your projet's root directory 😉) create the following folder structure ~/app/oscar/static/config.

Then, within it, add index.js. This file will only need to expose a blacklist property containing regular expressions.

export const blacklist = [/\/dynamic/];

Redirect

OSCAR will help you generating redirections for Netlify. He will generate a _redirects file for you, populated with the redirections coming directly from DatoCMS.

In your src directory (by default that's your projet's root directory 😉) create the following folder structure ~/app/oscar/queries.

Then, within it, add redirectionsQuery.js.

In this file you'll need to expose only one thing: the query responsible for getting your redirections.

import gql from 'graphql-tag';

export default gql`
    query Redirections {
        redirectionGroup {
            redirections {
                redirectionText
            }
        }
    }
`;