Skip to content

Latest commit

 

History

History

storage

README.md

@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:

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(...)

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.

Footnotes

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