next-plugin-node-config
v1.0.2
Published
Next.js and [node-config][], together at last.
Downloads
2,352
Readme
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:
- 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.
- Nice error messages with
config.get()
. Instead of an unhelpful message about accessing a property ofundefined
, or silent bugs caused by using missing values,config.get()
will throw an error with the full key path being requested. - 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 – butconfig
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 fromconfig.serverRuntimeConfig
, or a key of your choosing defined bynodeConfigServerKey
. For example, a value ofserver
will selectconfig.server
. If any existingserverRuntimeConfig
value exists, it will be merged.publicRuntimeConfig
will come fromconfig.publicRuntimeConfig
, or a key of your choosing defined bynodeConfigPublicKey
. For example, a value ofpublic
will selectconfig.public
. If any existingpublicRuntimeConfig
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 fromnext/config
, and compatibleget()
andhas()
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"
});