# @financial-times/rel-engage

Standardised tools for JavaScript projects owned by the Engineering Insights team. It includes common configuration for linting and formatting of source files and solve other common tasks.

## Installation

This is package for [Node.js] and is available through the [npm] registry. Using Node 20 or higher is recommended.

Installation is done using the [npm install] command:

```bash
npm install -S @financial-times/rel-engage
```

[node.js]: https://nodejs.org/
[npm]: http://npmjs.com/
[npm install]: https://docs.npmjs.com/getting-started/installing-npm-packages-locally

Next copy the Makefile template into your project. This imports a number of pre-configured Make recipes for your project:

```bash
cp node_modules/@financial-times/rel-engage/templates/project-makefile.mk Makefile
```

Finally, execute the install recipe which will generate a number of [configuration files](#configuration):

```bash
make install
```

## Commands

By default the `rel-engage` Makefile provides a number of commands for common tasks, including:

-   `install` to install Node modules and create [configuration files](#configuration).
-   `verify` to run linting and code formatting tools.
-   `clean` to undo all changes and remove files that are not tracked by version control.
-   `env` to fetch and save [project secrets](#secrets)

To view a list of all commands and their descriptions, run:

```shell
make help
```

## Configuration

Each time you run the `make install` command provided by this package a number of configuration files will be added to your project if not already present:

-   [EditorConfig](https://editorconfig.org/) (`.editorconfig`) - provides whitespace settings for your editor when creating new files.
-   [ESLint](https://eslint.org/) (`.eslintrc.js`, `.eslintignore`) - configuration for linting JavaScript.
-   [Husky](https://github.com/typicode/husky) (`.huskyrc.js`) - installs and configures [Git hooks] to run commands before committing and pushing code.
-   [lint-staged](https://github.com/okonet/lint-staged) (`.lintstagedrc.cjs`) - configures commands to run only on changed files that will be committed.
-   [Prettier](https://prettier.io/) (`.prettierrc.js`, `.prettierignore`) - automatic formatting for JavaScript, JSON, YAML, and more.

The created "dotfiles" link to shared configuration provided by this package and do not contain any rules themselves.

These rules should rarely need to be overridden but if you do need to then it's possible to directly modify them, either by using the built in support for the tool (e.g ESLint supports an `extends` pattern), or by manually extending the provided JavaScript objects themselves.

[git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

## Secrets

Project secrets (such as API keys) are stored in [Doppler] and can be used by executing commands via use of the `doppler run --command="..."`.

Secrets in Doppler are stored in projects; one for each system and one for each team's shared secrets.

[Doppler]: (https://dashboard.doppler.com/workplace/99fbb11f5bea112e94dd/projects)

### Secrets for local development

To get started, ensure that you have the [doppler-cli](https://docs.doppler.com/docs/cli) installed and configured correctly and that you are in the `GLO-OKTA-DOPPLER-ENGINEERING-INSIGHTS` okta group.

Once this is done you should be able to run the `doppler login` command. If you run into any problems then you can ask for help on the [#engineering-insights Slack channel](https://app.slack.com/client/E01UWFL9HMZ/C02HH3JAQ5V).

Note the `doppler login` only authenticates you with Doppler; it does not allow you to access any secrets.
To access the secrets in your current project you must define a `PROJECT_NAME` in your `makefile`.
For example:

```make
    PROJECT_NAME=biz-ops-route53-importer
```

Once a `PROJECT_NAME` as been defined then you can inject the `test` secrets into your local session by running:

```bash
    make env
```

If you need to access `prod` secrets then use the following:

```bash
    make env ENV=prod
```

### Secrets on CircleCI

When Doppler credentials are required as part of your CI pipeline these can be retrieved by appending the `load_secrets` command from the [ft-circleci-orbs\/doppler-circleci](https://github.com/ft-circleci-orbs/doppler-circleci-orb) orb to your workflow jobs:

```yaml
  test:
    <<: *default_container_config
    steps:
      - *attach_workspace
      - load_secrets:
          config: TEST
      - run:
          name: Run unit tests
          command: make unit-test
```

## Contributing

### Requirements

To get started with this project you'll need to make sure you have the following software tools installed.

1. [Git](https://git-scm.com/)
2. [Node.js@24](https://nodejs.org/en/) (version 24 or higher is required)
3. [npm@11](http://npmjs.com/)

Please note that Page Kit has only been tested in Mac and Linux environments. If you are on a Mac you may find it easiest to install the [Command Line Tools](https://developer.apple.com/download/more/) package which includes Git.

### Project installation

1. Clone the project's Git repository and change to the new directory that has been created:

    ```bash
    git clone git@github.com:Financial-Times/rel-engage
    cd rel-engage
    ```

2. Install all of the project dependencies (this may take a few minutes if you are running this for the first time):

    ```bash
    nvm install && nvm use # To install & use the recommended node version
    make install
    ```