@blaze-cms/nextjs-tools

Blaze next.js tools

Provides tools to add blaze to your nextjs project. blaze-nextjs-tools/build has been deprecated and will be removed in the future. Please use/update blaze-nextjs-build-tools for generating next config. Blaze packages are listed in alias.json. Please update this file for shared new blaze dependencies. add third-party alias via project's next.config.js as follows:

const { getNextPlugins, getNextJsConfig } = require('@blaze-cms/nextjs-build-tools');
const withPlugins = require('next-compose-plugins');

const webpackCustomConfig = { plugins: [getSentryPlugin()] };
const config = getNextJsConfig({
  webpackCustomConfig,
  nextJsCustomConfig: {
    srcAliases: {
      '@sentry/browser': '@sentry/browser/esm'
    }
  }
});
const plugins = getNextPlugins();

module.exports = withPlugins(plugins, config);

Server side rendering

The withBlaze higher order component that is used to wrap Nextjs applications using the Blaze frontend. An example of usage can be seen in the example frontend app.js file.

This implements the server side rendering recommendations of the Apollo client.

Note: It also has an extra check while server side rendering that will force the page to complete rendering if the apollo client gets stuck. After 500ms if all the apollo queries are finished but apollo hasn't then the app will carry on with rendering.

App ctx

On each route change the app ctx gets set with: router, req, res;

Open Graph

The packages adds og metadata to the head of pages automatically. It uses the following hierarchy to get the domain

• process.env.BLAZE_FRONTEND_HOST
• req.headers['x-request-host'] // custom blaze header
• req.headers['x-forwarded-host'] // not always passed by all cdn
• req.headers.host

Static routes

This package adds routes for some frontend files that will return responses not rendered by react. Currently these requests still initially route through the Resolver. They may be split out in the future.

Currently the static routes and handlers are expandable. The handlers are set in the static route handler config. Any new routes will also be added to the routes config.

The routes handled are described below

/sitemap.xml

This static route outputs a sitemap xml files that it fetches from the api. It does this be querying the api for the latest sitemap index then downloads it and sends the response.

See the sitemap handler to see the api query.

This path can be overriden by setting the BLAZE_ROUTE_PATTERN_SITEMAP env.

/sitemap/[filename].xml

This static route outputs a sitemap file xml that it fetches from the api. It does this be querying the api for the latest sitemap by filename then downloads it and sends the response.

See the sitemap file handler to see the api query.

/robots.txt

This static route outputs a robots.txt xml files that it fetches from the api. It does this be querying the api for the latest created file with filename robots.txt from the store specified by process.env.BLAZE_STATIC_ROUTE_STORE_KEY if set or the default store. Then downloads it and sends the response.

So to server a robots.txt file simply upload one to the api with the name robots.txt and it will be served through this route.

See the robots.txt handler to see the api query.

Route regex

The route regex defines what paths will be checked with the api. Any url paths that don't match the regex will return a 404 error.

The default regex can be seen in constants

If you want to make it stricter or more open you can override the default with the environmental variable BLAZE_ROUTE_REGEX.

Note If you make it more open this could increase load on the frontend/api services as more paths will be checked with the api so if bot is targetting the server the load on both services will be higher.

Example

This example will also allow the path to contain . characters

^\/[a-z0-9€_\/]+(?:[-\/\.]{1,2}[a-z0-9\/€_\/]+)*$|^\/$

Environment variables

