Installing Grunt.js

Installing Grunt.js

Before you can use Grunt, you need to install two things — the Grunt CLI (command-line interface) globally and Grunt itself locally in your project. This two-part installation is an important distinction that keeps your projects isolated and version-independent.

Step 1: Install the Grunt CLI Globally

npm install -g grunt-cli

The CLI (grunt-cli) is a small utility that looks for a locally installed Grunt in your project and runs it. Installing it globally means you can type grunt in any terminal, from any project directory.

Verify the installation:

grunt --version
// grunt-cli v1.x.x

Why Global CLI + Local Grunt?

Component	Installed	Purpose
grunt-cli	Globally (once per machine)	Provides the grunt command in your terminal
grunt	Locally (per project)	The actual task runner engine — each project can have its own version

This separation means different projects can use different versions of Grunt without conflicts. The CLI just delegates to whatever version is installed locally.

Step 2: Create a Project

mkdir grunt-project
cd grunt-project

Step 3: Initialize package.json

npm init -y

This creates a package.json file with default settings. The package.json tracks your project's dependencies including Grunt and its plugins.

Step 4: Install Grunt Locally

npm install grunt --save-dev

The --save-dev flag adds Grunt to the devDependencies section of package.json. This is correct because Grunt is a development tool — it is not needed in production.

// package.json after installation
{
    "name": "grunt-project",
    "version": "1.0.0",
    "devDependencies": {
        "grunt": "^1.6.1"
    }
}

Understanding devDependencies vs dependencies

Section	What Goes Here	Installed With
dependencies	Libraries your app needs to run (Express, React)	npm install package
devDependencies	Tools used only during development (Grunt, testing libs)	npm install package --save-dev

When deploying to production, you can run npm install --production which skips devDependencies. This keeps your production environment lean.

Step 5: Set Up the Project Structure

grunt-project/
├── src/
│   ├── js/
│   │   ├── module1.js
│   │   ├── module2.js
│   │   └── module3.js
│   └── scss/
│       └── styles.scss
├── dist/
│   ├── js/
│   └── css/
├── Gruntfile.js
├── package.json
└── node_modules/

Folder	Purpose
src/	Source files — your original, unprocessed code
src/js/	JavaScript source files (will be concatenated and uglified)
src/scss/	SASS source files (will be compiled to CSS)
dist/	Distribution files — processed output ready for production

Create Some Sample Files

Create a few JavaScript source files to work with:

src/js/module1.js

// Module 1: Utility functions
function greet(name) {
    return 'Hello, ' + name + '!';
}

function add(a, b) {
    return a + b;
}

src/js/module2.js

// Module 2: DOM helpers
function getElement(selector) {
    return document.querySelector(selector);
}

function setContent(selector, content) {
    getElement(selector).textContent = content;
}

src/js/module3.js

// Module 3: App initialization
function init() {
    var message = greet('World');
    setContent('#app', message);
    console.log('App initialized');
}

document.addEventListener('DOMContentLoaded', init);

src/scss/styles.scss

// SASS variables
$primary-color: #3498db;
$font-stack: Arial, sans-serif;
$bg-color: #ecf0f1;

body {
    font-family: $font-stack;
    background: $bg-color;
    color: #333;
    margin: 0;
    padding: 20px;
}

#app {
    max-width: 800px;
    margin: 0 auto;
    padding: 40px;
    background: white;
    border-radius: 8px;
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);

    h1 {
        color: $primary-color;
    }
}

Verifying the Setup

grunt --version

If you see the grunt-cli version and the local Grunt version, your setup is correct. If it says "Unable to find local grunt," make sure you ran npm install grunt --save-dev inside your project directory.

Key Takeaways

• Install grunt-cli globally with npm install -g grunt-cli — this provides the grunt command
• Install grunt locally with npm install grunt --save-dev — this is the actual task runner
• Use --save-dev because Grunt is a development tool, not a production dependency
• Organize your project with src/ for source files and dist/ for processed output
• The Gruntfile.js (created next) is where you will configure all your tasks and plugins