# nx-s3-plugin

> Utilities for managing S3 with NX. Includes sync'ing local directories with remote S3 buckets.

Latest version **1.0.7** (published 2023-05-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install nx-s3-plugin
pnpm add nx-s3-plugin
yarn add nx-s3-plugin
bun add nx-s3-plugin
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2023-05-02 |
| First published | 2023-04-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 11 |
| Unpacked size | 21.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | leeharrison1984 |
| Keywords | nx, s3, sync |

## Links

- npm: https://www.npmjs.com/package/nx-s3-plugin
- Repository: https://github.com/bruceharrison1984/nx-s3-plugin
- Homepage: https://github.com/bruceharrison1984/nx-s3-plugin#readme
- Issues: https://github.com/bruceharrison1984/nx-s3-plugin/issues
- npm.io page: https://npm.io/package/nx-s3-plugin

## Dependencies (11)

- [mime-types](https://npm.io/package/mime-types.md) 2.1.35
- [@swc/helpers](https://npm.io/package/@swc/helpers.md) 0.5.1
- [cli-progress](https://npm.io/package/cli-progress.md) 3.12.0
- [@aws-sdk/types](https://npm.io/package/@aws-sdk/types.md) 3.310.0
- [s3-sync-client](https://npm.io/package/s3-sync-client.md) 3.0.3
- [recursive-readdir](https://npm.io/package/recursive-readdir.md) 2.2.3
- [@aws-sdk/client-s3](https://npm.io/package/@aws-sdk/client-s3.md) 3.321.1
- [@aws-sdk/client-ssm](https://npm.io/package/@aws-sdk/client-ssm.md) 3.321.1
- [console-table-printer](https://npm.io/package/console-table-printer.md) 2.11.1
- [@aws-sdk/client-cloudformation](https://npm.io/package/@aws-sdk/client-cloudformation.md) 3.321.1
- [@aws-sdk/credential-provider-node](https://npm.io/package/@aws-sdk/credential-provider-node.md) 3.321.1

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads

## Recent versions

- 1.0.7 (latest) — 2023-05-02
- 1.0.6 — 2023-05-01
- 1.0.5 — 2023-04-15
- 1.0.4 — 2023-04-15
- 1.0.3 — 2023-04-15
- 1.0.2 — 2023-04-14
- 1.0.1 — 2023-04-14
- 1.0.0 — 2023-04-14
- 0.0.3 — 2023-04-14
- 0.0.1 — 2023-04-14

## README

# nx-s3-plugin

[![npm](https://img.shields.io/npm/v/nx-s3-plugin)](https://www.npmjs.com/package/nx-s3-plugin)

This is an NX executor that can be used to make changes to remote S3 buckets.

## Installation

Install the plugin in to your already configured NX workspace

```sh
npm i nx-s3-plugin
```

## Executors

| Name | Description                                           |
| ---- | ----------------------------------------------------- |
| sync | Synchronize a local directory with a remote S3 bucket |

## `sync`

<img style="padding: 1em; width: 70%; border: solid 1px grey; border-radius: 1em;" src="./docs/sync_example.png" />

The `sync` executor is similar to the `aws s3 sync` command. It will run a diff between local files and files contained in S3, and make S3 reflect the local directory. This can be very performant because only files which have changed will be uploaded. Bucket name can also be dynamically looked up from existing CloudFormation exports or SSM Parameters.

### Uploaded Bucket Object `content-type`

This plugin uses [mime-types](https://www.npmjs.com/package/mime-types) to make a best guess at file mime types as they are uploaded to S3. This means your files should arrive in S3, ready to be served as a static assets without having to manually define the types.

### AWS Credentials

The standard AWS credential chain of precedence is followed when making AWS calls. [@aws-sdk/credential-provider-node]() is used to to load these values, so that documentation should be used when setting up AWS credentials. In most cases, simply having the proper environment variables or valid credentials in your `~/.aws/credentials` file should be enough to get going. There is an optional `profile` argument that can be used if you wish to use a non-default set of credentials.

### Properties

| Name        | Description                                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sourceFiles | The path to the local files that you wish to upload. In the case of a static site, these should already be compiled (ie webpack).                       |
| bucketName  | The name of the S3 bucket where the files should be uploaded. _See notes on setting this value to retrieve a CF exported value or SSM Parameter value._ |
| region      | (Optional) The AWS region where requests will be sent. Will default to the local system default.                                                        |
| profile     | (Optional) The AWS credentials profile that will be used to make requests. Default system AWS credentials will be used if omitted.                      |
| batchSize   | (Optional) The number of files that will be present in each batch. Batched files are uploaded in parallel. Default is 500.                              |
| progress    | (Optional) Display upload progress. True by default.                                                                                                    |
| deleteFiles | (Optional) Should files be deleted in S3 if they are no longer present in the local directory. True by default.                                         |

### Usage

_You do not need to add `s3://` to bucketName, your CloudFormation export value, or your SSM parameter value. This plugin will add it for you._

Add the executor to the `target` section of `project.json`.

```js
  "targets": {
    "upload-site": {
      "executor": "nx-s3-plugin:sync",
      "options": {
        "sourceFiles": "<source-directory>",
        "bucketName": "[cfe|ssm]:<target-bucket>",
      }
    }
  }
```

### Static S3 Bucket Name

If you are directly targetting an S3 bucket, you can simply enter the name of the S3 bucket as the `bucketName` parameter in the NX task definition.

```js
  "targets": {
    "upload-site": {
      "executor": "nx-s3-plugin:sync",
      "options": {
        "sourceFiles": "/my-compiled-website-files",
        "bucketName": "my-s3-bucket",
      }
    }
  }
```

### Dynamic Cloudformation Export Lookup

If you prepend your `bucketName` with `cfe:`, this executor will attempt to locate a CloudFormation export with the same name. Omitting the `cfe:` prefix will simply use the `bucketName` value as is for the S3 url.

- If an export is found with a matching name, the value will be used for the S3 destination bucket.
- If an export is not found, an error will be thrown and no files will be uploaded.
- **Matching is case-sensitive.**
- This export must exist in the same account as the S3 bucket.
  - Cross-account lookup is not supported.

> Example:
>
> `cfe:StaticWebSite` will query CloudFormation for an export named `StaticWebSite` and use the value of that export as the `bucketName`.

```js
  "targets": {
    "upload-site": {
      "executor": "nx-s3-plugin:sync",
      "options": {
        "sourceFiles": "/my-compiled-website-files",
        "bucketName": "cfe:StaticWebSite",
      }
    }
  }
```

### Dynamic SSM Paramter Store Lookup

If you prepend your `bucketName` with `ssm:`, this executor will attempt to locate a SSM Paramter with the same name. Omitting the `ssm:` prefix will simply use the `bucketName` value as is for the S3 url.

- If an SSM Parameter is found with a matching name, the value will be used for the S3 destination bucket.
- If an SSM Parameter is not found, an error will be thrown and no files will be uploaded.
- **Matching is case-sensitive.**
- This SSM Parameter must exist in the same account as the S3 bucket.
  - Cross-account lookup is not supported.

> Example:
>
> `ssm:/myapp/s3bucket` will query for an SSM Parameter named `/myapp/s3bucket` and use the value of that export as the `bucketName`.

```js
  "targets": {
    "upload-site": {
      "executor": "nx-s3-plugin:sync",
      "options": {
        "sourceFiles": "/my-compiled-website-files",
        "bucketName": "ssm:/myapp/s3bucket",
      }
    }
  }
```

---
_Source: https://npm.io/package/nx-s3-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
