grunt-jsonfile
grunt-jsonfile is a multitask plugin which can create, delete or modify JSON files.
When running projects with babel, typescript, rollup oder webpack, building the project may require JSON files, that depend on values generated during the build.
While grunt is running a build process by calling a number of tasks, grunt-jsonfile can be used by grunt to pass collected data to existing or newly created JSON files.
Another way to use grunt-jsonfile is, to cut down an existing JSON file, which is a mechanism being used, during the process of building the package grunt-jsonfile.
The file named package.json, which is part of grunt-jsonfiles npm package, is the result of cutting away all developer dependencies, that can be found in the projects package.json file on github.
grunt
is a task runner written in Javascript that can be used to build projects. For this purpose grunt integrates plugins that contribute to the build process with their different capabilities.
grunt-jsonfile is open source software (OSS) and distributed under the MIT License.
Prerequisites for installing grunt-jsonfile are an existing npm that ships with nodejs and grunt.
npm install grunt-jsonfile --save-dev
Configuration of the plugin is usually done via an entry in the grunfile.js file. To be able to keep an overview of the configuration even when using many plugins, we use the package load-grunt-config. This way we can keep a separate configuration file for each plugin, as the following example shows.
// file jsonfile.js
module.exports = function ( grunt, options ) {
return {
options: {
EOF: true,
templates: {
one: "package.json",
two: {
pname1: 5,
pname2: true,
pname3: "value",
pname4: "${ BUILD }",
aproperty: "a aproperty will be deleted"
},
three: {
compilerOptions: {
outDir : "xxx",
target : "xxx",
module : "xxx",
moduleResolution : "node",
declaration : true,
inlineSourceMap : true,
inlineSources : true,
emitDecoratorMetadata : true,
experimentalDecorators : true,
importHelpers : true,
typeRoots : [ "node_modules/@types", "lib/@types" ],
lib : [ "dom", "es2018" ]
},
include : [ "../build/**/*.ts" ],
exclude : [ "../build/test/**/*" ]
}
}
},
target1: {
test: "value",
dest: "./src/test/tmp/target1.json"
}
}
};
grunt-jsonfile
Which parameters are supported by grunt-jsonfile?
grunt-jsonfile does not utilize a third party package, which is, why there are no parameters to support.
Properties in grunt-jsonfiles configuration file are directly consumed by the plugin.
Whats the structure of grunt-jsonfiles configuration?
grunt-jsonfile is a multitask plugin, which means, its configuration file may consist of the optionstarget
While the options section utilizes a fixed name, targets may have any name you like.
Which options are supported by grunt-jsonfile?
The options section supports one EOFtemplates
A template can be referenced by a path that has to be relative to the projects root directory, or it can be a collection of properties.
What is the projects root directory?
The projects root directory is the one, which holds the projects package.json file.
Property options {Object}
This property can be configured for all tasks or per task.
The example sets options for all task sections following the options section.
grunt
Property EOF {Boolean}
When saving JSON files, they may or may not end with EOF. Setting this value to true, will force JSON files being written by grunt-jsonfile to end with EOF.
grunt-jsonfile
Property templates {Object}
The templates property is an Object without specific propertys. Each of them is interpreted as “name” for a template, which can be referenced by target sections.
A template property can hold a string value, which then will be interpreted as relative path to a JSON file, or it can directly hold an object structure, which will be interpreted as inline JSON object template.
// templates section
const templates = {
one: "package.json",
two: {
pname1: 5,
pnamen: BUILD
},
three: {
compilerOptions: {
outDir: "${ DIR }",
target: "xxx",
typeRoots: [ "node_modules/@types", "lib/@types" ]
}
}
};
grunt-jsonfile
grunt-jsonfile maps names to templates.
To the left you can find a template section which holds the templates for JSON files.
Template “one” references the projects package.json file.
Template “two” holds a property “pnamen” which receives its value at the time the grunt-jsonfiles configuration is read.
The value will be taken from a variable named BUILD, which might be provided by grunt, a function or some process.
Property <targetname> {Object}
grunt-jsonfile is a multitask plugin, which means, there can be any number of targets to run.
Each target requires a number of properties.
// file jsonfile.js
module.exports = function ( grunt, options ) {
return {
target1: {
// ... further properties go here!
}
};
};
grunt
Because grunt tasks need to be named, target1
Property template {string|Object}
The template property can be of type String or Object.
A string can reference a template or be a path to a JSON file.
If template is an object, it is used as template.
// file jsonfile.js
module.exports = function ( grunt, options ) {
return {
options: {
templates: {
sometemplate: <...>
}
},
target1: {
template: "sometemplate"
},
target2: {
template: "path/to/file.json"
}
target3: {
template: {
property: value
}
}
}
};
grunt-jsonfile
The example to the left defines:
– a template named “sometemplate”
– target1
– target2
– target3
target1 uses its template property to reference template “sometemplate” from the options section.
target2 uses its template property to reference a JSON file found at ${projectdir}/path/to/file.json
target3 uses its template property by defining its own JSON object with one “property”.
Property dest {string}
The property dest defines the target file, which is to be written by grunt-jsonfile.
The path is relative to the project directory.
// file jsonfile.js
module.exports = function ( grunt, options ) {
return {
target1: {
template: {
property: value
},
dest: "path/to/destination.json"
},
target2: {
template: "package.json",
dest: [
"path/to/file1.json",
"path/to/file2.json",
"path/to/file3.json"
]
}
}
};
grunt-jsonfile
The example to the left will write a JSON file with one property to:
${project}/path/to/destination.json
It will as well copy the file package.json to three different files.
Property set {Object}
The property set holds properties, which will set new values to the resulting JSON file.
Properties set to null will show up in the resulting JSON file.
// file jsonfile.js
module.exports = function ( grunt, options ) {
return {
target: {
template: {
property0: 5,
property1: value,
property2: "other value"
},
dest: "path/to/destination.json",
set: {
property1: null,
property2: "edited",
property3: "new property"
}
}
}
};
grunt-jsonfile
The example to the left will result in the following JSON file
// file path/to/destination.json
{
property0: 5,
property1: null,
property2: "edited",
property3: "new property"
}
Result: A property set to null, will show up in the JSON file.
Property merge {Object}
The property merge holds properties, which will set new values to the resulting JSON file.
Properties set to null will NOT show up in the resulting JSON file.
Notice: Setting and merging properties will handle properties set to NULL in different ways! Merge opens an option to delete properties.
// file jsonfile.js
module.exports = function ( grunt, options ) {
return {
target: {
template: {
property0: 5,
property1: value,
property2: "other value"
},
dest: "path/to/destination.json",
merge: {
property1: null,
property2: "edited",
property3: "new property"
}
}
}
};
grunt-jsonfile
The example to the left will result in the following JSON file
// file path/to/destination.json
{
property0: 5,
property2: "edited",
property3: "new property"
}
Result: A property set to null, will NOT show up in the JSON file.
Property update {Object}
The property update holds properties, which will set new values to the templates properties. Update can be used to ensure, a resulting JSON file does hold only properties, which are part of the template.
Properties, which are not part of the template, will not show up in the resulting JSON file.
Properties set to null, will show up in the resulting JSON file only, if they are part of the template properties.
// file jsonfile.js
module.exports = function ( grunt, options ) {
return {
target: {
template: {
property0: 5,
property1: value,
property2: "other value"
},
dest: "path/to/destination.json",
update: {
property1: null,
property2: "edited",
property3: "new property"
}
}
}
};
grunt-jsonfile
The example to the left will result in the following JSON file
// file path/to/destination.json
{
property0: 5,
property1: null,
property2: "edited"
}