Have ideas to improve npm?Join in the discussion! »


    3.4.6 • Public • Published


    npm version npm downloads coverage

    Non-Official Google Cloud Storage Provider for Strapi Upload


    Install the package from your app root directory

    with npm

    npm install strapi-provider-upload-google-cloud-storage --save

    or yarn

    yarn add strapi-provider-upload-google-cloud-storage

    Create your Bucket on Google Cloud Storage

    The bucket should be created with fine grained access control, as the plugin will configure uploaded files with public read access.

    How to create a bucket ?

    Where my bucket can be located ?

    Setting up Google authentication

    If you are deploying to a Google Cloud Platform product that supports Application Default Credentials (such as App Engine, Cloud Run, and Cloud Functions etc.), then you can skip this step.

    If you are deploying outside GCP, then follow these steps to set up authentication:

    1. In the GCP Console, go to the Create service account key page.
    2. From the Service account list, select New service account.
    3. In the Service account name field, enter a name.
    4. From the Role list, select Cloud Storage > Storage Admin.
    5. Select JSON for Key Type
    6. Click Create. A JSON file that contains your key downloads to your computer.
    7. Copy the full content of the downloaded JSON file
    8. Open the Strapi configuration file
    9. Paste it into the "Service Account JSON" field (as string or JSON, be careful with indentation)

    Setting up the configuration file

    You will find below many examples of configurations, for each example :

    1. If you are deploying outside GCP, then follow the steps above Setting up Google authentication
    2. Set the #bucketName# field and replace Bucket-name by yours previously create
    3. Default baseUrl is working, but you can replace it by yours (if you use a custom baseUrl)
    4. Save the configuration file
    5. Enjoy !

    Example with application default credentials (minimal setup)

    This works only for deployment to GCP products such as App Engine, Cloud Run, and Cloud Functions etc.

    Edit ./config/plugins.js

    module.exports = {
        upload: {
            provider: 'google-cloud-storage',
            providerOptions: {
                bucketName: '#bucketName#',
                publicFiles: false,
                uniform: false,
                basePath: '',

    Example with credentials for outside GCP account

    Edit ./config/plugins.js

    module.exports = {
        upload: {
            provider: 'google-cloud-storage',
            providerOptions: {
                bucketName: '#bucketName#',
                publicFiles: true,
                uniform: false,
                serviceAccount: {}, // replace `{}` with your serviceAccount JSON object
                baseUrl: 'https://storage.googleapis.com/{bucket-name}',
                basePath: '',

    If you have different upload provider by environment, you can override plugins.js file by environment :

    • config/env/development/plugins.js
    • config/env/production/plugins.js

    This file, under config/env/{env}/ will be overriding default configuration present in main folder config.

    Example with environment variable

    module.exports = ({ env }) => ({
        upload: {
          provider: 'google-cloud-storage',
          providerOptions: {
            serviceAccount: env.json('GCS_SERVICE_ACCOUNT'),
            bucketName: env('GCS_BUCKET_NAME'),
            basePath: env('GCS_BASE_PATH'),
            baseUrl: env('GCS_BASE_URL'),
            publicFiles: env('GCS_PUBLIC_FILES'),
            uniform: env('GCS_UNIFORM'),

    Environment variable can be changed has your way.

    How to configure variable ?

    serviceAccount :

    JSON data provide by Google Account (explained before). If you are deploying to a GCP product that supports Application Default credentials, you can leave this omitted, and authentication will work automatically.

    Can be set as a String, JSON Object, or omitted.

    bucketName :

    The name of the bucket on Google Cloud Storage.

    • Required

    You can find more information on Google Cloud documentation.

    baseUrl :

    Define your base Url, first is default value :

    basePath :

    Define base path to save each media document.

    • Optional


    Boolean to define a public attribute to file when it upload to storage.

    • Default value : true
    • Optional


    Boolean to define uniform access, when uniform bucket-level access is enabled

    • Default value : false
    • Optional


    Common errors

    Uniform access

    Error uploading file to Google Cloud Storage: Cannot insert legacy ACL for an object when uniform bucket-level access is enabled

    When this error occurs, you need to set uniform variable to true.

    Service Account JSON

    Error: Error parsing data "Service Account JSON", please be sure to copy/paste the full JSON file

    When this error occurs, it's probably because you have missed something with the service account json configuration.

    Follow this step :

    • Open your ServiceAccount json file
    • Copy the full content of the file
    • Paste it under the variable ServiceAccount in plugins.js config file in JSON




    • Slack (Highly recommended for faster support)
    • GitHub (Bug reports, contributions)


    npm i strapi-provider-upload-google-cloud-storage

    DownloadsWeekly Downloads






    Unpacked Size

    29.9 kB

    Total Files


    Last publish


    • avatar