Migrating to the Node.js CF-compatible CNB

This topic describes how to prepare your Node or JavaScript apps to use the Node.js CF-compatible Cloud Native Buildpack (CNB) instead of the Cloud Foundry-only Node.js buildpack.

Install Processes:

With the new Node.js Cloud Native Buildpack, the installation commands that we choose to build an apps node_modules have changed as follows:

  • We assume that all of the following are updated and in agreement before an app is cf pushed
    • package.json
    • package-lock.json (optional)
    • node_modules (optional)
    • npm-cache (optional)
    • yarn.lock (optional)

As a result we require that apps that contain node_modules or npm-cache must contain all of the dependencies required for a successful npm or yarn install.

For additional details on how the installation process is chosen of this buildpack see Node.js Cloud Native Buildpack installation process.

Note: Due to the modular nature of CNB, the new Node.js buildpack does not currently include certain external integration helpers, such as those for APM agents.

Buildpack Ordering

The compatibility layer generated by cnb2cf imposes some additional constraints on multi-buildpacks builds. If a CF-compatible CNB is used during multi-buildpack builds. All subsequent buildpacks must also be CF-compatible CNB. In the example cf push below all buildpacks between compat-cn_buildpack_1 and compat-cn_buildpack_n must be a CF-compatible CNB.

  cf push -b bpack_1 -b bpack_2 -b compat-cn_bpack_1 ... -b compat-cn_bpack_n

Migration Guide:

Vendored Apps with NPM

Vendored app now must vendor ALL dependencies listed in package.json:

  • Using node_modules: Validate that all modules are vendored into the node_modules by the following:

         npm list
    

    If there are missing dependencies listed, this app will fail to build. Re-vendor by running the following in the root of your app:

          npm install <your preferred flags>
    
  • Using npm-cache: This is a newly added

        npm ci --cache npm-cache
    

Online Apps with NPM

To deploy online apps on NPM with the Node.js CNB:

  • Remove partially vendored components: Online apps must not contain either a node_modules or npm-cache directory in the root directory of the app. Remove these before running cf-push.

  • Make sure all dependencies are met: Apps must contain all required dependencies after an install. If you provide a package.json and all modules cannot be installed the subsequent npm list check will cause the build to fail.

Yarn Apps

To deploy online apps on NPM with the Node.js CNB:

  • yarn.lock must agree with package.json

Yarn apps will have dependencies installed from the yarn.lock file. This differs from the behavior of the Node.js Buildpack which installs dependencies from the package.json file.

To avoid discrepancies in installed packages, generate an up to date yarn.lock file before running a cf push using:

yarn install <your preferred flags>