NodeJS Buildpack on App Platform

App Platform is a Platform-as-a-Service (PaaS) offering that allows developers to publish code directly to DigitalOcean servers without worrying about the underlying infrastructure.

How App Platform Builds Images

App Platform supports two ways to build an image for your app: Cloud Native Buildpacks and Dockerfiles.

When you give App Platform access to your code, it defaults to using a Dockerfile if one is present in the root of the directory or specified in the app spec. Otherwise, App Platform checks your code to determine what language or framework it uses. If it supports the language or framework, it chooses an appropriate resource type and uses the proper buildpack to build the app and deploy a container.

heroku-buildpack-nodejs is utilized as the buildpack for detecting and building your NodeJS applications.

NodeJS Applications using Buildpacks

App Platform looks for any of the following files to detect a NodeJS application:

• package.json
• package-lock.json
• yarn.lock

If both package-lock.json and yarn.lock exist, Yarn is preferred.

Current Buildpack Version and Supported Runtimes

Default Stack

App Platform uses version 0.3.6 of the Node.js Cloud Native Buildpack by default. The buildpack supports Node.js runtime versions up to 17.x. If no version is specified in your app, App Platform defaults to using version 16.x.

Ubuntu 22.04 stack (supporting Node.js 18+)

You can choose to build and deploy apps using the upcoming Ubuntu 22.04 stack by adding the specified app spec feature to the root of your app spec.

features:
    - buildpack-stack=ubuntu-22

Specifying Versions

Specify your desired Node version in the engines section of package.json.

    
        
            
{
  "engines": {
    "node": "16.x"
  }
}

        
    

You can customize the NPM version used by specifying the version in the engines section of your package.json:

    
        
            
{
  "engines": {
    "npm": "~1.0.20"
  }
}

        
    

You can customize the Yarn version used by specifying the version in the engines section of your package.json:

    
        
            
{
  "engines": {
    "yarn": "^0.14.0"
  }
}

        
    

Note

Long Term Support (LTS) versions of Node.js are not supported.

Specifying devDependencies

App Platform doesn’t install devDependencies by default during the build process. If your build command requires devDependencies, configure the following custom script. This script installs devDependencies, runs your build command, and removes any installed devDependencies before deployment.

Yarn

Package.json

    
        
            
"scripts": {
    "build:digitalocean": "yarn install --production=false && yarn run build && rm -rf node_modules && yarn install --production --frozen-lockfile",
    ... 
  } 

        
    

App Platform Build Command

    
        
            
yarn build:digitalocean 

        
    

NPM

Package.json

    
        
            
  "scripts": {
    "build:digitalocean": "npm install --production=false && npm run build && npm ci",
    ... 
  } 

        
    

App Platform Build Command

    
        
            
npm run build:digitalocean  

        
    

Caching

The buildpack automatically caches and re-uses the node_modules directory between builds. After the package manager’s install command is run (yarn install or npm install), the node_modules directory is stored in the build cache along with snapshot of the package manager’s lockfile. In subsequent builds, the cached node_modules directory will be restored only if the lockfile’s contents are identical to cached version. Otherwise, the cache will be discarded.

Clearing the Cache

If your app is failing to build and you suspect that the issue is related to node_modules caching, you can force clear the cache and start a new build. To do this in the control panel, navigate to your app, click the Actions menu, and then select Force Build and Deploy.

In the Force Build and Deploy window, select the Clear Build Cache option, and then click on the “Deploy” button. This clears the build cache and starts a new deployment.

Here’s an example with Node and Express that uses the PORT variable or 3000 for developing locally.

const express = require('express');
const app = express();

// get our port
const port = process.env.PORT || 3000;

// applicaton code goes here

// have node listen on our port
app.listen(port, () => console.log(`App listening on port ${port}!`));