# payload-plugin-cloud-storage-ali

> The third party cloud storage plugin for Payload CMS and Ali storage

Latest version **1.0.1** (published 2023-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install payload-plugin-cloud-storage-ali
pnpm add payload-plugin-cloud-storage-ali
yarn add payload-plugin-cloud-storage-ali
bun add payload-plugin-cloud-storage-ali
```

## 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.1 |
| Published | 2023-09-11 |
| First published | 2023-09-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 796.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | xyxc0673 |

## Links

- npm: https://www.npmjs.com/package/payload-plugin-cloud-storage-ali
- npm.io page: https://npm.io/package/payload-plugin-cloud-storage-ali

## Dependencies (2)

- [ali-oss](https://npm.io/package/ali-oss.md) ^6.18.0
- [range-parser](https://npm.io/package/range-parser.md) ^1.2.1

## Recent versions

- 1.0.1 (latest) — 2023-09-11

## README

# Payload Cloud Storage Plugin

This repository contains the officially supported Payload Cloud Storage plugin. It extends Payload to allow you to store all uploaded media in third-party permanent storage.

#### Requirements

- Payload version `1.0.19` or higher is required

## Installation

`yarn add payload-plugin-cloud-storage-ali` or `npm install payload-plugin-cloud-storage-ali`

## Usage

Add this package into your dependencies executing this code in your command line:

`yarn add payload-plugin-cloud-storage-ali`

Now install this plugin within your Payload as follows:

```ts
import { buildConfig } from 'payload/config';
import path from 'path';
import { cloudStorage } from 'payload-plugin-cloud-storage-ali';

export default buildConfig({
  plugins: [
    cloudStorage({
      collections: {
        'my-collection-slug': {
          adapter: theAdapterToUse, // see docs for the adapter you want to use
        },
      },
    }),
  ],
  // The rest of your config goes here
});
```

### Conditionally Enabling/Disabling

The proper way to conditionally enable/disable this plugin is to use the `enabled` property.

```ts
cloudStorage({
  enabled: process.env.MY_CONDITION === 'true',
  collections: {
    'my-collection-slug': {
      adapter: theAdapterToUse, // see docs for the adapter you want to use
    },
  },
}),
```

If the code is included *in any way in your config* but conditionally disabled in another fashion, you may run into issues such as `Webpack Build Error: Can't Resolve 'fs' and 'stream'` or similar because the plugin must be run at all times in order to properly extend the webpack config.

## Features

**Adapter-based Implementation**

This plugin supports the following adapters:

- [Ali OSS](#ali-oss-adapter)

However, you can create your own adapter for any third-party service you would like to use.

All adapters are implemented `dev` directory's [Payload Config](https://github.com/payloadcms/plugin-cloud-storage/blob/master/dev/src/payload.config.ts). See this file for examples.

## Plugin options

This plugin is configurable to work across many different Payload collections. A `*` denotes that the property is required.

| Option                  | Type                                    | Description |
|-------------------------|-----------------------------------------| ----------- |
| `collections` *         | Record<string, [CollectionOptions](https://github.com/payloadcms/plugin-cloud-storage/blob/c4a492a62abc2f21b4cd6a7c97778acd8e831212/src/types.ts#L48)> | Object with keys set to the slug of collections you want to enable the plugin for, and values set to collection-specific options. |
| `enabled`               |                                         | `boolean` to conditionally enable/disable plugin. Default: true. |

**Collection-specific options:**

| Option                        | Type                                                                                               | Description                                                                        |
|-------------------------------|----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| `adapter` *                   | [Adapter](https://github.com/payloadcms/plugin-cloud-storage/blob/master/src/types.ts#L51)         | Pass in the adapter that you'd like to use for this collection. You can also set this field to `null` for local development if you'd like to bypass cloud storage in certain scenarios and use local storage. |
| `disableLocalStorage`         | `boolean`                                                                                          | Choose to disable local storage on this collection. Defaults to `true`. |
| `disablePayloadAccessControl` | `true`                                                                                             | Set to `true` to disable Payload's access control. [More](#payload-access-control) |
| `prefix`                      | `string`                                                                                           | Set to `media/images` to upload files inside `media/images` folder in the bucket. |
| `generateFileURL`             | [GenerateFileURL](https://github.com/payloadcms/plugin-cloud-storage/blob/master/src/types.ts#L53) | Override the generated file URL with one that you create. |

### Ali OSS Adapter

To use the Ali adapter, you need to have `ali-oss` installed in your project dependencies. To do so, run `yarn add ali-oss`.

From there, create the adapter, passing in all of its required properties:

```js
import { aliAdapter } from 'payload-plugin-cloud-storage-ali/ali';

const adapter = aliAdapter({
  config: {
    accessKeyId: process.env.ALI_ACCESS_KEY_ID,
    accessKeySecret: process.env.ALI_ACCESS_KEY_SECRET,
    region: process.env.ALI_REGION,
    bucket: process.env.ALI_BUCKET,
    // ... Other Ali configuration
  },
})

// Now you can pass this adapter to the plugin
```

### Payload Access Control

Payload ships with access control that runs *even on statically served files*. The same `read` access control property on your `upload`-enabled collections is used, and it allows you to restrict who can request your uploaded files.

To preserve this feature, by default, this plugin *keeps all file URLs exactly the same*. Your file URLs won't be updated to point directly to your cloud storage source, as in that case, Payload's access control will be completely bypassed and you would need public readability on your cloud-hosted files.

Instead, all uploads will still be reached from the default `/collectionSlug/staticURL/filename` path. This plugin will "pass through" all files that are hosted on your third-party cloud service—with the added benefit of keeping your existing access control in place.

If this does not apply to you (your upload collection has `read: () => true` or similar) you can disable this functionality by setting `disablePayloadAccessControl` to `true`. When this setting is in place, this plugin will update your file URLs to point directly to your cloud host.

## Credit

This plugin was created with significant help, and code, from [Alex Bechmann](https://github.com/alexbechmann) and [Richard VanBergen](https://github.com/richardvanbergen). Thank you!!

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