🧑🏼‍🏭 Don't mind us, we are still working on this site using NotionCMS! Like this project? Sponsor us on GitHub: ⚡️⚡️⚡️ Get Started ⚡️⚡️⚡️
⏳: ~1 min read.
🗺️: current location: /notion-cms/plugins/core-plugins/images

Core plugin: ncms-plugin-images

Hate when your Notion images disappear? I used to.

Hate when your Notion images disappear? I used to.

By default the Notion API set’s the AWS authorization timeout to about an hour. So the naive will use the API for their project, and it seems to work but after deploying you find out that the url to the image is no longer valid! Oh!

So our solution is to download the images, cache them and replace the urls with a stand-in url and this plugin does this automatically when using NotionCMS. The plugin currently doesn’t support keeping the original name of the image file but we may add that in the future because it can be important for SEO.


This is a core plugin so import it from the @agency-kit/notion-cms package like so:

import NotionCMS, { Images } from '@agency-kit/notion-cms'

new NotionCMS({
  databaseId: '...your db',
  notionAPIKey: process.env.YOUR_KEY,
  plugins: [


  globalExtension = 'webp',
  compression = 80,
  imageCacheDirectory = './public',
  customMatchers = [],

We use sharp behind the scenes so look at their docs if you are curious.

globalExtension string

By default everything is converted to webp extension. You can change this to either png or jpg or see Sharp docs for more options.

compression number

This should be a value between 1-100 that represents the amount of compression the images get. Set to 100 for no compression at all.

imageCacheDirectory string

Relative path to the directory you want to stash your images and cache manifest in.

customMatchers Array<Regex>

These Regular Expressions will be used to match against to determine if something is an image url that you want to cache and replace. We currently use these (no matter what you put in this option):

const matchA = /\b(https?:\/\/[\w_#&?.\/-]*?\.(?:png|jpe?g|svg|ico))(?=[`'")\]])/ig
const matchB = /<img[^>]*src=['|"](https?:\/\/[^'|"]+)(?:['|"])/ig

See the source here if you want: https://github.com/agency-kit/notion-cms/blob/main/src/plugins/images.ts

we make notionware. 2023 \c\