# @storyshelf/storage-gcs

> Store StoryShelf artifacts in Google Cloud Storage.

Source: https://storyshelf.js.org/packages/storage-gcs/

`@storyshelf/storage-gcs` stores StoryShelf blobs in a **Google Cloud Storage (GCS)** bucket — captured screenshots, diff overlays, and uploaded Storybook archives.

## Install

```sh
npm i @storyshelf/storage-gcs
```

[![JSR](https://jsr.io/badges/@storyshelf/storage-gcs)](https://jsr.io/@storyshelf/storage-gcs) [![JSR Score](https://jsr.io/badges/@storyshelf/storage-gcs/score)](https://jsr.io/@storyshelf/storage-gcs)

- [npm package](https://www.npmjs.com/package/@storyshelf/storage-gcs) — install tarballs and version history.
- [JSR package](https://jsr.io/@storyshelf/storage-gcs) — TypeScript-first registry page.
- [Public API reference](https://storyshelf.js.org/reference/storage-gcs/) — generated docs for every export; start here to learn the API. (The same reference is on [JSR](https://jsr.io/@storyshelf/storage-gcs/doc).)
- [Source on GitHub](https://github.com/GuptaSiddhant/storyshelf/tree/main/packages/storage-gcs) — package directory on `main`.

## Configure

```ts
import { createGcsStorage } from "@storyshelf/storage-gcs";
import { createShelfApp } from "@storyshelf/app";

const storage = createGcsStorage({
  bucket: "my-shelf",
  prefix: "storyshelf", // optional
  projectId: "my-gcp-project", // optional, defaults to ADC
});

const app = createShelfApp({ database, storage });
```

For local emulators or custom endpoints:

```ts
const storage = createGcsStorage({
  bucket: "my-shelf",
  apiEndpoint: "http://localhost:9090",
  projectId: "test-project",
});
```

Inject a pre-configured client (tests / IAM-rotation):

```ts
import { Storage } from "@google-cloud/storage";

const client = new Storage({ projectId: "my-project" });
const storage = createGcsStorage({ bucket: "my-shelf", client });
```

### `GcsStorageOptions`

```ts
interface GcsStorageOptions {
  bucket: string; // required GCS bucket name
  prefix?: string; // optional key prefix, defaults to ""
  client?: Storage; // optional pre-configured @google-cloud/storage client
  projectId?: string; // optional GCP project id
  keyFilename?: string; // optional path to service-account JSON
  credentials?: object; // optional service-account credentials object
  apiEndpoint?: string; // optional custom endpoint (emulator)
}
```

Options at a glance:

| Option        | Required | Notes                                                    |
| ------------- | -------- | -------------------------------------------------------- |
| `bucket`      | yes      | GCS bucket name                                          |
| `prefix`      | no       | Key prefix for every object                              |
| `client`      | no       | Pre-built `Storage` client (tests, custom endpoint)      |
| `projectId`   | no       | GCP project ID (defaults to ADC)                         |
| `keyFilename` | no       | Path to service-account JSON                             |
| `credentials` | no       | Inline service-account object                            |
| `apiEndpoint` | no       | Custom endpoint (emulator, e.g. `http://localhost:9090`) |

Auth otherwise uses Application Default Credentials.

### `createGcsStorage(options: GcsStorageOptions): StorageAdapter`

Creates a `StorageAdapter` backed by the configured GCS bucket. The returned adapter implements every method of the `StorageAdapter` interface (`read`, `write`, `delete`, `exists`, `list(prefix)`, `readStream`, `writeStream`).

### `gcsKey(prefix: string, path: string): string`

Helper that joins a storage prefix with a relative path into an object key.

## When to use it

Use GCS for GCP deploys — Cloud Run, GKE, or Cloud Functions — especially paired with [db-postgres](../db-postgres/). It is a drop-in replacement for [local storage](../storage-local/), [S3](../storage-s3/), and [Azure Blob](../storage-azure/).