# cloud-bucket

> Simple multi cloud (Google Storage and AWS S3) bucket API

Latest version **0.5.0** (published 2026-01-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install cloud-bucket
pnpm add cloud-bucket
yarn add cloud-bucket
bun add cloud-bucket
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2026-01-07 |
| First published | 2019-03-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 8 |
| Unpacked size | 93.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Jeremy Chone |
| Maintainers | jeremychone |

## Links

- npm: https://www.npmjs.com/package/cloud-bucket
- Repository: https://github.com/BriteSnow/node-cloud-bucket
- Homepage: https://github.com/BriteSnow/node-cloud-bucket#readme
- Issues: https://github.com/BriteSnow/node-cloud-bucket/issues
- npm.io page: https://npm.io/package/cloud-bucket

## Dependencies (8)

- [micromatch](https://npm.io/package/micromatch.md) ^4.0.8
- [mime-types](https://npm.io/package/mime-types.md) ^3.0.2
- [fs-extra-plus](https://npm.io/package/fs-extra-plus.md) ^0.6.0
- [@types/micromatch](https://npm.io/package/@types/micromatch.md) ^4.0.10
- [@types/mime-types](https://npm.io/package/@types/mime-types.md) ^3.0.1
- [@aws-sdk/client-s3](https://npm.io/package/@aws-sdk/client-s3.md) ^3.964.0
- [@aws-sdk/lib-storage](https://npm.io/package/@aws-sdk/lib-storage.md) ^3.964.0
- [@google-cloud/storage](https://npm.io/package/@google-cloud/storage.md) ^7.18.0

## Recent versions

- 0.5.0 (latest) — 2026-01-07
- 0.4.2 — 2022-03-10
- 0.4.1 — 2022-01-20
- 0.4.0 — 2021-11-30
- 0.4.0-SNAPSHOT.1 — 2021-11-30
- 0.3.16 — 2021-11-27
- 0.3.15 — 2021-10-29
- 0.3.14 — 2021-06-25
- 0.3.13 — 2021-02-25
- 0.3.12 — 2021-02-15
- 0.3.11 — 2020-12-25
- 0.3.10 — 2020-11-06
- 0.3.8 — 2020-09-13
- 0.3.7 — 2020-09-06
- 0.3.6 — 2020-08-31
- … 25 more at https://npm.io/package/cloud-bucket/versions

## README

Simple cross cloud (for now GCP and AWS) bucket API. 

**Current Features:**
- Supports AWS, GCP, and Minio (for mock only)
- Directory support (i.e. directory: true makes .dirs = string[])
- Promise/async/await based.
- signed url (with urlSigner supporting s3 wildcard signature)
- Glob support (processed on the nodejs side)
- Typed (Typescript)

**Roadmap:**
- Stream copy between bucket
- Azure support


## Usage

- `npm install cloud-bucket`

```ts
import {getBucket} from 'cloud-bucket';

// For AWS S3 (or minio)
const bucketCfg = { 
  bucketName: '_BUCKET_NAME_',
  access_key_id: "_AWS_ACCESS_KEY_ID_",
  access_key_secret: "_AWS_ACCESS_KEY_SECRET_",
  minio_endpoint: "http://localhost:9000" // for minio (for mock s3)
};

// for google bucket
const bucketCfg = {
  bucketName: '_BUCKET_NAME_',
  project_id: '_GOOGLE_PROJECT_ID_NAME_',
  client_email: '_GOOGLE_SERVICE_ACCOUNT_EMAIL_',
  private_key: '-----BEGIN PRIVATE KEY-----\n_GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY_WITH_NEW_LINE_\n-----END PRIVATE KEY-----'
}


const bucket = await getBucket(bucketCfg);

//// Uploads
const file = await bucket.getFile('/some-file.txt');
// Return BucketFile or null if not found, throws exception if other error.

// upload to a folder
const remoteFiles = await bucket.upload('./some-file.txt', 'in-this-folder/');
// [{Bucket:..., 
//  path: 'in-this-folder/some-file.txt', 
//  size: 34, // size in bytes
//  local: './some-file.txt' // only present for upload/download
//  }]

// will upload to a specific name
const remoteFiles = await bucket.upload('./some-file.txt', 'in-this-folder/new-name.txt');

// upload a full folder remotely (recursive)
const remoteFiles = await bucket.upload('./some-dir/', 'remote-base-dir/');


//// List

const files = await bucket.listFiles();
// files: File[] (all files contained in this bucket, no pagination yet)

const files = await bucket.listFiles('in-this-folder/', {limit: 300});
// files: File[] (only file with the prefix 'in-this-folder/) and only the first 300;

const files = await bucket.listFiles('in-this-folder/**/*.txt');
// files: File[] (only file with the prefix 'in-this-folder/ and matching the glob);
// Note: Glob processing happen on the nodejs side.

// More result info by calling the list method. 
const listResult = await bucket.list('in-this-folder/', {directory: true});
// {files: BucketFile[], dirs?: string[], nextMarker}


//// Download

const files = await bucket.download('in-this-folder/some-file.txt', './local-dir/');
// files: [{
//   Bucket:  ...,
//   path: 'in-this-folder/some-file.txt',
//   size: 34,
//   local: `./local-dir/some-file.txt'
// }]

const files = await bucket.download('in-this-folder/**/*.txt', './local-dir/');
// Note: When glob as src, then, sub folder from the base path will be added in the local-dir
// files: [{
//   Bucket:  ...,
//   path: 'in-this-folder/some-file.txt',
//   size: 34,
//   local: `./local-dir/some-file.txt'
// },{
//   Bucket:  ...,
//   path: 'in-this-folder/sub-dir/another-file.txt',
//   size: 34,
//   local: `./local-dir/sub-dir/another-file.txt'
// },
//]

const deleted = await bucket.delete('some-file.txt');
// return true if deleted, false if not found, throws exception if other error.

```

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