Runtime Environment

How Sherpa.sh handles OS-level dependencies and runtime environments for your applications.

Dependency Management

Automatic Dependency Installation When you deploy a project, Sherpa.sh automatically detects your package manager and installs all dependencies listed in your package.json, yarn.lock, pnpm-lock.yaml, bun or other lock files. This ensures all Node modules and JavaScript dependencies are available during build and runtime.

Custom Install Commands Configure custom installation commands in your project settings for specialized dependency requirements or multi-step installation processes.

OS-Level Dependencies

Build Infrastructure Sherpa.sh runs builds and deployments within standardized Ubuntu containers that include essential system libraries and tools required for most Node.js and web projects.

Native Module Support Node modules requiring compilation or native binaries (such as sharp, sqlite3, canvas) are automatically built during deployment. Sherpa.sh ensures these binaries are compiled against the same runtime environment where your application executes, eliminating common deployment issues.

System Libraries

Pre-installed Libraries The Sherpa.sh runtime includes commonly-used system libraries needed by popular frameworks and tools:

Core Development Tools

# Build essentials
build-essential, gcc, g++, make, cmake
autoconf, automake, libtool, nasm, pkg-config

# Version control and utilities
git, curl, wget, bash, unzip

Image Processing Libraries

# Image manipulation (Sharp, Canvas support)
libvips-dev, libvips-tools
libpng-dev, libjpeg-dev, libwebp-dev
libgif-dev, libtiff-dev, librsvg2-dev
libcairo2-dev, libpango1.0-dev, libpixman-1-dev

Database Client Libraries

# Database connectivity
libpq-dev              # PostgreSQL
libmysqlclient-dev      # MySQL
libsqlite3-dev          # SQLite

Browser Testing Support

# Headless browser libraries (Puppeteer, Playwright)
libgtk-3-dev, libgbm-dev, libxrandr2
libxcomposite1, libxcursor1, libxdamage1
libnss3, libcups2, libdrm2

Security and Compression

# SSL/TLS and compression
libssl-dev, libffi-dev
zlib1g-dev, libbz2-dev

Runtime Environment Characteristics

Python Support Python 3 is included with development headers for native module compilation:

python3, python3-pip, python3-dev
python-is-python3  # python command points to python3

Consistent Build and Runtime Applications build and execute in identical container environments, ensuring binary compatibility and reducing runtime errors from missing libraries or version mismatches.

Limitations and Workarounds

System Library Constraints The runtime environment uses a fixed set of system libraries. If your application requires specialized system packages not included in the base image, consider these alternatives:

1. Find npm alternatives: Look for JavaScript implementations of native tools

2. Use included libraries: Leverage the comprehensive set of pre-installed packages

3. Custom functions: Implement workarounds using available system tools

4. Reach out to support: Head into discord.sherpa.sh and request a new package be added to the runtime.

Supported Use Cases The runtime environment supports most common development scenarios:

• Image processing and manipulation

• Database connectivity (PostgreSQL, MySQL, SQLite)

• Headless browser automation

• Cryptographic operations

• File compression and archives

Best Practices

Dependency Optimization

• Use lock files (package-lock.json, yarn.lock) for reproducible builds

• Specify exact versions for critical dependencies

• Test locally with similar Node.js versions

Native Module Compatibility

• Verify native modules support Linux x64 architecture

• Use modules with prebuilt binaries when possible

• Test deployment with native dependencies in staging environment

Performance Considerations

• Minimize dependency installation time with .npmrc configuration

• Use npm ci for faster, reliable installs in production

• Cache dependencies when possible using build optimization settings

The Sherpa.sh runtime environment provides a robust, predictable foundation for deploying Node.js applications with complex dependencies while maintaining security and performance standards.