| Name | Description | Type | Default | |---|---|---| | BLAZE_FRONTEND_HOST | Frontend host (used to identify host) | String | | | BLAZE_ROUTE_REGEX | Override default route regex | /^/[a-z0-9€/]+(?:[-/.]{1,2}[a-z0-9/€/]+)*$|^/$/ | | BLAZE_CACHE_CONTROL_HEADER | Cache-Control header to set on page requests | String | "" | | BLAZE_STATIC_ROUTE_STORE_KEY | Override store for static file routes | default | | BLAZE_ROUTE_PATTERN_SITEMAP | Override sitemap route | /sitemap.xml | | BLAZE_CONTENT_SITEMAP_URL_PREFIX | Prefix for sitemap URL, used in frontend static route e.g. /sitemap/sitemap-0.xml. This needs to match the value set in the API app. | String | | | BLAZE_ROOT_SELECTOR_CLASSES_LIMIT | The number of root-selector classes to display. 0 or unset will show noe | String | | | BLAZE_BUILD_ENV_PREFIX_REGEX | '|' separated list of allowed environment variable prefixes. Any environment variable that matches this prefix pattern will be dynamically added to the next environment config and will be available in code for use. If the environment variable has a "BUILD_" prefix, then this prefix will be removed from the next environment variable name before assigning it. i.e. BUILD_THIRD_PARTY_ENV will become THIRD_PARTY_ENV in the build. Prefixes BLAZE|GOOGLE|JWPLAYER|DFP are added for backward compatibility and will be deprecated. We recommend to use new and change existing environment variables with "BUILD_" prefix. | BLAZE|GOOGLE|JWPLAYER|DFP|BUILD | | BLAZE_CONTENT_SITEMAP_URL_PREFIX | Prefix for sitemap URL, used in frontend static route e.g. /sitemap/sitemap-0.xml. This needs to match value set in API app. | String | | | BLAZE_DISABLE_REDIRECT_WITH_QUERY | Do not add query string to redirects | String | |

Events emitted

For more information about specific package events go to package README.

Key	Description
page-load:get-initial-props:before	Called in getInitialProps and passes in the nextjs ctx before running through AppTree

Tailwind

Tailwind CSS is a utility-first CSS framework packed with classes like flex , pt-4 , text-center and rotate-90 that can be composed to build any design, directly in your markup.

Setup

1. Update next package to version 10 in frontend application

2. Install tailwindcss, PostCSS and Autoprefixer packages in frontend application

cd packages/frontend/
yarn install tailwindcss@latest postcss@latest autoprefixer@latest --save

1. Add tailwind.config.js file in packages/frontend with following content

module.exports = {
  purge: ['./src/pages/**/*.js', './src/components/**/*.js'],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {}
  },
  variants: {
    extend: {}
  },
  plugins: []
};

1. Add postcss.config.js file in packages/frontend with following content

module.exports = {
  plugins: ['tailwindcss', 'autoprefixer']
};

When including Tailwind in your CSS in a Next.js project, there are two approaches you can take: directly in JS or in CSS.

Import Tailwind directly in JS

If you aren't planning to write any custom CSS in your project, the fastest way to include Tailwind is to import it directly in pages/_app.js:

  // pages/_app.js
 import '../styles/globals.css'
 import "tailwindcss/tailwind.css";

  function MyApp({ Component, pageProps }) {
    return <Component {...pageProps} />
  }

  export default MyApp

If you aren't planning to use them, you can safely delete any CSS files Next.js creates for you by default like globals.css and Home.module.css. Make sure you delete any references to them within your components as well.

Include Tailwind in CSS

Open the ./styles/globals.css file that Next.js generates for you by default (if file is missing then create it) and use the @tailwind directive to include Tailwind's base, components, and utilities styles, replacing the original file contents:

/* ./styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind will swap these directives out at build-time with all of the styles it generates based on your configured design system.

Read our documentation on adding base styles, extracting components, and adding new utilities for best practices on extending Tailwind with your own custom CSS.

Finally, ensure your CSS file is being imported in your pages/_app.js component:

// pages/_app.js
import '../styles/globals.css'

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

export default MyApp

If you've chosen to use a different file than the default globals.css file, you'll want to update the import accordingly.

Frontend checks

When checking new code or build configs make sure to check the following things.

Root selector classes

To make styling of sections of a site simpler, it is possible to enable setting root selector classes at the top of the Resolver page structure that are generated based on the url hierarchy.

For example the following url, /parent/child/article-123 might be broken into the following classes

root-selector--parent
root-selector--parent--child
root-selector--parent--child--article-123

To enable this the BLAZE_ROOT_SELECTOR_CLASSES_LIMIT env variable must be set to the number of classes you want to display e.g. if you want just the parent section set this to 1 and the only class will be root-selector--parent.

Note If this variable is set then the home page will have the classes root-selector.

Because of the url restrictions in core blaze the classes shouldn't need escaping/replacing as all characters should be supported.