Pipeline Caching

Efficient dependency caching in Jenkins Pipelines reduces build time by reusing previously created artifacts (for example, node_modules) instead of reinstalling them on every run. This is particularly valuable for ephemeral agents or fresh containers where every build starts from a clean environment. In this lesson you’ll learn how to enable and use the Jenkins Job Cacher plugin to cache dependencies (like node_modules) and reuse them across builds, speeding up CI and reducing load on package registries.

Why cache dependencies?

Fast feedback: Large JavaScript projects with thousands of packages can spend significant time in the install step. Caching reduces iteration time.
Bandwidth and registry load: Re-using previously downloaded packages reduces reliance on external registries.
Stability: Using a lockfile-driven cache helps ensure consistent dependency versions across builds.

How to enable caching in Jenkins

Install the Job Cacher plugin from the Jenkins plugin manager.
Configure a cache either using the Pipeline Snippet Generator or by adding the snippet directly to your Jenkinsfile.
Use a cache validity file (for npm: package-lock.json; for yarn: yarn.lock) to decide when to invalidate and recreate the cache.

First, install the plugin:

A dark-themed Jenkins plugin manager screen showing the "Available plugins" view with a highlighted "Job Cacher" plugin entry and an Install button.

After installation you may be prompted to restart Jenkins. Once Jenkins is running again, you can create cache definitions using the Pipeline Snippet Generator.

Configuring the cache (Pipeline Snippet Generator)

Recommended snippet settings for caching Node.js dependencies:

path: the directory to cache (e.g., node_modules)
cacheName: an identifiable name (e.g., npm-dependency-cache)
cacheValidityDecidingFile: a lockfile such as package-lock.json or yarn.lock used to detect changes
compression: choose an archive format (e.g., TARGZ)
maxCacheSize: a reasonable size limit (e.g., 550 MB)

In the Snippet Generator, choose the cache snippet and complete those fields. Example configuration in the Snippet Generator (screenshot):

A screenshot of a Jenkins "Pipeline Syntax" page showing cache configuration fields, with "package-lock.json" entered as the cache validity deciding file and the compression method set to TARGZ. The "Use default excludes" checkbox is checked and there are Include/Exclude input boxes visible.

Avoid caching sensitive files or environment-specific binaries. Use the cache for reproducible dependencies (like node_modules) and ensure the cache validity deciding file (lockfile) is trusted.

Tip: Use package-lock.json or yarn.lock as the cache validity deciding file. When the lockfile hash changes, the plugin will consider the cache stale and recreate it automatically.

Example Jenkinsfile snippets

Below are concise examples showing where to place the cache step in a Declarative Pipeline and how to use stash/unstash alongside caching when stages run on different agents. Installing Dependencies stage (cache node_modules and stash for later stages)

pipeline {
    agent any

    stages {
        stage('Installing Dependencies') {
            agent any
            options { timestamps() }
            steps {
                cache(maxCacheSize: 550, caches: [
                    arbitraryFileCache(
                        cacheName: 'npm-dependency-cache',
                        cacheValidityDecidingFile: 'package-lock.json',
                        includes: '**/*',
                        path: 'node_modules'
                    )
                ]) {
                    sh 'node -v'
                    sh 'npm install --no-audit'
                    // Use stash to transfer node_modules between stages/agents
                    stash(includes: 'node_modules/', name: 'solar-system-node-modules')
                }
            }
        }

        stage('Dependency Scanning') {
            steps {
                // dependency scanning steps here
            }
        }
    }
}

Notes:

cache wraps the steps that create or consume files under path. On first run the plugin will create the cache; on subsequent runs it will attempt to restore it.
Use stash/unstash to move files between stages or agents when the cache restore occurs on a different executor (for example, controller vs Kubernetes pod).

Unit Testing stage (unstash before running tests)

stage('Unit Testing') {
    parallel {
        stage('NodeJS 18') {
            options { retry(2) }
            steps {
                sh 'node -v'
                unstash 'solar-system-node-modules'
                sh 'npm test'
            }
        }

        stage('NodeJS 19') {
            options { retry(2) }
            steps {
                container('node-19') {
                    sh 'sleep 10s' // example - waiting for container readiness
                    sh 'node -v'
                    unstash 'solar-system-node-modules'
                    sh 'npm test'
                }
            }
        }
    }
}

