> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript in Gitpod

Gitpod comes with great built-in support for JavaScript, TypeScript, and tools like Node.js, npm, pnpm & yarn pre-installed with [Gitpod workspace image](/classic/user/configure/workspaces/workspace-image). This guide walks you through how to fully configure a JavaScript application using Gitpod.

## Prerequisites

This guide assumes familiarity with:

[Docker](https://docs.docker.com/), [YAML](https://yaml.org/spec/1.1/), [Linux](https://www.linux.org/), [Bash](https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html) and Linux [environment variables](https://wiki.archlinux.org/title/environment_variables).

## Getting started / Quick Start

<iframe width="560" height="315" src="https://www.youtube.com/embed/ij1msCffQZA" title="JavaScript in Gitpod" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen className="rounded-xl" />

To see a full working Node/TypeScript application, take a look at [gitpod-samples/template-typescript-node](https://github.com/gitpod-samples/template-typescript-node). To update an existing JavaScript application, follow the steps below in this guide.

<a href="https://gitpod.io/#https://github.com/gitpod-samples/template-typescript-node">
  <img src="https://gitpod.io/button/open-in-gitpod.svg" alt="Push" className="align-center" />
</a>

## Installing dependencies

### The default base image

The default Gitpod workspace image default is [workspace-full](https://github.com/gitpod-io/workspace-images) based on [Ubuntu](https://ubuntu.com/).

Along with other languages and tools, this base image includes:

* [Node.js](https://nodejs.org/en/) `v18.16.0` (`node -v`)
* [Node Package Manager - npm](https://www.npmjs.com/) `9.5.1` (`npm -v`)
* [Node Version Manager - nvm](https://nvm.sh) `0.39.0` (`nvm -v`)

<Note> We discuss how to set up a [custom base image](/classic/user/introduction/languages/javascript#setting-up-a-custom-dockerfile) later in the guide.</Note>

### Updating Node Versions

Gitpod comes with the latest stable Node.js version pre-installed but let's say your project uses a different version of `node` (say `14.8.0` for example), well the good news is that Gitpod also comes with `nvm` (a tool used to manage multiple active Node.js versions) installed. To install and configure the desired version of node: `nvm install 14.8.0` and `nvm use 14.8.0` (you can also use `nvm alias default 14.8.0` to set the default version of node) or you can setup [custom Dockerfile](/classic/user/introduction/languages/javascript#setting-up-a-custom-dockerfile) to install the desired version of node & other required tools.

### Setting up a custom Dockerfile

<iframe width="560" height="315" src="https://www.youtube.com/embed/jFsbmcXCRf8" title="Setting up a custom Dockerfile" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen className="rounded-xl" />

To ensure Gitpod workspaces always start with the correct dependencies, configure a Dockerfile:

1. Create a `.gitpod.yml`

```bash theme={null}
touch .gitpod.yml
```

2. Create a custom Dockerfile

```bash theme={null}
touch .gitpod.Dockerfile
```

3. Reference your newly created Dockerfile in your `.gitpod.yml`

```yml theme={null}
image:
    file: .gitpod.Dockerfile
```

4. Update your `.gitpod.Dockerfile` to install your dependency versions

```dockerfile theme={null}
FROM gitpod/workspace-full:latest

RUN bash -c 'VERSION="14.8.0" \
    && source $HOME/.nvm/nvm.sh && nvm install $VERSION \
    && nvm use $VERSION && nvm alias default $VERSION'

RUN echo "nvm use default &>/dev/null" >> ~/.bashrc.d/51-nvm-fix
```

5. Commit and push both `.gitpod.yml` and `.gitpod.Dockerfile`

```bash theme={null}
git commit -m "configuring gitpod with javascript" && git push
```

6. Start a **new workspace** from the branch with the committed `.gitpod.Dockerfile`

For example, opening: `gitpod.io/#https://github.com/gitpod-io/gitpod`

7. Test your dependencies are correct in the new workspace

```bash theme={null}
node -v
```

> If your changes are not taking effect, ensure your workspace is building from the correct [context](/classic/user/introduction/gitpod-tutorial/1-start-your-workspace#open-your-repository), where your `gitpod.yml` or `gitpod.Dockerfile` are checked in to version control and are on the branch or commit that you are opening.

See [configure Docker](/classic/user/configure/workspaces/workspace-image) for more.

## Build and run your application

### Building a JavaScript application

To build your application, you'll need to configure a [start task](/classic/user/configure/workspaces/tasks).

Start tasks are processes that are initiated on every workspace start. Depending on your project setup, start tasks can be used to build your application, run your application directly, or start any necessary tools for the application to run, such as starting database processes.

1. Add the command to build your application to your `.gitpod.yml`

**Example with npm**

```yml theme={null}
tasks:
    - init: npm install && npm run build
```

**Example with yarn**

```yml theme={null}
tasks:
    - init: yarn install && yarn build
```

2. **Optional:** Validate by stopping and starting (restart) your workspace

```bash theme={null}
gp stop
```

3. **Optional:** Validate your commands by running [`gp tasks`](/classic/user/references/gitpod-cli#tasks)

```shell theme={null}
gp tasks
```

<Tip> If you're using [VS Code Browser](/classic/user/references/ides-and-editors/vscode-browser) or [VS Code Desktop](/classic/user/references/ides-and-editors/vscode), then your tasks will open as terminal windows. You can configure their layout using the [openMode](/classic/user/configure/workspaces/tasks#openmode) property.</Tip>

<Note> We are using the `init` property so that we can perform application building during a [prebuild](/classic/user/configure/repositories/prebuilds), for increased performance. We'll discuss prebuilds more later on.</Note>

See [start tasks](/classic/user/configure/workspaces/tasks) and [.gitpod.yml reference](/classic/user/references/gitpod-yml) for more.

### Running a JavaScript application

To run your application, you have two options:

1. **Update your start task command** - Starting your application using the `command` start task will run the start process on workspace start. With both [VS Code Browser](/classic/user/references/ides-and-editors/vscode) and [VS Code Desktop](/classic/user/references/ides-and-editors/vscode-browser), tasks are automatically opened in the terminal(s). With [IntelliJ](/classic/user/references/ides-and-editors/intellij) / [JetBrains Gateway](/classic/user/integrations/jetbrains-gateway), configured tasks can be viewed by running `gp tasks` in the workspace.

#### Using start tasks to run JavaScript

1. Add a `command` for starting your application to your `.gitpod.yml`

**Example with npm**

```yml theme={null}
tasks:
    - init: npm install && npm run build
      command: npm run dev
```

**Example with yarn**

```yml theme={null}
tasks:
    - init: yarn install && yarn build
      command: yarn start
```

2. **Optional:** Validate by stopping and starting (restart) your workspace

```bash theme={null}
gp stop
```

3. **Optional:** Validate your commands by running [`gp tasks`](/classic/user/references/gitpod-cli#tasks)

```shell theme={null}
gp tasks
```

### Using ESLint for linting

If your project's `package.json` does not mention ESLint as a dependency then you have to install it first. For installing it add the following to the end of the `init` phase of your [.gitpod.yml](/classic/user/references/gitpod-yml) as shown:

```yml theme={null}
tasks:
    - init: npm install && npm run build && npm install -g eslint
```

and then search for `eslint` in the extensions tab and then install it from there using the install button.

### Hot Module Replacement (HMR)

Especially when it comes to Frontend Projects, the dev-server should be able to auto-reload on file changes. The implementation varies from server to server. To make this work, some additional config is required:

### Vite

Vite 3+ works with Gitpod out of the box. However, if you are using Vite 2 you should add the following config:

```js title="vite.config.js" theme={null}
import { defineConfig } from 'vite';

export default defineConfig({
	server: {
		hmr: process.env.GITPOD_WORKSPACE_URL
			? {
					protocol: 'wss',
					clientPort: 443,
					host: process.env.GITPOD_WORKSPACE_URL.replace(
						'https://',
						'3000-',
					),
			  }
			: true,
	},
});
```

### Webpack

In your `.gitpod.yml` file, you should export the workspace url for the port your server runs into the environment.

```yml .gitpod.yml theme={null}
tasks:
    - init: npm install
      command: |
          export HMR_HOST=`gp url 3000`
```

After the workspace URL with the given port is exported to the environment, it can be used in the `webpack.config.js` to determine the right port and hostname.

### Nuxt

Nuxt version `3.7.4` works out of the box with Gitpod.

```js title="webpack.config.js" theme={null}
module.exports = {
	devServer: {
		client: {
			webSocketURL: {
				hostname: process.env.HMR_HOST
					? new URL(process.env.HMR_HOST).hostname
					: 'localhost',
				port: process.env.HMR_HOST ? 443 : 3000,
				protocol: 'wss',
			},
		},
	},
};
```

### Use of Private Packages

If you want to use private packages from npm or yarn on Gitpod, you can use the [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-access-tokens) environment variable. You can set it in your [Gitpod user settings](/classic/user/configure/user-settings/environment-variables).

## Debug your JavaScript application in Gitpod

### Debugging JavaScript applications in VS Code

To debug your application, you can use the [VS Code Browser](/classic/user/references/ides-and-editors/vscode-browser) or [VS Code Desktop](/classic/user/references/ides-and-editors/vscode) IDE. You can start debugging by clicking the `Debug` button in the IDE's status bar or by pressing `F5` or following the steps below:

See the [official VS Code debugging guide](https://code.visualstudio.com/editor/debugging) for more.

### Debugging JavaScript applications in JetBrains IDE (WebStorm)

To debug your application, you can use the [WebStorm](/classic/user/references/ides-and-editors/webstorm) IDE. You can start debugging by clicking the `Add Configurations` button in the IDE's top status bar.

See the [official WebStorm debugging guide](https://blog.jetbrains.com/webstorm/2018/01/how-to-debug-with-webstorm/) for more.

## Example Repositories

Here are a few JavaScript/TypeScript example projects that are automated with Gitpod:

|                          Repository                          |                                       Description                                       |                                                               Try it                                                              |
| :----------------------------------------------------------: | :-------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------: |
|    [Tesseract.js](https://github.com/naptha/tesseract.js)    |                     Pure JavaScript OCR for more than 100 Languages                     |    [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/naptha/tesseract.js)    |
| [freeCodeCamp](https://github.com/freeCodeCamp/freeCodeCamp) | [freeCodeCamp.org](https://www.freecodecamp.org/)'s open source codebase and curriculum | [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/freeCodeCamp/freeCodeCamp) |
|      [Mozilla PDF.js](https://github.com/mozilla/pdf.js)     |                     PDF.js is a PDF viewer that is built with HTML5                     |       [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mozilla/pdf.js)      |

## Recommended Reading

* [Build Projects in a Gitpod Ephemeral Dev Environment — The Ultimate Guide](https://www.gitpod.io/guides/guide-ephemeral-dev-environment-on-gitpod)
* [Sustainable Node.js development with only a browser](https://www.gitpod.io/blog/node-js-development).
* [Developing a Nuxt.js app entirely in your browser](https://www.gitpod.io/blog/developing-nuxtjs-in-browser)
* [Gitpodifying — The Ultimate Guide](https://www.gitpod.io/guides/gitpodify)
* [Debugging Node.js applications in Theia](https://www.gitpod.io/blog/node-js-gitpod)