@capacitor-firebase/storage

Unofficial Capacitor plugin for Firebase Cloud Storage.[^1]

Installation

npm install @capacitor-firebase/storage
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS).

Android

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

• $firebaseStorageVersion version of com.google.firebase:firebase-storage (default: 20.2.1)

Configuration

No configuration required for this plugin.

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Starter templates

The following starter templates are available:

• Ionstarter Angular Firebase

Usage

import { FirebaseStorage } from '@capacitor-firebase/storage';
import { Filesystem, Directory } from '@capacitor/filesystem';

const uploadFile = async () => {
  return new Promise((resolve, reject) => {
    await FirebaseStorage.uploadFile(
      {
        path: 'images/mountains.png',
        uri: 'file:///var/mobile/Containers/Data/Application/E397A70D-67E4-4258-236E-W1D9E12111D4/Library/Caches/092F8464-DE60-40B3-8A23-EB83160D9F9F/mountains.png',
      },
      (event, error) => {
        if (error) {
          reject(error);
        } else if (event?.completed) {
          resolve();
        }
      }
    );
  });
};

const downloadFile = async () => {
  const { downloadUrl } = await FirebaseStorage.getDownloadUrl({
    path: 'images/mountains.png',
  });
  const { path } = await Filesystem.downloadFile({
    url: downloadUrl,
    path: 'mountains.png',
    directory: Directory.Cache,
  });
  return path;
};

const getDownloadUrl = async () => {
  const { downloadUrl } = await FirebaseStorage.getDownloadUrl({
    path: 'images/mountains.png',
  });
  return downloadUrl;
};

const deleteFile = async () => {
  await FirebaseStorage.deleteFile({
    path: 'images/mountains.png',
  });
};

const listFiles = async () => {
  const { items } = await FirebaseStorage.listFiles({
    path: 'images',
  });
  return items;
};

const getMetadata = async () => {
  const result = await FirebaseStorage.getMetadata({
    path: 'images/mountains.png',
  });
  return result;
};

const updateMetadata = async () => {
  await FirebaseStorage.updateMetadata({
    path: 'images/mountains.png',
    metadata: {
      contentType: 'image/png',
      customMetadata: {
        foo: 'bar',
      },
    },
  });
};

const useEmulator = async () => {
  await FirebaseStorage.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};

API

• deleteFile(...)
• getDownloadUrl(...)
• getMetadata(...)
• listFiles(...)
• updateMetadata(...)
• uploadFile(...)
• useEmulator(...)
• Interfaces
• Type Aliases

deleteFile(...)

deleteFile(options: DeleteFileOptions) => Promise<void>

Delete a file.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | DeleteFileOptions |

Since: 5.3.0

getDownloadUrl(...)

getDownloadUrl(options: GetDownloadUrlOptions) => Promise<GetDownloadUrlResult>

Get the download url for a file.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | GetDownloadUrlOptions |

Returns: Promise<GetDownloadUrlResult>

Since: 5.3.0

getMetadata(...)

getMetadata(options: GetMetadataOptions) => Promise<GetMetadataResult>

Get the metadata for a file.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | GetMetadataOptions |

Returns: Promise<GetMetadataResult>

Since: 5.3.0

listFiles(...)

listFiles(options: ListFilesOptions) => Promise<ListFilesResult>

List files in a directory.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | ListFilesOptions |

Returns: Promise<ListFilesResult>

Since: 5.3.0

updateMetadata(...)

updateMetadata(options: UpdateMetadataOptions) => Promise<void>

Update the metadata for a file.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | UpdateMetadataOptions |

Since: 5.3.0

uploadFile(...)

uploadFile(options: UploadFileOptions, callback: UploadFileCallback) => Promise<CallbackId>

Upload a file.

| Param | Type | | -------------- | ----------------------------------------------------------------- | | options | UploadFileOptions | | callback | UploadFileCallback |

Returns: Promise<string>

Since: 5.3.0

useEmulator(...)

useEmulator(options: UseEmulatorOptions) => Promise<void>

Instrument your app to talk to the Cloud Storage emulator.

On Android, the cleartext traffic must be allowed. On the Capacitor configuration:

{
  server: {
    cleartext: true
  }
}

The cleartext traffic is not intended for use in production.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | UseEmulatorOptions |

Since: 6.1.0

Interfaces

DeleteFileOptions

| Prop | Type | Description | Since | | ---------- | ------------------- | ------------------------------------------------------------- | ----- | | path | string | The full path to the file to delete, including the file name. | 5.3.0 |

GetDownloadUrlResult

| Prop | Type | Description | Since | | ----------------- | ------------------- | ------------------------------ | ----- | | downloadUrl | string | The download url for the file. | 5.3.0 |

GetDownloadUrlOptions

| Prop | Type | Description | Since | | ---------- | ------------------- | ------------------------------------------------------------------------------- | ----- | | path | string | The full path to the file to get the download url for, including the file name. | 5.3.0 |

GetMetadataResult