Code Coverage stage example (non-blocking failures with catchError)

stage('Code Coverage') {
    steps {
        catchError(buildResult: 'SUCCESS', message: 'Coverage failures are non-blocking for now') {
            sh 'node -v'
            unstash 'solar-system-node-modules'
            sh 'npm run coverage'
        }
    }
}

Running the pipeline and interpreting cache logs

On the first run:

The plugin searches job and default caches.
If no up-to-date cache exists it will skip restoring, run the install step, then create and upload a new cache keyed by the lockfile hash.

On later runs:

If the lockfile hash matches a cached entry, the plugin restores the cache quickly and avoids re-downloading packages.

You can inspect the detailed cache-related entries in the classic Jenkins console output (look for lines beginning with [Cache]). View the job and build runs for visual feedback:

A screenshot of the Jenkins web UI showing the "feature/advanced-demo" pipeline with several build runs and stage progress indicators (green checkmarks and some warning icons). The left sidebar shows job actions and a build history list.

Console log excerpts (first build — cache not found, then created)

[Cache] Searching cache in job specific caches...
[Cache] Searching cache in default caches...
[Cache] Skip restoring cache as no up-to-date cache exists
+ node -v
v22.6.0
+ npm install --no-audit
up to date in 1s

[Pipeline] stash
Stashed 4993 file(s)

[Cache] Creating cache...
[Cache] got hash a47b9ef02dbc79db72ab6385105e0142 for cacheValidityDecidingFile(s) - actual file(s): /var/lib/jenkins/workspace/lar-system_feature_advanced-demo/package-lock.json
[Cache] Cache created in 1648ms

Console log excerpts (second build — cache restored)

[Cache] got hash a47b9ef02dbc79db72ab6385105e0142 for cacheValidityDecidingFile(s) - actual file(s): /var/lib/jenkins/workspace/lar-system_feature_advanced-demo/package-lock.json
[Cache] Found cache in job specific caches
[Cache] Restoring cache...
[Cache] Cache restored in 771ms

+ node -v
v22.6.0
+ npm install --no-audit
up to date in 1s

[Pipeline] stash
Stashed 4993 file(s)

[Cache] Skip cache creation as the cache is up-to-date

Quick reference

Setting	Purpose	Example
`path`	Directory to cache	`node_modules`
`cacheName`	Identifies the cache	`npm-dependency-cache`
`cacheValidityDecidingFile`	File used to compute cache hash and invalidate stale caches	`package-lock.json`
`compression`	Archive format for upload/download	`TARGZ`
`maxCacheSize`	Limit uploads to reasonable size	`550` (MB)

Summary

Install the Job Cacher plugin and configure a node_modules cache.
Use a lockfile (such as package-lock.json or yarn.lock) as the cache validity deciding file so the cache is recreated whenever dependencies change.
Combine cache with stash/unstash when stages run on different agents or when you need to transfer dependencies between stages.
Inspect the classic Jenkins console log for [Cache] entries to verify cache restore/create behavior.

Use the lockfile as the cache validity deciding file. This ensures the cache is recreated whenever dependencies change, preventing stale or incompatible node_modules from being reused.

References

Jenkins Job Cacher plugin documentation: https://plugins.jenkins.io/job-cacher/
npm lockfile guide: https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json

That’s all for this lesson — try modifying dependencies to see cache invalidation and recreation in action.

Shared Libraries in Jenkins

Agents and Nodes in Jenkins

Pipeline Enhancement and Caching

Pipeline Structure and Scripted vs Declarative

Jenkins Administration and Monitoring

Backup and Configuration Management

Introduction

Why cache dependencies?

How to enable caching in Jenkins

Configuring the cache (Pipeline Snippet Generator)

Example Jenkinsfile snippets

Running the pipeline and interpreting cache logs

Quick reference

Summary

Watch Video

​Why cache dependencies?

​How to enable caching in Jenkins

​Configuring the cache (Pipeline Snippet Generator)

​Example Jenkinsfile snippets

​Running the pipeline and interpreting cache logs

​Quick reference

​Summary

Watch Video

Why cache dependencies?

How to enable caching in Jenkins

Configuring the cache (Pipeline Snippet Generator)

Example Jenkinsfile snippets

Running the pipeline and interpreting cache logs

Quick reference

Summary