Overview

The Storage API in StudioCMS provides a unified way to manage and interact with various storage backends. It abstracts the complexities of different storage systems, allowing developers to work with a consistent interface regardless of the underlying technology.

How it Works

The Storage API is designed to be flexible and extensible. It supports multiple storage backends, including local file systems, cloud storage services, and databases. Developers can choose the storage backend that best fits their needs and easily switch between them without changing their application code.

Manager plugins

The Storage API uses manager plugins to handle different storage backends. Each manager plugin implements a specific storage system and provides methods for common operations such as reading, writing, and deleting files.

An example of a manager built-in to StudioCMS is the no-op manager, which performs no operations and tells StudioCMS not to enable any of its storage features.

Example of the No-op Manager

import type {
  
type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType,
  
interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition,
  
type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn,
  
interface StorageApiBuilderDefinition<C, R>
Storage API Builder Definition interface.
This interface defines the structure and methods for building storage API endpoints,
including handling POST and PUT requests.
StorageApiBuilderDefinition,
  
(alias) interface UrlMappingServiceDefinition
import UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition,
} from 'studiocms/storage-manager/definitions';

/**
 * A No-Op Storage Service that implements the StorageApiBuilderDefinition interface.
 *
 * This service provides placeholder implementations for storage API endpoints,
 * returning a 501 Not Implemented response for both POST and PUT requests.
 *
 * @typeParam C - The context type.
 * @typeParam R - The response type.
 */
export default class 
class NoOpStorageService<C, R>
A No-Op Storage Service that implements the StorageApiBuilderDefinition interface.
This service provides placeholder implementations for storage API endpoints,
returning a 501 Not Implemented response for both POST and PUT requests.
NoOpStorageService<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R> implements
  
interface StorageApiBuilderDefinition<C, R>
Storage API Builder Definition interface.
This interface defines the structure and methods for building storage API endpoints,
including handling POST and PUT requests.
StorageApiBuilderDefinition<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R> {
    
NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver: 
interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R>;
    
NoOpStorageService<C, R>.urlMappingService: UrlMappingServiceDefinition
urlMappingService: 
(alias) interface UrlMappingServiceDefinition
import UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition;

    constructor(
      
driver: ContextDriverDefinition<C, R>
driver: 
interface ContextDriverDefinition<C, R>
Context Driver Definition interface.
This interface defines the structure and methods for a context driver,
including parsing the context, building responses, and handling endpoints.
ContextDriverDefinition<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R>,
      
urlMappingService: UrlMappingServiceDefinition
urlMappingService: 
(alias) interface UrlMappingServiceDefinition
import UrlMappingServiceDefinition
URL Mapping Service Definition interface.
This interface defines the structure and methods for the URL Mapping Service,
which manages the mapping between storage file identifiers and their corresponding URLs.
UrlMappingServiceDefinition
    ) {
      this.
NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver = 
driver: ContextDriverDefinition<C, R>
driver;
      this.
NoOpStorageService<C, R>.urlMappingService: UrlMappingServiceDefinition
urlMappingService = 
urlMappingService: UrlMappingServiceDefinition
urlMappingService;
    }

    #sharedResponse() {
      return { 
data: {
    error: string;
}
data: { 
error: string
error: 'noStorageConfigured' }, 
status: number
status: 501 };
    }

    
