Upsun User Documentation

JavaScript/Node.js

Sign up

Get your free trial by clicking the link below.

Get your Upsun free trial

Node.js is a popular asynchronous JavaScript runtime. Deploy scalable Node.js apps of all sizes on Upsun. You can also develop a microservice architecture mixing JavaScript and other apps with multi-app projects.

Supported versions Anchor to this heading

You can select the major version. But the latest compatible minor version is applied automatically and can’t be overridden.

Patch versions are applied periodically for bug fixes and the like. When you deploy your app, you always get the latest available patches.

  • 20
  • 18
  • 16

Specify the language Anchor to this heading

To use Node.js, specify nodejs as your app’s type:

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    <APP_NAME>:
        type: 'nodejs:<VERSION_NUMBER>'

For example:

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'nodejs:20'

To use a specific version in a container with a different language, use a version manager.

Deprecated versions Anchor to this heading

The following versions are deprecated. They’re available, but they aren’t receiving security updates from upstream and aren’t guaranteed to work. They’ll be removed in the future, so migrate to one of the supported versions.

  • 14
  • 12
  • 10
  • 8
  • 6
  • 4.8
  • 4.7
  • 0.12

Usage example Anchor to this heading

To use JavaScript with Node.js on Upsun, configure your app configuration (a complete example is included at the end).

1. Specify the version Anchor to this heading

Choose a version from the list of supported versions and add it to your app configuration:

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'nodejs:20'

2. Specify any global dependencies Anchor to this heading

Add the following to your app configuration:

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'nodejs:20'
        dependencies:
            nodejs:
                sharp: "*"

These are now available as commands, the same as installing with npm install -g.

3. Build your app Anchor to this heading

Include any commands needed to build and setup your app in the hooks, as in the following example:

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'nodejs:20'
        dependencies:
            nodejs:
                sharp: "*"
        hooks:
            build: |
                npm run setup-assets
                npm run build                

4. Start your app Anchor to this heading

Specify a command to start serving your app (it must be a process running in the foreground):

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'nodejs:20'
        dependencies:
            nodejs:
                sharp: "*"
        hooks:
            build: |
                npm run setup-assets
                npm run build                
        web:
            commands:
                start: node index.js

5. Listen on the right port Anchor to this heading

Make sure your Node.js application is configured to listen over the port given by the environment.

// Load the http module to create an http server.
const http = require('http');
const PORT = process.env.PORT || 8888;

const server = http.createServer(function (request, response) {
    response.writeHead(200, {"Content-Type": "application/json"});
    response.end("Hello world!");
});

// Listen on the port from the Upsun configuration
server.listen(PORT, () => {
  console.log(`Server is listening on port: ${PORT}`);
});

Complete example Anchor to this heading

A complete basic app configuration looks like the following:

.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    'node-app':
        type: 'nodejs:20'
        dependencies:
            nodejs:
                sharp: "*"
        hooks:
            build: |
                npm run setup-assets
                npm run build                
        web:
            commands:
                start: "node index.js"

Dependencies Anchor to this heading

By default, Upsun assumes you’re using npm as a package manager. If your code has a package.json, the following command is run as part of the default build flavor:

npm prune --userconfig .npmrc && npm install --userconfig .npmrc

This means you can specify configuration in a .npmrc file in your app root.

Use Yarn as a package manager Anchor to this heading

To switch to Yarn to manage dependencies, follow these steps:

  1. Turn off the default use of npm:
.upsun/config.yaml
applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'nodejs:20'
        build:
            flavor: none
  1. Specify the version of Yarn you want:

    package.json
    {
      ...
      "packageManager": "yarn@3.2.1"
    }

What you do next depends on the versions of Yarn and Node.js you want.

  1. Use Corepack to run Yarn in your build hook:
.upsun/config.yaml
applications:
    # The name of the app container. Must be unique within a project.
    myapp:
        # The location of the application's code.
        source:
            root: "/"
       type: 'nodejs:20'
        hooks:
            build: |
                corepack yarn install                
  1. Enable Corepack (which is opt-in):
.upsun/config.yaml
applications:
    # The name of the app container. Must be unique within a project.
    myapp:
        # The location of the application's code.
        source:
            root: "/"
       type: 'nodejs:20'
        dependencies:
            nodejs:
                corepack: "*"
  1. Use Corepack to run Yarn in your build hook:
.upsun/config.yaml
applications:
    # The name of the app container. Must be unique within a project.
    myapp:
        # The location of the application's code.
        source:
            root: "/"
       type: 'nodejs:20'
        hooks:
            build: |
                corepack yarn install                
  1. Add Yarn as a global dependency:
.upsun/config.yaml
applications:
    # The name of the app container. Must be unique within a project.
    myapp:
        # The location of the application's code.
        source:
            root: "/"
       type: 'nodejs:20'
        dependencies:
            nodejs:
                yarn: "1.22.19"
  1. Install dependencies in the build hook:
.upsun/config.yaml
applications:
    # The name of the app container. Must be unique within a project.
    myapp:
        # The location of the application's code.
        source:
            root: "/"
       type: 'nodejs:20'
        hooks:
            build: |
                yarn --frozen-lockfile                

Use Bun as a package manager Anchor to this heading

Availability

Bun is available as a runtime and package manager for Node.js versions 20 or above.

To switch to Bun to manage dependencies, use the following configuration:

.upsun/config.yaml
applications:
    # The name of your app.
    myapp:
    # Choose Node.js version 20 or above.
        type: 'nodejs:20'
        # Override the default Node.js build flavor.
        build:
    	    flavor: none
        # Use Bun to install the dependencies.
        hooks:
    	    build: bun install

Use Bun as a runtime Anchor to this heading

You can even use Bun as a runtime by adjusting the start command as follows:

.upsun/config.yaml
applications:
    # The name of your app.
    myapp:
    # Choose Node.js version 20 or above.
        type: 'nodejs:20'
        # Override the default Node.js build flavor.
        build:
    	    flavor: none
        # Use Bun to install the dependencies.
        hooks:
    	    build: bun install
        # In the start command replace node with Bun.
        web:
    	    commands:
    		    start: 'bun app.js'

Connecting to services Anchor to this heading

You can access service credentials to connect to managed services from environment variables present in the application container. Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

Frameworks Anchor to this heading

All major Javascript/Node.js web frameworks can be deployed on Upsun. See dedicated guides for deploying and working with them:

Is this page helpful?