---
title: "Getting started with Node.js applications and environments"
date: "2024-02-14T06:18:38+00:00"
summary: "Learn to manage Node.js apps on Cloud Platform: create environments, configure versions, and develop with pipelines for seamless deployment."
image:
type: "page"
url: "/acquia-cloud-platform/add-ons/node-js/getting-started-nodejs-applications-and-environments"
id: "8caee5bb-8988-44f8-a074-22c24d51c58f"
---

If you are already familiar with the Cloud Platform user interface, getting started with a Node.js application is similar to the other applications you have already created in Cloud Platform.

For your reference, here is how Node.js applications and environments are managed, and how you develop your code in them, which may be slightly different than your previously created applications and environments.

Managing applications
---------------------

Many of the basic application management functions are the same for Cloud Platform-hosted Drupal applications. These functions include:

*   Modifying views of applications
*   Adding applications
*   Renaming applications

For a full explanation of each of these functions, see [Managing applications with the Cloud Platform interface](/acquia-cloud-platform/manage-apps/cloud-platform-interface).

Managing environments
---------------------

The Cloud Platform implementation of Node.js uses separate environments to help you maintain a clear and orderly workflow as you develop, test, and publish your applications. An application is deployed on each of its environments, but each environment may be in a different state—possibly with a build artifact deployed. Each environment has a URL at which its application can be accessed, but only the production environment’s URL is designed to be visible to the application’s users (website visitors).

Acquia Node.js applications start with one production (**Prod**) environment, and one development (**Dev**) environments. See [Resources and limitations for Node.js environments](/acquia-cloud-platform/add-ons/node-js/resources) for infrastructure details.

*   _Development environments_: Shared between customers
*   _Production environments_: Dedicated to a single customer

Determining Node.js version on an environment
---------------------------------------------

The **Overview** page for an environment displays the Node.js version installed on an environment. To check the version installed on an environment, complete the following steps:

