> For the complete documentation index, see [llms.txt](https://darkobits.gitbook.io/nr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://darkobits.gitbook.io/nr/getting-started/configuration-file.md).

# Configuration File

`nr` is configured using a JavaScript configuration file named `nr.config.js` that should be placed in the root directory of your project.

A configuration file is responsible for creating **commands**, **tasks**, and **scripts**:

* **Commands** describe the invocation of a single executable and any arguments provided to it, as well as any configuration related to how the command should be invoked and how its output should be handled.
* **Tasks** are JavaScript functions that may execute arbitrary code. They may be synchronous or asynchronous.
* **Scripts** are the entry-point to `nr`. They compose commands, tasks, and other scripts that may run sequentially, in parallel, or a combination of both. 

A configuration file must export a function that will be passed a `ConfigurationFactoryContext` object that contains the following properties:

<table><thead><tr><th width="142.33333333333331">Key</th><th width="127">Type</th><th>Description</th></tr></thead><tbody><tr><td><a href="/nr/configuration-reference/command.md"><code>command</code></a></td><td><code>function</code></td><td>Creates a new command.</td></tr><tr><td><a href="/nr/configuration-reference/task.md"><code>task</code></a></td><td><code>function</code></td><td>Creates a new task.</td></tr><tr><td><a href="/nr/configuration-reference/script.md"><code>script</code></a></td><td><code>function</code></td><td>Creates a new script.</td></tr><tr><td><code>isCI</code></td><td><code>boolean</code></td><td><code>true</code> in CI environments. See <a href="https://github.com/watson/is-ci"><code>is-ci</code></a>.</td></tr></tbody></table>

These functions are documented in more detail later in this guide.

### ESM

The examples in this guide are written in modern ESM syntax. If your project is configured to support this syntax, either by declaring `"type": "module"` in `package.json` or via Babel, you can author your `nr` configuration file the same way.

{% code title="nr.config.js" %}

```typescript
export default ({ command, task, script }) => {
  // Define scripts here.
};
```

{% endcode %}

{% hint style="info" %}
Note: If your project uses Babel to provide support for modern language features, `nr` will automatically use your project's local Babel configuration. You do not need to use a `.babel.js` extension.
{% endhint %}

### CommonJS

If your project is not configured to support ESM syntax, you will need to author your configuration file using CommonJS syntax:

{% code title="nr.config.js" %}

```typescript
module.exports = ({ command, task, script }) => {
  // Define scripts here.
};
```

{% endcode %}

## Hello World Example

Here, we will define a simple script that runs a single command that outputs "Hello world!". Use this as a sanity check to ensure `nr` can find and parse your configuration file. The concepts used here will be covered in more detail later in the guide.

{% code title="nr.config.js" %}

```typescript
export default ({ command, script }) => {
  script('hello-world', {
    run: [
      command('hello-world', ['echo', ['Hello world!']])
    ]
  });
};
```

{% endcode %}

Verify that you can run this script using one of the following commands, depending on how you have configured your environment:

{% code title="Command Line" %}

```
$ nr hello-world
Hello world!
```

{% endcode %}

{% code title="Command Line" %}

```
$ npx nr hello-world
Hello world!
```

{% endcode %}

Once you have created your configuration file, proceed to the next section to learn how to create your first script.