> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # JavaScript/Node.js > Get started creating JavaScript apps with Node.js on Upsun Cloud. > [!TIP] > > You can now use composable image to install runtimes and tools in your application container. To find out more, see the [Composable image](https://developer.upsun.com/docs/configure-apps/app-reference/composable-image.md) topic. Node.js is a popular asynchronous JavaScript runtime. Deploy scalable Node.js apps of all sizes on Upsun Cloud. You can also develop a microservice architecture mixing JavaScript and other apps with [multi-app projects](https://developer.upsun.com/docs/configure-apps/multi-app). ## Active versions See [Image statuses](https://developer.upsun.com/docs/core-concepts/upgrade-runtimes-services.md#image-statuses) for what Active means. 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 other maintenance updates. By default, you get the latest available patches each time you deploy. If your project has a [maintenance window](https://developer.upsun.com/docs/core-concepts/build-deploy.md#maintenance-window) configured, Upsun Cloud applies patches only during that window. Upsun Cloud may still apply urgent or critical fixes outside of the maintenance window. * 26 * 24 * 22 ### Specify the language To use Node.js, specify `nodejs` as your [app’s type](https://developer.upsun.com/docs/configure-apps/app-reference/single-runtime-image.md#type): applications: \# The app's name, which must be unique within the project. \: type: 'nodejs:\' For example: applications: \# The app's name, which must be unique within the project. myapp: type: 'nodejs:\{\{version:nodejs:latest}}' To use a specific version in a container with a different language, [use a version manager](https://developer.upsun.com/docs/languages/nodejs/node-version.md). ## Sunset versions The following versions are still available in your projects, including code pushes, but new projects can't use them. These versions are decommissioned 180 calendar days after entering Sunset. The exact decommission date is shown on your project's Overview page and on the relevant activity in the **Activity** panel. See [Image statuses](https://developer.upsun.com/docs/core-concepts/upgrade-runtimes-services.md#image-statuses) for what each status means. * 20 * 18 * 16 * 15 * 14 * 12 * 10 * 8.9 * 8 * 6.10 * 6.9 * 6.8 * 6.6 * 6.3 * 6.2 * 6 * 4.7 * 4.6 * 4.5 * 4.4 * 4.3 * 4.2 * 4 * 0.12 ## Decommissioned versions The following versions have been decommissioned and are no longer available. See [Image statuses](https://developer.upsun.com/docs/core-concepts/upgrade-runtimes-services.md#image-statuses) for what each status means. If your project uses a decommissioned version, you must update to an [active version](#active-versions). *No decommissioned versions.* ## Usage example To use JavaScript with Node.js on Upsun Cloud, configure your [app configuration](https://developer.upsun.com/docs/configure-apps) (a complete example is included at the end). ### 1. Specify the version Choose a version from the [list of active versions](#active-versions) and add it to your app configuration: applications: \# The app's name, which must be unique within the project. myapp: type: 'nodejs:\{\{version:nodejs:latest}}' ### 2. Specify any global dependencies Add the following to your app configuration: applications: \# The app's name, which must be unique within the project. myapp: type: 'nodejs:\{\{version:nodejs:latest}}' dependencies: nodejs: sharp: "\*" These are now available as commands, the same as installing with `npm install -g`. ### 3. Build your app Include any commands needed to build and setup your app in the `hooks`, as in the following example: applications: \# The app's name, which must be unique within the project. myapp: type: 'nodejs:\{\{version:nodejs:latest}}' dependencies: nodejs: sharp: "\*" hooks: build: | npm run setup-assets npm run build ### 4. Start your app Specify a command to start serving your app (it must be a process running in the foreground): applications: \# The app's name, which must be unique within the project. myapp: type: 'nodejs:\{\{version:nodejs:latest}}' dependencies: nodejs: sharp: "\*" hooks: build: | npm run setup-assets npm run build web: commands: start: node index.js ### 5. Listen on the right port Make sure your Node.js application is configured to listen over the port given by the environment. ```js theme={null} // 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 Cloud configuration server.listen(PORT, () => { console.log(`Server is listening on port: ${PORT}`); }); ``` ### Complete example A complete basic app configuration looks like the following: applications: \# The app's name, which must be unique within the project. 'node-app': type: 'nodejs:\{\{version:nodejs:latest}}' dependencies: nodejs: sharp: "\*" hooks: build: | npm run setup-assets npm run build web: commands: start: "node index.js" ## Dependencies By default, Upsun Cloud 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](https://developer.upsun.com/docs/configure-apps/app-reference/single-runtime-image.md#build): ```bash theme={null} npm prune --userconfig .npmrc && npm install --userconfig .npmrc ``` This means you can specify configuration in a `.npmrc` file in [your app root](https://developer.upsun.com/docs/configure-apps/app-reference/single-runtime-image.md#root-directory). ### Use Yarn as a package manager To switch to Yarn to manage dependencies, follow these steps: 1. Turn off the default use of npm: applications: \# The app's name, which must be unique within the project. myapp: type: 'nodejs:\{\{version:nodejs:latest}}' build: flavor: none 2. Specify the version of Yarn you want: ```json package.json theme={null} { ... "packageManager": "yarn@3.2.1" } ``` What you do next depends on the versions of Yarn and Node.js you want. > [tab] Yarn 3.x and Node.js 16+ > > 3. Use Corepack to run Yarn in your build hook: > > applications: > \# The name of the app container. Must be unique within a project. > myapp: > \# The location of the application's code. > type: 'nodejs:\{\{version:nodejs:latest}}' > hooks: > build: | > corepack yarn install > [tab] Yarn 3.x and Node.js \< 16 > > 3. Enable Corepack (which is opt-in): > > applications: > \# The name of the app container. Must be unique within a project. > myapp: > \# The location of the application's code. > type: 'nodejs:\{\{version:nodejs:latest}}' > dependencies: > nodejs: > corepack: "\*" > > 4. Use Corepack to run Yarn in your build hook: > > applications: > \# The name of the app container. Must be unique within a project. > myapp: > \# The location of the application's code. > type: 'nodejs:\{\{version:nodejs:latest}}' > hooks: > build: | > corepack yarn install > [tab] Yarn \< 3 > > 3. Add Yarn as a global dependency: > > applications: > \# The name of the app container. Must be unique within a project. > myapp: > \# The location of the application's code. > type: 'nodejs:\{\{version:nodejs:latest}}' > dependencies: > nodejs: > yarn: "1.22.19" > > 4. Install dependencies in the `build` hook: > > applications: > \# The name of the app container. Must be unique within a project. > myapp: > \# The location of the application's code. > type: 'nodejs:\{\{version:nodejs:latest}}' > hooks: > build: | > yarn --frozen-lockfile ### Use Bun as a package manager > [!NOTE] > > [Bun is available as a runtime and package manager](https://developer.upsun.com/posts/releases/bun-support-is-here) for Node.js **version 20 or above**. Choose one of the [active versions](#active-versions) rather than the minimum supported version. To switch to Bun to manage dependencies, use the following configuration: ```yaml .upsun/config.yaml theme={null} applications: # The name of your app. myapp: # Choose an active Node.js version. type: 'nodejs:26' # 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 You can even [use Bun as a runtime](https://developer.upsun.com/posts/releases/bun-support-is-here) by adjusting the `start` command as follows: ```yaml .upsun/config.yaml theme={null} applications: # The name of your app. myapp: # Choose an active Node.js version. type: 'nodejs:26' # 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 You can access service credentials to connect to [managed services](https://developer.upsun.com/docs/add-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. * [ClickHouse](https://developer.upsun.com/docs/add-services/clickhouse.md#usage-example) * [Elasticsearch](https://developer.upsun.com/docs/add-services/elasticsearch.md#usage-example) * [Gotenberg](https://developer.upsun.com/docs/add-services/gotenberg.md#usage-example) * [Headless Chrome](https://developer.upsun.com/docs/add-services/headless-chrome.md#usage-example) * [InfluxDB](https://developer.upsun.com/docs/add-services/influxdb.md#usage-example) * [Kafka](https://developer.upsun.com/docs/add-services/kafka.md#usage-example) * [MariaDB/MySQL](https://developer.upsun.com/docs/add-services/mysql#usage-example) * [Memcached](https://developer.upsun.com/docs/add-services/memcached.md#usage-example) * [mercure](https://developer.upsun.com/docs/add-services/mercure.md#usage-example) * [mongodb](https://developer.upsun.com/docs/add-services/mongodb.md#usage-example) * [Network Storage](https://developer.upsun.com/docs/add-services/network-storage.md#usage-example) * [OpenSearch](https://developer.upsun.com/docs/add-services/opensearch.md#usage-example) * [PostgreSQL](https://developer.upsun.com/docs/add-services/postgresql#usage-example) * [RabbitMQ](https://developer.upsun.com/docs/add-services/rabbitmq.md#usage-example) * [Redis](https://developer.upsun.com/docs/add-services/redis.md#usage-example) * [Solr](https://developer.upsun.com/docs/add-services/solr.md#usage-example) * [Valkey](https://developer.upsun.com/docs/add-services/valkey.md#usage-example) * [Varnish](https://developer.upsun.com/docs/add-services/varnish.md#usage-example) * [Vault KMS](https://developer.upsun.com/docs/add-services/vault.md#usage-example) * [Chroma](https://developer.upsun.com/tutorials/self-hosted/chroma.md#3-use-the-relationship-in-your-application) * [Qdrant](https://developer.upsun.com/tutorials/self-hosted/qdrant.md#4-use-the-relationship-in-your-application) > [!NOTE] > > To deploy a Node.js project, create a new project from the > [Upsun Console](https://console.upsun.com/projects/create-project) > and select a template, or push your existing code. ## Frameworks All major Javascript/Node.js web frameworks can be deployed on Upsun Cloud. See dedicated guides for deploying and working with them: * [Express](https://developer.upsun.com/docs/get-started/stacks/express) * [Next.js](https://developer.upsun.com/docs/get-started/stacks/nextjs.md) * [Strapi](https://developer.upsun.com/docs/get-started/stacks/strapi) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.