| Prop | Type | Description | Since | | ------------------------ | --------------------------------------- | --------------------------------------------------------------------------------- | ----- | | bucket | string | The bucket this file is contained in. | 5.3.0 | | createdAt | number | The timestamp at which the file was created in milliseconds since the epoch. | 5.3.0 | | generation | string | The object's generation. | 5.3.0 | | md5Hash | string | The md5 hash of the file. | 5.3.0 | | metadataGeneration | string | The object's metadata generation. | 5.3.0 | | name | string | The short name of this file, which is the last component of the full path. | 5.3.0 | | path | string | The full path to the file, including the file name. | 5.3.0 | | size | number | The size of the file in bytes. | 5.3.0 | | updatedAt | number | The timestamp at which the file was last updated in milliseconds since the epoch. | 5.3.0 | | cacheControl | string | Served as the Cache-Control header on object download. | 6.1.0 | | contentDisposition | string | Served as the Content-Disposition header on object download. | 6.1.0 | | contentEncoding | string | Served as the Content-Encoding header on object download. | 6.1.0 | | contentLanguage | string | Served as the Content-Language header on object download. | 6.1.0 | | contentType | string | Served as the Content-Type header on object download. | 6.1.0 | | customMetadata | { [key: string]: string; } | Additional user-defined custom metadata. | 6.1.0 |

GetMetadataOptions

| Prop | Type | Description | Since | | ---------- | ------------------- | --------------------------------------------------------------------------- | ----- | | path | string | The full path to the file to get the metadata for, including the file name. | 5.3.0 |

ListFilesResult

| Prop | Type | Description | Since | | ------------------- | ------------------------------- | ------------------------------------------------------------------------------------- | ----- | | items | StorageReference[] | The list of files in the directory. | 5.3.0 | | nextPageToken | string | If set, there might be more results for this list. Use this token to resume the list. | 5.3.0 |

StorageReference

| Prop | Type | Description | Since | | ------------ | ------------------- | -------------------------------------------------------------------------- | ----- | | bucket | string | The bucket this file is contained in. | 5.3.0 | | path | string | The full path to the file, including the file name. | 5.3.0 | | name | string | The short name of this file, which is the last component of the full path. | 5.3.0 |

ListFilesOptions

| Prop | Type | Description | Default | Since | | ---------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- | | path | string | The full path to the directory to list files for. | | 5.3.0 | | maxResults | number | The maximum number of results to return. | 1000 | 5.3.0 | | pageToken | string | The page token, returned by a previous call to this method. If provided, listing is resumed from the previous position. | | 5.3.0 |

UpdateMetadataOptions

| Prop | Type | Description | Since | | -------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----- | | path | string | The full path to the file to update the metadata for, including the file name. | 5.3.0 | | metadata | SettableMetadata | The metadata to update. | 5.3.0 |

SettableMetadata

| Prop | Type | Description | Since | | ------------------------ | --------------------------------------- | -------------------------------------------------------------- | ----- | | cacheControl | string | Served as the Cache-Control header on object download. | 5.3.0 | | contentDisposition | string | Served as the Content-Disposition header on object download. | 5.3.0 | | contentEncoding | string | Served as the Content-Encoding header on object download. | 5.3.0 | | contentLanguage | string | Served as the Content-Language header on object download. | 5.3.0 | | contentType | string | Served as the Content-Type header on object download. | 5.3.0 | | customMetadata | { [key: string]: string; } | Additional user-defined custom metadata. | 5.3.0 |

UploadFileOptions

| Prop | Type | Description | Since | | -------------- | --------------------------------------------------------- | --------------------------------------------------------------------- | ----- | | blob | Blob | The data to upload. Only available for Web. | 5.3.0 | | path | string | The full path where data should be uploaded, including the file name. | 5.3.0 | | uri | string | The uri to the file to upload. Only available for Android and iOS. | 5.3.0 | | metadata | UploadMetadata | The metadata to set for the file. | 5.4.0 |

UploadMetadata

| Prop | Type | Description | Since | | ------------- | ------------------- | ---------------------------------------------------------------- | ----- | | md5Hash | string | The base64-encoded MD5 hash of the file. Only available for Web. | 5.4.0 |

UploadFileCallbackEvent

| Prop | Type | Description | Since | | ---------------------- | -------------------- | ----------------------------------------------------------------------------------- | ----- | | progress | number | The upload progress, as a percentage between 0 and 1. | 5.3.0 | | bytesTransferred | number | The number of bytes that have been transferred. Only available for Android and Web. | 5.3.0 | | totalBytes | number | The total number of bytes to be transferred. Only available for Android and Web. | 5.3.0 | | completed | boolean | Whether the upload is completed or not. | 5.3.0 |

UseEmulatorOptions

| Prop | Type | Description | Default | Since | | ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- | | host | string | The emulator host without any port or scheme. Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer. | | 6.1.0 | | port | number | The emulator port. | 9199 | 6.1.0 |

Type Aliases

UploadFileCallback

(event: UploadFileCallbackEvent | null, error: any): void

CallbackId

string

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.