NoOpStorageService<C, R>.getPOST(_?: AuthorizationType): StorageAPIEndpointFn<C, R>
getPOST(
_: AuthorizationType | undefined
_?: 
type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType): 
type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R> {
      return this.
NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver.
ContextDriverDefinition<C, R>.handleEndpoint(contextHandler: ContextHandler): ContextHandlerFn<C, R>
handleEndpoint(async () => this.#sharedResponse());
    }

    
NoOpStorageService<C, R>.getPUT(_?: AuthorizationType): StorageAPIEndpointFn<C, R>
getPUT(
_: AuthorizationType | undefined
_?: 
type AuthorizationType = "locals" | "headers"
Authorization Type.
This type defines the possible authorization types
that can be used in storage manager API requests.
AuthorizationType): 
type StorageAPIEndpointFn<C, R> = (context: C) => Promise<R>
Storage API Endpoint Function type.
This type defines a function that takes a context of type C
and returns a Promise resolving to a response of type R.
StorageAPIEndpointFn<
function (type parameter) C in NoOpStorageService<C, R>
C, 
function (type parameter) R in NoOpStorageService<C, R>
R> {
      return this.
NoOpStorageService<C, R>.driver: ContextDriverDefinition<C, R>
driver.
ContextDriverDefinition<C, R>.handleEndpoint(contextHandler: ContextHandler): ContextHandlerFn<C, R>
handleEndpoint(async () => this.#sharedResponse());
    }
}

Configuring a Manager

To configure a storage manager in StudioCMS, you need to specify the desired manager plugin in your StudioCMS configuration file. To do so you must install the manager plugin package and then add it to the storageManager property in your studiocms.config.* file.

import { 
function defineStudioCMSConfig(config: StudioCMSOptions): {
    readonly dbStartPage?: boolean | undefined;
    readonly verbose?: boolean | undefined;
    readonly logLevel?: "All" | "Fatal" | "Error" | "Warning" | "Info" | "Debug" | "Trace" | "None" | undefined;
    readonly db?: {
        readonly dialect?: "libsql" | "postgres" | "mysql" | undefined;
    } | undefined;
    readonly plugins?: {
        readonly identifier: string;
        readonly name: string;
        readonly studiocmsMinimumVersion?: string | undefined;
        readonly requires?: readonly string[] | undefined;
        readonly hooks: {
            "studiocms:astro-config"?: ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>;
            }) => Promise<void>) | ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>;
            }) => void) | undefined;
            "studiocms:auth"?: ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly setAuthService: (args: {
                    oAuthProvider: {
                        readonly name: string;
                        readonly formattedName: string;
                        readonly svg: string;
                        readonly endpointPath: string;
                        readonly requiredEnvVariables?: readonly string[] | undefined;
                    };
                }) => Promise<void>;
            }) => Promise<void>) | ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly setAuthService: (args: {
                    oAuthProvider: {
                        readonly name: string;
                        readonly formattedName: string;
                        readonly svg: string;
                        readonly endpointPath: string;
                        readonly requiredEnvVariables?: readonly string[] | undefined;
                    };
                }) => Promise<void>;
            }) => void) | undefined;
            "studiocms:dashboard"?: ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly setDashboard: (args: {
                    translations: {
                        [x: string]: {
                            [x: string]: {
                                [x: string]: string;
                            };
                        };
                    };
                    dashboardGridItems?: readonly {
                        readonly name: string;
                        readonly span: 1 | 2 | 3;
                        readonly variant: "default" | "filled";
                        readonly requiresPermission?: "owner" | "admin" | "editor" | "visitor" | undefined;
                        readonly header?: {
                            readonly title: string;
                            readonly icon?: "heroicons:academic-cap" | "heroicons:academic-cap-16-solid" | "heroicons:academic-cap-20-solid" | "heroicons:academic-cap-solid" | "heroicons:adjustments-horizontal" | "heroicons:adjustments-horizontal-16-solid" | "heroicons:adjustments-horizontal-20-solid" | "heroicons:adjustments-horizontal-solid" | "heroicons:adjustments-vertical" | "heroicons:adjustments-vertical-16-solid" | "heroicons:adjustments-vertical-20-solid" | "heroicons:adjustments-vertical-solid" | "heroicons:archive-box" | "heroicons:archive-box-16-solid" | "heroicons:archive-box-20-solid" | "heroicons:archive-box-arrow-down" | "heroicons:archive-box-arrow-down-16-solid" | "heroicons:archive-box-arrow-down-20-solid" | "heroicons:archive-box-arrow-down-solid" | "heroicons:archive-box-solid" | "heroicons:archive-box-x-mark" | "heroicons:archive-box-x-mark-16-solid" | "heroicons:archive-box-x-mark-20-solid" | "heroicons:archive-box-x-mark-solid" | "heroicons:arrow-down" | "heroicons:arrow-down-16-solid" | "heroicons:arrow-down-20-solid" | "heroicons:arrow-down-circle" | "heroicons:arrow-down-circle-16-solid" | "heroicons:arrow-down-circle-20-solid" | "heroicons:arrow-down-circle-solid" | "heroicons:arrow-down-left" | "heroicons:arrow-down-left-16-solid" | "heroicons:arrow-down-left-20-solid" | "heroicons:arrow-down-left-solid" | "heroicons:arrow-down-on-square" | "heroicons:arrow-down-on-square-16-solid" | "heroicons:arrow-down-on-square-20-solid" | "heroicons:arrow-down-on-square-solid" | "heroicons:arrow-down-on-square-stack" | "heroicons:arrow-down-on-square-stack-16-solid" | "heroicons:arrow-down-on-square-stack-20-solid" | "heroicons:arrow-down-on-square-stack-solid" | "heroicons:arrow-down-right" | "heroicons:arrow-down-right-16-solid" | "heroicons:arrow-down-right-20-solid" | "heroicons:arrow-down-right-solid" | "heroicons:arrow-down-solid" | "heroicons:arrow-down-tray" | "heroicons:arrow-down-tray-16-solid" | "heroicons:arrow-down-tray-20-solid" | "heroicons:arrow-down-tray-solid" ...
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.
StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.
Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';

export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig } from "studiocms/config";
import 
function s3Storage(): StudioCMSStorageManagerDef
Creates and configures a StudioCMS S3 Storage Manager plugin.
This function initializes the S3 storage integration for StudioCMS by defining
a storage manager plugin with the necessary configuration and hooks.
@returns ― A configured storage manager instance that integrates
S3 storage capabilities with StudioCMS.
@example 
import { studiocmsS3Storage } from '@studiocms/s3-storage';

const s3Storage = studiocmsS3Storage();
s3Storage from '@studiocms/s3-storage';

export default 
function defineStudioCMSConfig(config: StudioCMSOptions): {
    readonly dbStartPage?: boolean | undefined;
    readonly verbose?: boolean | undefined;
    readonly logLevel?: "All" | "Fatal" | "Error" | "Warning" | "Info" | "Debug" | "Trace" | "None" | undefined;
    readonly db?: {
        readonly dialect?: "libsql" | "postgres" | "mysql" | undefined;
    } | undefined;
    readonly plugins?: {
        readonly identifier: string;
        readonly name: string;
        readonly studiocmsMinimumVersion?: string | undefined;
        readonly requires?: readonly string[] | undefined;
        readonly hooks: {
            "studiocms:astro-config"?: ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>;
            }) => Promise<void>) | ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>;
            }) => void) | undefined;
            "studiocms:auth"?: ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly setAuthService: (args: {
                    oAuthProvider: {
                        readonly name: string;
                        readonly formattedName: string;
                        readonly svg: string;
                        readonly endpointPath: string;
                        readonly requiredEnvVariables?: readonly string[] | undefined;
                    };
                }) => Promise<void>;
            }) => Promise<void>) | ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly setAuthService: (args: {
                    oAuthProvider: {
                        readonly name: string;
                        readonly formattedName: string;
                        readonly svg: string;
                        readonly endpointPath: string;
                        readonly requiredEnvVariables?: readonly string[] | undefined;
                    };
                }) => Promise<void>;
            }) => void) | undefined;
            "studiocms:dashboard"?: ((args: {
                readonly logger: AstroIntegrationLogger;
                readonly setDashboard: (args: {
                    translations: {
                        [x: string]: {
                            [x: string]: {
                                [x: string]: string;
                            };
                        };
                    };
                    dashboardGridItems?: readonly {
                        readonly name: string;
                        readonly span: 1 | 2 | 3;
                        readonly variant: "default" | "filled";
                        readonly requiresPermission?: "owner" | "admin" | "editor" | "visitor" | undefined;
                        readonly header?: {
                            readonly title: string;
                            readonly icon?: "heroicons:academic-cap" | "heroicons:academic-cap-16-solid" | "heroicons:academic-cap-20-solid" | "heroicons:academic-cap-solid" | "heroicons:adjustments-horizontal" | "heroicons:adjustments-horizontal-16-solid" | "heroicons:adjustments-horizontal-20-solid" | "heroicons:adjustments-horizontal-solid" | "heroicons:adjustments-vertical" | "heroicons:adjustments-vertical-16-solid" | "heroicons:adjustments-vertical-20-solid" | "heroicons:adjustments-vertical-solid" | "heroicons:archive-box" | "heroicons:archive-box-16-solid" | "heroicons:archive-box-20-solid" | "heroicons:archive-box-arrow-down" | "heroicons:archive-box-arrow-down-16-solid" | "heroicons:archive-box-arrow-down-20-solid" | "heroicons:archive-box-arrow-down-solid" | "heroicons:archive-box-solid" | "heroicons:archive-box-x-mark" | "heroicons:archive-box-x-mark-16-solid" | "heroicons:archive-box-x-mark-20-solid" | "heroicons:archive-box-x-mark-solid" | "heroicons:arrow-down" | "heroicons:arrow-down-16-solid" | "heroicons:arrow-down-20-solid" | "heroicons:arrow-down-circle" | "heroicons:arrow-down-circle-16-solid" | "heroicons:arrow-down-circle-20-solid" | "heroicons:arrow-down-circle-solid" | "heroicons:arrow-down-left" | "heroicons:arrow-down-left-16-solid" | "heroicons:arrow-down-left-20-solid" | "heroicons:arrow-down-left-solid" | "heroicons:arrow-down-on-square" | "heroicons:arrow-down-on-square-16-solid" | "heroicons:arrow-down-on-square-20-solid" | "heroicons:arrow-down-on-square-solid" | "heroicons:arrow-down-on-square-stack" | "heroicons:arrow-down-on-square-stack-16-solid" | "heroicons:arrow-down-on-square-stack-20-solid" | "heroicons:arrow-down-on-square-stack-solid" | "heroicons:arrow-down-right" | "heroicons:arrow-down-right-16-solid" | "heroicons:arrow-down-right-20-solid" | "heroicons:arrow-down-right-solid" | "heroicons:arrow-down-solid" | "heroicons:arrow-down-tray" | "heroicons:arrow-down-tray-16-solid" | "heroicons:arrow-down-tray-20-solid" | "heroicons:arrow-down-tray-solid" ...
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.
StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.
Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms/config';

export default defineStudioCMSConfig({
 dbStartPage: true,
 // ...Other Options
})
defineStudioCMSConfig({
    
storageManager?: {
    readonly identifier: string;
    readonly name: string;
    readonly studiocmsMinimumVersion?: string | undefined | undefined;
    readonly requires?: readonly string[] | undefined;
    readonly hooks: {
        "studiocms:astro-config"?: ((args: {
            readonly logger: AstroIntegrationLogger;
            readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>;
        }) => Promise<void>) | ((args: {
            readonly logger: AstroIntegrationLogger;
            readonly addIntegrations: (args: AstroIntegration | AstroIntegration[]) => Promise<void>;
        }) => void) | undefined;
        "studiocms:auth"?: ((args: {
            readonly logger: AstroIntegrationLogger;
            readonly setAuthService: (args: {
                oAuthProvider: {
                    readonly name: string;
                    readonly formattedName: string;
                    readonly svg: string;
                    readonly endpointPath: string;
                    readonly requiredEnvVariables?: readonly string[] | undefined;
                };
            }) => Promise<void>;
        }) => Promise<void>) | ((args: {
            readonly logger: AstroIntegrationLogger;
            readonly setAuthService: (args: {
                oAuthProvider: {
                    readonly name: string;
                    readonly formattedName: string;
                    readonly svg: string;
                    readonly endpointPath: string;
                    readonly requiredEnvVariables?: readonly string[] | undefined;
                };
            }) => Promise<void>;
        }) => void) | undefined;
        "studiocms:dashboard"?: ((args: {
            readonly logger: AstroIntegrationLogger;
            readonly setDashboard: (args: {
                translations: {
                    [x: string]: {
                        [x: string]: {
                            [x: string]: string;
                        };
                    };
                };
                dashboardGridItems?: readonly {
                    readonly name: string;
                    readonly span: 1 | 2 | 3;
                    readonly variant: "default" | "filled";
                    readonly requiresPermission?: "owner" | "admin" | "editor" | "visitor" | undefined;
                    readonly header?: {
                        readonly title: string;
                        readonly icon?: "heroicons:academic-cap" | "heroicons:academic-cap-16-solid" | "heroicons:academic-cap-20-solid" | "heroicons:academic-cap-solid" | "heroicons:adjustments-horizontal" | "heroicons:adjustments-horizontal-16-solid" | "heroicons:adjustments-horizontal-20-solid" | "heroicons:adjustments-horizontal-solid" | "heroicons:adjustments-vertical" | "heroicons:adjustments-vertical-16-solid" | "heroicons:adjustments-vertical-20-solid" | "heroicons:adjustments-vertical-solid" | "heroicons:archive-box" | "heroicons:archive-box-16-solid" | "heroicons:archive-box-20-solid" | "heroicons:archive-box-arrow-down" | "heroicons:archive-box-arrow-down-16-solid" | "heroicons:archive-box-arrow-down-20-solid" | "heroicons:archive-box-arrow-down-solid" | "heroicons:archive-box-solid" | "heroicons:archive-box-x-mark" | "heroicons:archive-box-x-mark-16-solid" | "heroicons:archive-box-x-mark-20-solid" | "heroicons:archive-box-x-mark-solid" | "heroicons:arrow-down" | "heroicons:arrow-down-16-solid" | "heroicons:arrow-down-20-solid" | "heroicons:arrow-down-circle" | "heroicons:arrow-down-circle-16-solid" | "heroicons:arrow-down-circle-20-solid" | "heroicons:arrow-down-circle-solid" | "heroicons:arrow-down-left" | "heroicons:arrow-down-left-16-solid" | "heroicons:arrow-down-left-20-solid" | "heroicons:arrow-down-left-solid" | "heroicons:arrow-down-on-square" | "heroicons:arrow-down-on-square-16-solid" | "heroicons:arrow-down-on-square-20-solid" | "heroicons:arrow-down-on-square-solid" | "heroicons:arrow-down-on-square-stack" | "heroicons:arrow-down-on-square-stack-16-solid" | "heroicons:arrow-down-on-square-stack-20-solid" | "heroicons:arrow-down-on-square-stack-solid" | "heroicons:arrow-down-right" | "heroicons:arrow-down-right-16-solid" | "heroicons:arrow-down-right-20-solid" | "heroicons:arrow-down-right-solid" | "heroicons:arrow-down-solid" | "heroicons:arrow-down-tray" | "heroicons:arrow-down-tray-16-solid" | "heroicons:arrow-down-tray-20-solid" | "heroicons:arrow-down-tray-solid" | "heroicons:arrow-left" | "heroicons:arrow-left-16-solid" | "heroicons:arrow-left-20-solid" | "heroicons:arrow-left-circle" | "heroicons:arrow-left-circle-16-solid" | "heroicons:arrow-left-circle-20-solid" | "heroicons:arrow-left-circle-solid" | "heroicons:arrow-left-end-on-rectangle" | "heroicons:arrow-left-end-on-rectangle-16-solid" | "heroicons:arrow-left-end-on-rectangle-20-solid" | "heroicons:arrow-left-end-on-rectangle-solid" | "heroicons:arrow-left-on-rectangle" | "heroicons:arrow-left-on-rectangle-20-solid" | "heroicons:arrow-left-on-rectangle-solid" ...
storageManager: 
function s3Storage(): StudioCMSStorageManagerDef
Creates and configures a StudioCMS S3 Storage Manager plugin.
This function initializes the S3 storage integration for StudioCMS by defining
a storage manager plugin with the necessary configuration and hooks.
@returns ― A configured storage manager instance that integrates
S3 storage capabilities with StudioCMS.
@example 
import { studiocmsS3Storage } from '@studiocms/s3-storage';

const s3Storage = studiocmsS3Storage();
s3Storage(),
    // other configuration options
})

For available storage manager plugins, see the Package catalog.