npm Operations

The npm module manages Node.js packages using npm (Node Package Manager).

Functions

packages

Install, remove, or update npm packages.

from pyinfra.operations import npm

npm.packages(
    name="Install Node.js packages",
    packages=["express", "lodash"],
)

str | list[str]

List of packages to ensure.

bool

default:true

Whether the packages should be present.

bool

default:false

Whether to upgrade packages without a specified version.

str

Directory to manage packages for. Defaults to global installation.

Package versions can be pinned like npm: <pkg>@<version>

Examples

from pyinfra.operations import npm

# Install packages globally
npm.packages(
    name="Install global npm packages",
    packages=["typescript", "nodemon"],
)

from pyinfra.operations import npm

# Install packages in a project directory
npm.packages(
    name="Install project dependencies",
    packages=["express", "mongoose", "dotenv"],
    directory="/var/www/myapp",
)

from pyinfra.operations import npm

# Install specific versions
npm.packages(
    name="Install specific versions",
    packages=[
        "express@4.18.2",
        "react@18.2.0",
        "typescript@5.0.4",
    ],
    directory="/app",
)

from pyinfra.operations import npm

# Always install latest versions
npm.packages(
    name="Install latest packages",
    packages=["express", "lodash"],
    latest=True,
    directory="/app",
)

Common Use Cases

Express.js Application Setup

from pyinfra.operations import npm

npm.packages(
    name="Install Express.js dependencies",
    packages=[
        "express@4.18.2",
        "body-parser",
        "cors",
        "dotenv",
        "mongoose",
    ],
    directory="/var/www/api",
)

React Application

from pyinfra.operations import npm

npm.packages(
    name="Install React dependencies",
    packages=[
        "react@18.2.0",
        "react-dom@18.2.0",
        "react-router-dom",
        "axios",
    ],
    directory="/var/www/frontend",
)

Global Development Tools

from pyinfra.operations import npm

npm.packages(
    name="Install global development tools",
    packages=[
        "typescript",
        "nodemon",
        "pm2",
        "eslint",
        "prettier",
    ],
)

Install from package.json

from pyinfra.operations import server

# Install all dependencies from package.json
server.shell(
    name="Install npm dependencies",
    commands=["cd /app && npm install"],
)

Build Tools

from pyinfra.operations import npm

npm.packages(
    name="Install build tools",
    packages=[
        "webpack",
        "webpack-cli",
        "babel-loader",
        "@babel/core",
        "@babel/preset-env",
    ],
    directory="/var/www/myapp",
)

Testing Framework

from pyinfra.operations import npm

npm.packages(
    name="Install testing tools",
    packages=[
        "jest",
        "@testing-library/react",
        "@testing-library/jest-dom",
        "supertest",
    ],
    directory="/app",
)

npm-Specific Tips

Global vs Local Packages

Global packages (no directory parameter):

Installed system-wide
Typically CLI tools
Use npm install -g

Local packages (with directory parameter):

Installed in project’s node_modules
Project dependencies
Use npm install in directory

from pyinfra.operations import npm

# Global: CLI tools
npm.packages(
    name="Install global tools",
    packages=["typescript", "nodemon"],
)

# Local: Project dependencies
npm.packages(
    name="Install project dependencies",
    packages=["express", "mongoose"],
    directory="/app",
)

Using package.json

For full project setups, use package.json:

from pyinfra.operations import files, server

# Upload package.json
files.put(
    name="Upload package.json",
    src="local/package.json",
    dest="/app/package.json",
)

# Install all dependencies
server.shell(
    name="Install npm dependencies",
    commands=["cd /app && npm install"],
)

# For production (skip devDependencies)
server.shell(
    name="Install production dependencies",
    commands=["cd /app && npm install --production"],
)

Update Packages

Update packages to latest versions:

from pyinfra.operations import npm

# Update specific packages
npm.packages(
    name="Update packages",
    packages=["express", "lodash"],
    latest=True,
    directory="/app",
)

# Or use npm update directly
from pyinfra.operations import server

server.shell(
    name="Update all packages",
    commands=["cd /app && npm update"],
)

Scoped Packages

Install scoped packages (organization packages):

from pyinfra.operations import npm

npm.packages(
    name="Install scoped packages",
    packages=[
        "@babel/core",
        "@testing-library/react",
        "@types/node",
    ],
    directory="/app",
)

Clean Install

Perform a clean install (removes node_modules):

from pyinfra.operations import server

server.shell(
    name="Clean install dependencies",
    commands=[
        "cd /app",
        "rm -rf node_modules",
        "npm ci",  # Clean install from package-lock.json
    ],
)

Private Registries

Install from private npm registries:

from pyinfra.operations import server

# Set registry
server.shell(
    name="Configure private registry",
    commands=[
        "npm config set registry https://registry.company.com",
    ],
)

# Or use .npmrc file
from pyinfra.operations import files

files.put(
    name="Upload .npmrc",
    src="local/.npmrc",
    dest="/app/.npmrc",
)

Best Practices

Use package-lock.json

Always commit and deploy package-lock.json for reproducible builds:

from pyinfra.operations import files, server

files.put(
    name="Upload package files",
    src="local/package.json",
    dest="/app/package.json",
)

files.put(
    name="Upload lock file",
    src="local/package-lock.json",
    dest="/app/package-lock.json",
)

server.shell(
    name="Install exact versions",
    commands=["cd /app && npm ci"],
)

Separate Dev and Production

from pyinfra.operations import server

# Production: skip devDependencies
server.shell(
    name="Install production dependencies",
    commands=["cd /app && npm install --production"],
)

# Development: install all
server.shell(
    name="Install all dependencies",
    commands=["cd /app && npm install"],
)

Pin Major Versions

from pyinfra.operations import npm

# Pin major versions for stability
npm.packages(
    name="Install with version constraints",
    packages=[
        "express@4.18.2",    # Exact version
        "lodash@^4.17.21",    # Compatible version
    ],
    directory="/app",
)

Important Notes

When no directory is specified, packages are installed globally using npm install -g.

Global npm installations may require sudo/administrator privileges depending on Node.js installation.

For production deployments, use npm ci instead of npm install for faster, more reliable builds.

Overview

Package Managers

Language Packages

Service Management

System Operations

Containers

Databases

Version Control

Security

Functions

packages

Examples

Common Use Cases

Express.js Application Setup

React Application

Global Development Tools

Install from package.json

Build Tools

Testing Framework

npm-Specific Tips

Best Practices

Important Notes

​Functions

​packages

​Examples

​Common Use Cases

​Express.js Application Setup

​React Application

​Global Development Tools

​Install from package.json

​Build Tools

​Testing Framework

​npm-Specific Tips

​Best Practices

​Important Notes

Functions

packages

Examples

Common Use Cases

Express.js Application Setup

React Application

Global Development Tools

Install from package.json

Build Tools

Testing Framework

npm-Specific Tips

Best Practices

Important Notes