1.  [Sign in to the Cloud Platform user interface](https://cloud.acquia.com).
2.  In the [breadcrumbs menu](/acquia-cloud-platform/cloud-ui#cloud-breadcrumbs), click the triangle and select your organization, application, and environment to display the environment’s **Overview** page.
3.  On the environment’s **Overview** page, scroll down to the **Information** section.

The Cloud Platform user interface displays the Node.js version at the bottom of the **Information** section as shown in the following example:

![Environment details in Cloud UI including Node.js version](https://acquia.widen.net/content/e32b00f7-972d-4e53-be28-e114cd16ff21/web/cloud-platform_checking-node-js-version.png?w=720&itok=j9R6VoyZ)

Configuring Node.js version on an environment
---------------------------------------------

1.  [Sign in to the Cloud Platform user interface](https://cloud.acquia.com).
2.  Select your application and environment.
3.  Click the **Configure** icon. Cloud Platform will display the **Configuration** panel.
4.  In the **Configuration** panel, select the Node version you want to use for the environment:
    
    ![The Node.js version configuration in the Cloud Platform user interface](https://acquia.widen.net/content/a747abf0-f044-4b78-a9d8-b7961f7fe59f/web/cloud-platform_selecting-node-js-version.png?w=480&itok=howUBJK6)
    
5.  Click **Save**.

Developing your application
---------------------------

Development with Node.js on Cloud Platform requires you create [pipelines](/acquia-cloud-platform/features/pipelines) for your code.

Based on the normal Pipelines workflow, after [connecting your application to a repository](/acquia-cloud-platform/pipelines "Pipelines"), you must [create your build definition file](/acquia-cloud-platform/features/pipelines/yaml).

The Cloud Platform uses the conventional `npm start` command to start your Node.js application. Ensure that you have a snippet similar to the following in your application’s `package.json` file:

    "scripts": {
        "start": "node index.js"
    }

Update your [Node.js application](https://docs.acquia.com/acquia-cloud-platform/add-ons/node-js "https://docs.acquia.com/acquia-cloud-platform/add-ons/node-js") within the error-handling code so that the code can capture error information and display logs and error messages in log streaming. Node.js applications that capture logs through `console.log()` and error messages through `console.error()` can provide effective monitoring and troubleshooting.

Node.js applications on Cloud Platform have a `docroot` directory. This directory isn’t used by Node.js applications, and can be safely added to your `.gitignore` file.

For a detailed tutorial about local Drupal and Node.js setup, see [Node.js with Decoupled Drupal on Cloud Platform](/acquia-cloud-platform/help/94596-nodejs-decoupled-drupal-cloud-platform "Node.js with Decoupled Drupal on Cloud Platform").

### Pipelines client commands

The Pipelines client for Cloud Platform includes [commands that are specific to Node.js applications](/node/56264#pipelines-start-command) and [commands available for your YAML file](/acquia-cloud-platform/commands-available-pipelines "Commands available in Pipelines"). For a listing of commands in the CLI client, see [Using the Cloud Platform Pipelines client](/acquia-cloud-platform/features/pipelines/cli/commands).

### Creating a Pipelines artifact for a Node.js application

The following is an example script for building a Pipelines artifact with your Node.js application:

    # For more acquia-pipelines.yaml pipelines examples, see
    # https://docs.acquia.com/pipelines/yaml/examples/
    version: 1.2.0
    variables:
      global:
        # All of these settings are only needed if you want to use the custom deployment script.
        # Use the name of the environment where the automatic deployment should happen.
        # The deployment script will deploy all the new commits to this given environment.
        TARGET_ENV_NAME: 'stage'
        ARTIFACT_NAME: '${PIPELINE_VCS_PATH}@${PIPELINE_GIT_HEAD_REF}'
        PIPELINE_JOB_URL: 'https://cloud.acquia.com/app/develop/applications/${PIPELINE_APPLICATION_ID}/pipelines/jobs/${PIPELINE_JOB_ID}'
        PIPELINE_ARTIFACT_START_LOG: '/tmp/pipelines-artifact-start-${PIPELINE_JOB_ID}.log'
        # Put your Cloud API credentials here.
        CLOUD_API_KEY:
          secure:
        CLOUD_API_SECRET:
          secure:
    events:
      build:
        steps:
          - build:
              script:
                - nvm use <node_version>
                # <node_version> must be the version of node that you want to target. For example, to target version 22: nvm use 22.
                - npm install --production
                # The next line is only needed when the built code is not part of the commits, otherwise it can be removed.
                - npm run build
                # Here you can include all the needed scripts for the build to be production ready. Only needed if the built code is not part of the commit.
          - upload-artifact:
              script:
                - pipelines-artifact start
                - pipelines-artifact upload $SOURCE_DIR
      fail-on-build:
        steps:
          - fail:
              script:
                - pipelines-artifact fail
    post-deploy:
      steps:
        - deploy:
            script:
              - 'chmod +x ./deploy-artifact.sh'
              - ./deploy-artifact.sh
              - 'echo Artifact $ARTIFACT_NAME is deployed to $TARGET_ENV_NAME environment'
              - 'echo Check task log for more details at $PIPELINE_JOB_URL'

For other example scripts for pipelines, see [Example Pipelines build definition files](/acquia-cloud-platform/features/pipelines/yaml/examples).

Configuring Puppeteer
---------------------

To use the Puppeteer package, add a `.puppeteerrc.cjs` file in the application root directory with the following content:

    const {join} = require('path');
    
    /**
    * @type {import("puppeteer").Configuration}
    */
    module.exports = {
    // Changes the cache location for Puppeteer.
    cacheDirectory: join(__dirname, 'browsers', 'puppeteer'),
    };

You must replace `__dirname` with the directory in which you want to install Chrome. Puppeteer uses the specified directory to install and use the Chrome package. Therefore, you do not need the globally installed Chrome package.

For more information, see [Puppeteer configuration](https://pptr.dev/#configuration).