NPM Build

The npm-build jobs are used to build Node.js applications using npm or Yarn. These jobs install dependencies and build the application for deployment.

Overview

The npm-build jobs include:

• .npm-build: Build job using npm package manager
• .yarn-build: Build job using Yarn package manager

Both jobs:

• Install dependencies
• Run build scripts
• Cache dependencies for faster subsequent builds
• Create build artifacts for use in subsequent pipeline stages

Variables

The following variables can be configured:

Variable	Description	Default	Required
NPM_BUILD_PATH	Path to the npm project root directory	'./'	No
NPM_NODE_IMAGE	Docker image to use for npm builds	'node:20-alpine'	No
NODE_BUILD_OPTS	Options passed to npm run build	""	No
YARN_IMAGE	Docker image to use for Yarn builds	'node:20-alpine'	No
YARN_BUILD_PATH	Path to the Yarn project directory	'wp-content/themes/wp-starter'	No
YARN_BUILD_OPTS	Options passed to yarn build	''	No

Variable Details

• NPM_BUILD_PATH: The directory path where the npm project is located. Defaults to the repository root ('./').
• NPM_NODE_IMAGE: The Docker image used to run npm commands. Defaults to node:20-alpine.
• NODE_BUILD_OPTS: Command-line options passed to npm run build. Empty for development builds, can be set to --production for production releases.
• YARN_IMAGE: The Docker image used to run Yarn commands. Defaults to node:20-alpine.
• YARN_BUILD_PATH: The directory path where the Yarn project is located. Defaults to 'wp-content/themes/wp-starter' (WordPress theme path).
• YARN_BUILD_OPTS: Command-line options passed to yarn build. Can be used to run other npm scripts for development builds.

GitLab CI/CD Variables

The jobs use the following built-in GitLab CI/CD variable:

• PROJECT_ID: Project identifier used for cache key isolation

Job Types

.npm-build

Build job using npm package manager.

Usage

variables:
  NPM_BUILD_PATH: './'
  NPM_NODE_IMAGE: 'node:20-alpine'
  NODE_BUILD_OPTS: ""

.npm-build:
  image: $NPM_NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH
    - rm -rf .git
  script:
    - npm install && npm run build $NODE_BUILD_OPTS
  cache:
    key: "$PROJECT_ID_node_modules"
    paths:
    - node_modules/
  artifacts:
    paths:
    - ./    
    expire_in: 1 hour

Job Details

Before Script:

1. Changes to the NPM_BUILD_PATH directory
2. Removes the .git/ directory to reduce artifact size

Script:

npm install && npm run build $NODE_BUILD_OPTS

• Installs all dependencies from package.json
• Runs the build script defined in package.json
• Applies NODE_BUILD_OPTS if provided

Cache:

• Caches node_modules/ directory
• Cache key: $PROJECT_ID_node_modules (ensures cache isolation per project)

Artifacts:

• Creates artifacts containing the entire project directory (./)
• Expires after 1 hour

Example Configurations

Development Build:

variables:
  NODE_BUILD_OPTS: ""  # Empty for dev build

Production Build:

variables:
  NODE_BUILD_OPTS: "--production"  # Production release

Custom Build Path:

variables:
  NPM_BUILD_PATH: './frontend'
  NPM_NODE_IMAGE: 'node:20-alpine'

.yarn-build

Build job using Yarn package manager.

Usage

variables:
  YARN_IMAGE: 'node:20-alpine'
  YARN_BUILD_PATH: 'wp-content/themes/wp-starter'
  YARN_BUILD_OPTS: ''

.yarn-build:
  image: $YARN_IMAGE
  before_script:
    - cd $YARN_BUILD_PATH
    - rm -rf .git/ 
  script:
    - yarn && yarn build $YARN_BUILD_OPTS
  cache:
    key: "$PROJECT_ID_node_modules"
    paths:
    - wp-content/themes/wp-starter/node_modules
  artifacts:
    paths:
    - ./    
    expire_in: 1 hour

Job Details

Before Script:

1. Changes to the YARN_BUILD_PATH directory
2. Removes the .git/ directory to reduce artifact size

Script:

yarn && yarn build $YARN_BUILD_OPTS

• Installs all dependencies using Yarn
• Runs the build script
• Applies YARN_BUILD_OPTS if provided (useful for running other npm scripts for development builds)

Cache:

• Caches node_modules/ directory at the specified path
• Cache key: $PROJECT_ID_node_modules
• Note: Cache path is hardcoded to wp-content/themes/wp-starter/node_modules in the example

Artifacts:

• Creates artifacts containing the entire project directory (./)
• Expires after 1 hour

Example Configurations

WordPress Theme Build:

variables:
  YARN_BUILD_PATH: 'wp-content/themes/wp-starter'
  YARN_BUILD_OPTS: ''

Custom Yarn Build with Options:

variables:
  YARN_BUILD_PATH: './src'
  YARN_BUILD_OPTS: '--watch'  # Run watch mode for development

Complete Pipeline Examples

NPM Build Example

variables:
  PROJECT_ID: 'p222-01'
  NPM_BUILD_PATH: './'
  NPM_NODE_IMAGE: 'node:20-alpine'
  NODE_BUILD_OPTS: ""

stages:
  - build
  - deploy

.npm-build:
  image: $NPM_NODE_IMAGE
  before_script:
    - cd $NPM_BUILD_PATH
    - rm -rf .git
  script:
    - npm install && npm run build $NODE_BUILD_OPTS
  cache:
    key: "$PROJECT_ID_node_modules"
    paths:
    - node_modules/
  artifacts:
    paths:
    - ./    
    expire_in: 1 hour

build:
  extends: .npm-build
  stage: build
  only:
    - main
    - develop

Yarn Build Example

variables:
  PROJECT_ID: 'p222-01'
  YARN_IMAGE: 'node:20-alpine'
  YARN_BUILD_PATH: 'wp-content/themes/wp-starter'
  YARN_BUILD_OPTS: ''

stages:
  - build
  - deploy

.yarn-build:
  image: $YARN_IMAGE
  before_script:
    - cd $YARN_BUILD_PATH
    - rm -rf .git/ 
  script:
    - yarn && yarn build $YARN_BUILD_OPTS
  cache:
    key: "$PROJECT_ID_node_modules"
    paths:
    - wp-content/themes/wp-starter/node_modules
  artifacts:
    paths:
    - ./    
    expire_in: 1 hour

build:
  extends: .yarn-build
  stage: build
  only:
    - main
    - develop

Environment-Specific Builds

Development Build:

variables:
  NODE_BUILD_OPTS: ""  # Empty for dev build
  YARN_BUILD_OPTS: ''  # Empty for dev build

Production Build:

variables:
  NODE_BUILD_OPTS: "--production"  # Production release
  YARN_BUILD_OPTS: '--production'  # Production release

Choosing Between npm and Yarn

Use .npm-build when:

• Your project uses npm as the package manager
• You have a standard Node.js application structure
• You want to use npm's native features

Use .yarn-build when:

• Your project uses Yarn as the package manager
• You're building WordPress themes (common use case)
• You need Yarn-specific features or performance

Prerequisites

• A package.json file must exist in the build path
• For npm builds: npm must be available (included in Node.js images)
• For Yarn builds: yarn must be available (included in Node.js images)
• A build script must be defined in package.json:

  {
    "scripts": {
      "build": "your-build-command"
    }
  }

Notes

• The .git/ directory is removed to reduce artifact size and avoid including unnecessary files
• The cache key uses $PROJECT_ID to ensure cache isolation between different projects
• Artifacts expire after 1 hour to prevent storage bloat
• For Yarn builds, the cache path in the example is hardcoded to wp-content/themes/wp-starter/node_modules - adjust if using a different path
• NODE_BUILD_OPTS and YARN_BUILD_OPTS can be used to pass additional options or run different npm scripts
• The jobs use Alpine-based Node.js images for smaller size and faster pulls
• Both jobs create artifacts containing the entire project directory, which can be used by subsequent deployment jobs