json-bundler

Bundles your JSON files intelligently.

What it does

When developing web applications, we often use JSON files in order to define content (e.g. for internationalization) or extracting some form of configuration. Especially in the former case, we usually end up with one huge JSON file, probably a couple or hundred or thousand lines long.

Meet the json-bundler, a NodeJS-based command line tool, enabling you to place multiple JSON files in multiple places - and bundle them together intelligently.

For example, the json-bundler allows you to place your i18n files directly next to your component implementations (e.g. next to Angular components), or to reference JSON files published within a npm library.

How to install

You can get the json-bundler via npm by either adding it as a new devDependency to your package.json file and running npm install, or running the following command:

npm install json-bundler

Requirements

• json-bundler requires NodeJS 7.6 (or higher) to be installed
• If using Travis CI, we recommend setting the environment variable FORCE_COLOR to 1 in order to enable colored logging

How it works

Using the json-bundler is very straightforward. In general:

• Entry Point There must be exactly one JSON file acting as the singular entry point (e.g. index.json or en.json).
• References JSON files are referenced (and thus included) using the $ref key, and the path to the JSON file as the value. Reference paths are always relative to the JSON file they're being defined within. Paths starting with ~ are pointing to the project's node_modules folder (for easy npm library access).
• Bundling When bundling, referenced JSON files get merged in (instead of just placed in), at the exact position in the JSNO files at which they're being referenced. Existing values will not be overwritten by referenced files (the "referencee" has always higher priority).

Also: Both json and json5 files are supported, even in a mixed manner. That means you can do linebreaks, use comments, and much more. See JSON5 for further details.

How to use

It's recommended to use the json-bundler within one of your package.json scripts. For instance:

{
  "scripts": {
    "json:bundle": "json-bundler --entryFile <PATH> --outFile <PATH>"
  }
}

The following parameters are available:

• --entryFile <PATH> (required) defines the path to the root JSON / JSON5 file
• --outFile <PATH> (required) defines the path to the output file
• --minified enables, if used, the minification of the output file (production build, in other words)
• --watch enables the watch mode - which comes in very handy during development

You can always run json-bundler --help to get a full list of available command line parameters.

Example

The following is a very simple example, demonstrating the basics of json-bundler. For further examples, feel free to take a look at the unit tests of the library.

Source

First file at src/app/en.json (entry file):

{
  "title": "My application title",
  "login": {
    "$ref": "./pages/login.json5"
  },
  "home": {
    "title": "Welcome back, it's Christmas time!",
    "$ref": "./pages/home.json"
  },
  "footer": {
    "$ref": "~my-library/i18n/footer.json"
  }
}

Second file at src/app/pages/login.json5 (referenced file):

// Login Page
{
  "title": "Login", // TODO: Rename to register?
  "form": {
    "user": "Please enter your username.",
    "password": "Please enter your password."
  }
}

Third file at src/app/pages/home.json (referenced file):

{
  "title": "Welcome back!",
  "description": "Lorem ipsum dolor sit amet."
}

Fourth file at node_modules/my-library/i18n/footer.json (referenced file):

{
  "copyright": "My company",
  "legal": "My super-duper important legal information. Plus imprint, of course."
}

Notice that:

• One JSON file can reference multiple other JSON files
• The place of the reference within the JSON structure will define where the referenced file gets merged in
• The paths are relative to the file they are defined within
• The ~ symbol can be used to access libraries (as a shortcut)
• The paths include the file ending (either .json or .json5)

Bundling

We use the following command to create the bundle:

json-bundler --entryFile src/app/en.json --outFile dist/en.json

Notice that:

• We use the entry file from above
• We only define the required parameters here (entryFile and outFile)

Output

The result is a JSON file at dist/en.json, and it contains the following:

{
  "title": "My application title",
  "login": {
    "title": "Login",
    "form": {
      "user": "Please enter your username.",
      "password": "Please enter your password."
    }
  },
  "home": {
    "title": "Welcome back, it's Christmas time!",
    "description": "Lorem ipsum dolor sit amet."
  },
  "footer": {
    "copyright": "My company",
    "legal": "My super-duper important legal information. Plus imprint, of course."
  }
}

Notice that:

• Referenced files get merged in at the place they got referenced
• Files are included, no matter if they are json or json5, no matter if they exist within the project or come from a library
• The home/title has the value of the src/app/en.json file, and not the value defined in src/app/pages/home.json - the "parent" (aka the referencee) always has higher priority than the referenced file during merge

Creator

Dominique Müller

• E-Mail: [email protected]
• Website: www.devdom.io
• Twitter: @itsdevdom