Offensive Security Researcher & Quantum Cryptography Analyst

How to Set Up Jenkins for Node.js Projects

Abdul Wahab Junaid
How to Set Up Jenkins for Node.js Projects

I’ve worked with enough Node.js projects to know that manual testing and deployment gets old fast, especially once a team grows past one or two people. Setting up Jenkins for a Node.js project gives you automated builds, tests, linting, and deployments every single time code changes. In this guide, I’ll walk through the entire process — from installing the right tools to writing a production-ready pipeline.

Why Jenkins Works Well for Node.js

Node.js projects usually follow a predictable lifecycle: install dependencies, lint, test, build (if using TypeScript or a bundler), and deploy. Jenkins is flexible enough to model this lifecycle exactly, and its plugin ecosystem — including the NodeJS Plugin — makes managing multiple Node versions across projects painless.

Jenkins Architecture Quick Refresher

Jenkins has a controller that schedules and tracks jobs, and agents that execute them. For Node.js projects, I recommend running builds on agents with Node.js pre-installed (or installed on demand via the NodeJS Plugin), since npm installs can be resource-intensive and you don’t want to bog down your controller.

Step 1: Install Jenkins

If Jenkins isn’t installed yet:

sudo apt update
sudo apt install openjdk-17-jdk -y
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee \
  /usr/share/keyrings/jenkins-keyring.asc > /dev/null
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc]" \
  https://pkg.jenkins.io/debian-stable binary/ | sudo tee \
  /etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt update
sudo apt install jenkins -y
sudo systemctl enable jenkins
sudo systemctl start jenkins

Step 2: Install the NodeJS Plugin

Go to Manage Jenkins > Plugins > Available, search for “NodeJS,” and install it. This plugin lets you define multiple Node.js versions and automatically installs them on build agents as needed — no manual nvm juggling required.

After installing, go to Manage Jenkins > Tools, scroll to “NodeJS installations,” and add a version (e.g., Node 20.x). Give it a name like node-20 — you’ll reference this in your pipeline.

Step 3: Connect Your Git Repository

Create a new Pipeline job and configure it to pull from your Git repository (GitHub, GitLab, or otherwise), the same way you would for any other project. If you’re using a Jenkinsfile stored in your repo (recommended), point the job at “Pipeline script from SCM.”

Step 4: Write Your Jenkinsfile

Here’s a full example tailored for a typical Node.js project:

pipeline {
    agent any

    tools {
        nodejs "node-20"
    }

    environment {
        CI = 'true'
    }

    stages {
        stage('Checkout') {
            steps {
                git branch: 'main', url: 'https://github.com/yourusername/your-node-app.git'
            }
        }

        stage('Install Dependencies') {
            steps {
                sh 'npm ci'
            }
        }

        stage('Lint') {
            steps {
                sh 'npm run lint'
            }
        }

        stage('Test') {
            steps {
                sh 'npm test -- --coverage'
            }
        }

        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }

        stage('Package') {
            steps {
                sh 'tar -czf app.tar.gz dist/'
                archiveArtifacts artifacts: 'app.tar.gz', fingerprint: true
            }
        }
    }

    post {
        always {
            junit 'reports/junit.xml'
        }
        failure {
            echo 'Build or tests failed. Check logs for details.'
        }
    }
}

A few notes on this pipeline:

Step 5: Managing Environment Variables and Secrets

Most Node.js apps need environment variables (API keys, database URLs, etc.). Store these as Jenkins credentials and inject them safely:

environment {
    DATABASE_URL = credentials('database-url-secret')
}

Never hard-code secrets directly in your Jenkinsfile or .env files committed to Git.

Step 6: Running Tests and Generating Coverage Reports

If you’re using Jest, Mocha, or another test runner, configure it to output JUnit-compatible XML reports so Jenkins can visualize pass/fail trends over time:

"scripts": {
  "test": "jest --ci --reporters=default --reporters=jest-junit"
}

Then in Jenkins, the junit post-build step (shown above) picks up these results automatically and displays them in the build’s test report tab.

Step 7: Dockerizing and Deploying

Many Node.js teams containerize their apps for consistent deployment. Add a Docker stage to your pipeline:

stage('Docker Build') {
    steps {
        sh 'docker build -t yourdockerhub/node-app:${BUILD_NUMBER} .'
    }
}
stage('Push to Registry') {
    steps {
        withCredentials([usernamePassword(credentialsId: 'docker-hub-creds', usernameVariable: 'USER', passwordVariable: 'PASS')]) {
            sh 'echo $PASS | docker login -u $USER --password-stdin'
            sh 'docker push yourdockerhub/node-app:${BUILD_NUMBER}'
        }
    }
}

From there, deployment to Kubernetes, a VM, or a platform like AWS Elastic Beanstalk becomes the next logical stage.

Real-World Workflow Example

A typical setup I’d recommend for a small-to-mid-size Node.js team:

  1. Developer opens a pull request.
  2. Jenkins Multibranch Pipeline automatically detects the branch and runs lint + tests.
  3. On merge to main, Jenkins builds a Docker image, tags it with the commit SHA, and pushes it to a registry.
  4. A separate deployment pipeline (or manual approval gate) promotes the image to staging, then production.

Monorepo and Workspace Considerations

If you’re using npm/yarn/pnpm workspaces for a monorepo containing multiple packages, structure your pipeline to only build and test the packages affected by a given change:

stage('Detect Affected Packages') {
    steps {
        sh 'npx nx affected --target=test'
    }
}

Tools like Nx or Turborepo integrate cleanly with Jenkins since they’re just CLI commands under the hood — Jenkins doesn’t need any special monorepo awareness beyond running the right script.

TypeScript-Specific Considerations

For TypeScript projects, add a dedicated type-checking stage separate from your build step, since tsc --noEmit can catch type errors without needing a full build:

stage('Type Check') {
    steps {
        sh 'npx tsc --noEmit'
    }
}

This gives faster feedback on type errors before waiting for a full bundler build to complete.

Caching node_modules Between Builds

While npm ci is fast, repeated installs across many builds can still add up. Some teams configure a shared cache directory outside the workspace:

stage('Install Dependencies') {
    steps {
        sh 'npm ci --prefer-offline --cache /var/jenkins_cache/npm'
    }
}

Just be cautious with concurrent builds sharing the same cache directory, as simultaneous writes can occasionally cause corruption — per-agent or per-executor cache paths avoid this issue entirely.

Troubleshooting Common Issues

Handling Environment-Specific Builds

Many Node.js apps need different build outputs for staging versus production (different API endpoints, feature flags, etc.). A clean way to handle this in a Jenkinsfile is passing a build-time environment variable through to your bundler:

stage('Build') {
    steps {
        sh "NODE_ENV=${params.ENVIRONMENT} npm run build"
    }
}

Combined with a Choice Parameter for ENVIRONMENT, this lets the same Jenkinsfile produce environment-specific builds without duplicating pipeline logic.

Security Best Practices

Working with Monorepo Tools Like Turborepo

If your Node.js project uses Turborepo for a monorepo setup, Jenkins doesn’t need any special configuration beyond invoking the right CLI commands — Turborepo’s own caching handles most of the speed optimization:

stage('Build Affected') {
    steps {
        sh 'npx turbo run build --filter=...[origin/main]'
    }
}

This only rebuilds packages affected by the current change set compared to main, which can save significant time on large monorepos with many independent packages.

FAQs

Q: Can I use multiple Node.js versions across different jobs? Yes, define each version separately under Global Tool Configuration, then reference the specific one you need in each Jenkinsfile’s tools block.

Q: Does Jenkins support Yarn or pnpm instead of npm? Absolutely — just replace the shell commands (yarn install, pnpm install) accordingly; Jenkins doesn’t care which package manager you use.

Q: How do I speed up npm installs in Jenkins? Consider using npm ci with a local npm cache directory, or set up a private npm registry proxy like Verdaccio or Nexus.

Q: Can Jenkins run my Node.js app’s end-to-end tests (like Cypress or Playwright)? Yes, though you may need to install additional system dependencies (like browser binaries) on your Jenkins agent, or run them inside a Docker container that already has these pre-installed.

Summary

Setting up Jenkins for a Node.js project isn’t complicated once you understand the pieces: the NodeJS Plugin for managing versions, a well-structured Jenkinsfile for your build/test/deploy stages, and proper credential handling for secrets. Once this pipeline is in place, your team gets fast feedback on every change and a repeatable path to production.

References

Exit mobile version