grunt-package

by Delta Source

Introduction

This simple library for grunt is intended for rewriting package.json files during your build. The idea is, that you isolate your build directories from your source directory. This way, your source directory will always remain clean.

Example:

• / (project root).

  This folder might contain the grunt file, but this is not necessary. I consider the grunt file as a source file as well.

  • src/

    Your sources. This folder should contain your source package.json file, as well as all other sources. Typicaly, your package.json file will have dev dependencies here. This is the folder you open in your IDE, and that you commit to git.

  • build/ (created by grunt)

    Your build folder. When you run grunt, your project is built into this folder. Here, you will also find some generated sources, like css files generated from less, html files generated from jade templates, etc.

    This is where you run your tests. You'll notice that some of your normal dev dependencies (like jade, less...) are no longer needed here. You'll only need these in src/. So it's safe to remove those. You'll also want your package.json to have a build timestamp, and maybe the user who performed the build. For traceability.

  • dist/ (created by *grunt release)

    Your release folder. This is a transformation of the build folder, with minimised versions of the sources, some removed folders etc. In the end, this is what you wish to publish to the npm registry. In the package.json file, you may want to remove the private property, and you might want to set a publishConfig.

Why rewriting?

You'll want to process your package.json file as a part of your build, if - for example - you want to change folders or properties. This way, you can manage versions easier, or make sure only a release is publishable to npm, etc.

Some examples:

• in src/

    {
    	"name": "grunt-package",
    	"description": "Grunt Package Tasks",
    	"version": "0.1.0",
    	
    	"author": {
    		"name": "Delta Source OOD, Bulgaria",
    		"email": "info@deltasource.eu",
    		"url": "http://www.deltasource.eu"
    	},
    	
    	"contributors": [
    		"daankets":{
    			"name":"Daan Kets",
    			"email":"daankets@deltasource.eu"
    		}
    	],
  
    	"private": "true",
  
    	"main":"tasks/package.js",
    
        "repository": {
            "type": "git",
            "url": "http://git.deltasource.eu/deltasource/grunt-package.git"
        },
    
        "dependencies": {
            "grunt": "0.4.x"
        },
    
        "devDependencies": {
            "grunt": "latest"
        },
    
        "testDependencies": {
            "nodeunit": "latest"
        }
    }
  

• in build/

    {
    	"name": "grunt-package",
    	"description": "Grunt Package Tasks",
    	"version": "0.1.0",
    	"author": {
    		"name": "Delta Source OOD, Bulgaria",
    		"email": "info@deltasource.eu",
    		"url": "http://www.deltasource.eu"
    	},			
    	"contributors": [
    		"daankets":{
    			"name":"Daan Kets",
    			"email":"daankets@deltasource.eu"
    		}
    	],
    	"private": "true",
    	"main":"tasks/package.js",                
        "dependencies": {
            "grunt": "0.4.x"
        },
        "devDependencies": {
            "nodeunit": "latest"
        }
    }
  

• in dist/

    {
    	"name": "grunt-package",
    	"description": "Delta Source JavaScript Project Tooling",
    	"version": "0.1.0",
    	"author": {
    		"name": "Delta Source OOD, Bulgaria",
    		"email": "info@deltasource.eu",
    		"url": "http://www.deltasource.eu"
    	},
    	"contributors": [
    		"daankets":{
    			"name":"Daan Kets",
    			"email":"daankets@deltasource.eu"
    		}
    	],
    	"main":"tasks/package.js",                
    	"dependencies": {
       		"grunt": "0.4.x"
        }
   	}
  

Configuration

You can configure the package options in the grunt config, with one configuration per 'target'. The following options exist:

• srcDir : "relativePath/" - The source directory (should contain the source package.json)
• destDir : "relativePath/" - The destination directory (will contain the target package.json)
• pretty : true | spaceCount - The source directory (should contain the source package.json)
• remove : ["propertyName",...] - A list of properties to delete from the package.json file.
• move : [["propertyNameFrom","propertyNameTo"],...] - A list of property pairs to move within the package.json file.
• add : {"key":value} An object with keys and values to add within the package.json file.

Example:

• In your src package.json:

    "devDepenencies":{
    	"grunt-package":"latest"
    }
  

• In your gruntfile.js (assuming it's in the src dir, and of course you'll need other build tasks as well...):

    module.exports = function (grunt) {
  
    grunt.initConfig(
    	{
    		sourceDir: "./",
    		buildDir: "../build/",
    		releaseDir: "../dist/",
    		package: {
    			build: {
    				pretty: 4,
    				srcDir: "<%=sourceDir%>",
    				destDir: "<%=buildDir%>",
    				remove: ["devDependencies","repository"],
    				move: [
    					["testDependencies", "devDependencies"]
    				],
    				add: {
    					"build": {
    						"timestamp": new Date(),
    						"user": process.env.USER
    					}
    				}
    			},
    			release: {
    				pretty: false,
    				srcDir: "<%=buildDir%>",
    				destDir: "<%=releaseDir%>",
    				remove: ["devDependencies", "private"]
    			}
    		}
    	}
    );
  
    grunt.loadNpmTasks("grunt-package");
  
    grunt.registerTask("default", ["package:build"]);
  

Notes

• The package task will NEVER change your source package.json file. Your destination package.json file MUST be different from the source package.json file.
• In a multiple-phase setup [build, release...], you'll want to use the output package.json from the previous phase as the input for the next phase.
• The package task will NOT create directories for you. You'll need to do that yourself. This is part of a security measure in order to avoid mistakes.

License

This library is released under the Create Commons Attribution-ShareAlike 4.0 International License