next-plugin-node-config

Next.js and node-config, together at last.

Install with npm:

npm install next-plugin-node-config

Install with Yarn:

yarn add next-plugin-node-config

Why?

Next.js already has built-in support for runtime configuration (in fact, this plugin is implemented using that) –  so why involve node-config as well?

node-config provides some features that are nicer for large applications:

1. Merging of (potentially many) different configuration files
   (including multiple supported formats) depending on the environment. This is
   useful for managing different configurations in staging, production, etc.
2. Nice error messages with config.get(). Instead of an unhelpful
   message about accessing a property of undefined, or silent bugs caused by
   using missing values, config.get() will throw an error with the full key
   path being requested.
3. It works in places where next/config doesn’t – for example, server files
   that have not been built by Next.js. In these situations, next/config will
   supply an undefined configuration because it has not performed its setup
   phase that populates these values – but config will still work.

How?

When called, this plugin imports config and uses the result to define serverRuntimeConfig and publicRuntimeConfig in the Next.js config that it returns.

• serverRuntimeConfig will come from config.serverRuntimeConfig, or a key of
  your choosing defined by nodeConfigServerKey. For example, a value of
  server will select config.server. If any existing serverRuntimeConfig
  value exists, it will be merged.
• publicRuntimeConfig will come from config.publicRuntimeConfig, or a key of
  your choosing defined by nodeConfigPublicKey. For example, a value of
  public will select config.public. If any existing publicRuntimeConfig
  value exists, it will be merged.
• A webpack alias is added for the config module that points to a browser shim
  provided by this plugin. It exports an object containing the configuration
  values retrieved from next/config, and compatible get() and has()
  methods.

Usage

Add some configuration files, for example config/default.js, then add this plugin to next.config.js.

Simplest usage with no existing Next.js config:

const withNodeConfig = require('next-plugin-node-config');

module.exports = withNodeConfig();

With existing Next.js config:

const withNodeConfig = require('next-plugin-node-config');

module.exports = withNodeConfig({
  // These will be merged on top of anything that comes from `config`!
  serverRuntimeConfig: {
    secret: 'entropy9'
  },
  publicRuntimeConfig: {
    api: '/graphql'
  },
  webpack(config, options) {
    // ...
    return config;
  }
});

Using the nodeConfigServerKey and nodeConfigPublicKey options, serverRuntimeConfig and publicRuntimeConfig can be named something nicer in your config files:

const withNodeConfig = require('next-plugin-node-config');

module.exports = withNodeConfig({
  nodeConfigServerKey: 'server',
  nodeConfigPublicKey: 'public'
});

In your application, you’re still free to use the next/config module directly:

import getConfig from 'next/config';

const { serverRuntimeConfig, publicRuntimeConfig } = getConfig();

…but you can now use config as well!

import config from 'config';

const secret = config.get('serverRuntimeConfig.secret');
const api = config.get('publicRuntimeConfig.api');

// …or if using the custom keys as in the example above:
const secret = config.get('server.secret');
const api = config.get('public.api');