BCMS Logo

Working with Media

The Media manager in BCMS helps you manage all your visual and file assets - images, videos, documents, and more. You can upload, organize, rename, and delete files using folders, or access them programmatically via the BCMS SDK.

Uploading media

To upload a file:

  1. Go to the Media section in the sidebar.

  2. Click Upload File.

  3. Choose a file from your system or drag and drop it into the upload area.

15.jpg

Each uploaded media item is stored in its original form and, for images, automatically generates multiple resized versions to optimize delivery.

Using Folders

Folders help organize your files for better structure and retrieval.

  • Click Create new folder and provide a name.

  • If you’re inside another folder, the new folder will be nested within it.

  • Uploads respect the current folder path.

16.jpg

You can nest folders as deeply as you need, just like on a file system.

Renaming and Deleting Media

To rename a file:

  1. Hover over the media file and click the pencil icon.

  2. Enter a new name and save.

17.jpg

To delete a file or folder:

  1. Click the dropdown menu on the file/folder.

  2. Select Delete.

18.jpg

⚠️ Deleting media will remove it from all entries and widgets where it is used.

Media and <BCMSContentManager />

The <BCMSContentManager /> component supports rendering image nodes inside content. It automatically selects the optimal size for display based on the screen size.

Example:

import { BCMSContentManager } from '@thebcms/components-react';

<BCMSContentManager
  items={post.content.en}
  clientConfig={bcms.getConfig()}
/>

If the content includes an image (media type), BCMS will serve the most suitable image variant (e.g. small thumbnail, webp, or original size) depending on how the image is embedded in the entry.

Currently, only images are auto-rendered - videos, PDFs, and other types are not handled by <BCMSContentManager />.

Auto-generated sizes for images

When you upload an image, BCMS automatically generates multiple width-based versions to optimize performance across devices:

  • 350 px

  • 600 px

  • 900 px

  • 1200 px

  • 1600 px

  • 1920 px

These widths are based on the original image and are used to serve the most appropriate size depending on the context.

When rendering images using <BCMSImage />, the component will automatically choose the closest available version based on the size of the image on the page. This ensures optimal loading speed and image quality without any additional configuration.

Using a Dedicated Media API Key

Accessing media content requires API keys to be publicly used. So it's better to keep it separately from the API key you use to get the rest of the content.

Example media client:

import { Client } from '@thebcms/client';

export const bcmsMediaClient = new Client(
  process.env.NEXT_PUBLIC_BCMS_ORG_ID!,
  process.env.NEXT_PUBLIC_BCMS_INSTANCE_ID!,
  {
    id: process.env.NEXT_PUBLIC_BCMS_MEDIA_API_KEY_ID!,
    secret: process.env.NEXT_PUBLIC_BCMS_MEDIA_API_KEY_SECRET!,
  },
  {
    injectSvg: true, // Auto-inlines SVGs
  },
);

Benefits:

  • Granular permissions: Limit API key to only media access.

  • Separation of concerns: One key for entry/template logic, another for media.

  • Security: Even if exposed, media keys can't mutate other content types.

Working with Media via SDK

Get all media:

const allMedia = await bcms.media.getAll();

Get a single media file:

const media = await bcms.media.getById('media_id');

Get binary file buffer (e.g. image):

const file = await media.bin();

Get image thumbnail:

const thumbnail = await media.thumbnail();

Get public URI to a file:

const uri = bcms.media.toUri('media_id', 'filename.jpg', {
  webp: true,
});

Create a folder via API:

await bcms.media.createDir({ name: 'images', parentId: 'folder_id' });

Upload a file via API:

const uploadToken = await bcms.media.requestUploadToken();

await bcms.media.createFile({
  uploadToken,
  name: 'logo.png',
  file: yourFileBlob,
});

Conclusion

BCMS Media management provides a flexible and powerful way to store and serve visual assets. Use the dashboard for manual management or leverage the SDK to automate tasks. Don’t forget to use <BCMSContentManager /> for automatic image rendering in entry content and consider using a dedicated API key for optimized and secure media delivery.

PreviousGroups
NextProperties