# Node.JS Server

This configuration is suitable if the project uses the node.js environment and the npm package manager. In this case, the project can be written in languages ​​such as JavaScript or TypeScript. This configuration is intended for server applications. For browser applications, see [Node.JS Browser](https://docs.amverum.ru/books/amverum/page/nodejs-browser).

You can write a yaml file yourself, using the instructions below, or use our yaml generator by clicking on [link](https://manifest.amverum.ru/).

## Section meta

The `meta` section of the `amverum.yml` file will look like this:

``` yaml
meta:
  environment: node
  toolchain:
    name: npm
    version: 18
```

The parameter that can be changed here is `meta.toolchain.version`. Logically, this is the version of node.js that should be used for the job. Technically, the value of `version` is substituted into the name of the Docker image that will be used.

The image `node:${meta.toolchain.version}` is used for both the build and run phases. Since the same image is used for both phases, `meta.toolchain.version` can be any tag of this image on [docker hub](https://hub.docker.com/_/node/tags).

## Section build

The `build` section may contain the following optional parameters:

 - `skip`
 - `additionalCommands`
 - `artifacts`

The `skip` parameter can be used if the project has no dependencies and/or does not have a `package.json` file. Specifying `skip: yes` will mean that the build phase will be skipped entirely.

During the build, the script runs the `npm install` command. If additional commands need to be run (e.g. `npm run build`), the `additionalCommands` parameter is used:

``` yaml
build:
  additionalCommands: npm run build
```

In this case, the command `npm install && npm run build` will be executed during the build.

The `artifacts` parameter allows you to specify which files should be included in the final application. By default, all files will be copied to the root of the application folder.

The `artifacts` parameter, unlike other parameters, is not a string, but a dictionary. The key in it is the mask of the source files to copy, and the value is the folder to which the files will be copied.

So, the default value of `artifacts` is:

``` yaml
build:
  artifacts:
    "*": /
```

We use the following copying rules:

 - only relative paths (without / at the beginning) are specified as a source;
 - if a file matches the mask, the file will be copied to the destination folder without the source path;
 - if a folder matches the mask, it will be copied entirely to the destination folder along with all its contents.

## Section run

The `run` section can contain the following parameters:

 - `scriptName`
 - `scriptArguments`
 - `nodeArguments`
 - `command`
 - `persistenceMount`
 - `persistenceMount`

The `scriptName` parameter is required.

The command `node ${run.nodeArguments} ${run.scriptName} ${run.scriptArguments}` is used to run it.

The `scriptName` parameter is the path to the script to run, relative to the repository root.

``` yaml
run:
  scriptName: index.js
```

If you need to pass additional arguments to `node` to run, you must specify them in the `nodeArguments` parameter.

If you need to pass additional arguments to the script to run, you must specify them in the `scriptArguments` parameter.

The `command` parameter is an alternative way to run the application. When using this parameter, the `scriptName`, `scriptArguments` and `nodeArguments` parameters are ignored. It must contain a complete command to run:

``` yaml
run:
  command: npm run start
```

The `persistenceMount` parameter allows you to specify in which directory the folder with [persistent storage](../storage.md#data) will be mounted.
The default value is `/data`.

The `containerPort` parameter allows you to specify which port the application listens on. The default value is `80`.

## Recipes

### Minimal amverum.yml file

``` yaml
meta:
  environment: node
  toolchain:
    name: npm
    version: 18

run:
  scriptName: index.js
```

### Express.JS application

``` yaml
meta:
  environment: node
  toolchain:
    name: npm
    version: 18

run:
  scriptName: index.js
  containerPort: 3000
```

### Application with a build phase (Webpack, tsc, etc.)

This file assumes that the build launch script is written in the `build` task, and the application launch script is written in the `start` task in the `package.json` file

``` yaml
meta:
  environment: node
  toolchain:
    name: npm
    version: 18

build:
  additionalCommands: npm run build

run:
  command: npm run start
  containerPort: 3000
```