Instagram widget compatible with the apostrophe cms

Usage no npm install needed!

<script type="module">
  import kwsitesCmsInstagramWidgets from 'https://cdn.skypack.dev/@kwsites/cms-instagram-widgets';



Instagram widget compatible with the apostrophe cms

Getting Started

Install with npm i @kwsites/cms-instagram-widgets or yarn add @kwsites/cms-instagram-widgets.

Ensure your application also has a dependency on @kwsites/cms-common, which provides the less plugins used by this library to generate its theme.

Add both libraries to your app.js:

// app.js
  modules: {
    '@kwsites/cms-common': {},
    '@kwsites/cms-instagram-widgets': {
      embed: { source: '...', token: '...' },
      auth: { /* see authentication below */ }

To use the widget in an area:

<!-- in any template.html -->
      widgets: {
        "@kwsites/cms-instagram": {


Periodically instagram will require that a valid Instagram account has logged into the site for the IP and "device" to show profile data. To manage the interaction with Instagram, this library uses instagram-private-api. Configure your account username/password using one of the options below:

With source=inline, the username and password are used as-is from the module's configuration in app.js:

To be able to reliably fetch oembed data from instagram, you should follow the steps on https://developers.facebook.com/docs/instagram/oembed/ to create a Facebook app then supply the app's access token using the embed configuration property - either supplying the token itself (when source=inline) or the name of the environment variable to look up (when source=env).

const config = {
  auth: { source: 'inline', user: 'USERNAME', pass: 'PASSWORD' },
  embed: { source: 'env', token: 'OEMBED_TOKEN' }

With source=env, the username and password are read from the named environment variables:

process.env.IG_USER = 'USERNAME';
process.env.IG_PASS = 'PASSWORD';
const auth = { source: 'env', user: 'IG_USER', pass: 'IG_PASS' };
// set your auth options in the app.js configuration of the module
apostrophe({ modules: { '@kwsites/cms-instagram-widgets': { auth, embed } } });

For a completely custom way to deliver your credentials, extend the module:

apostrophe({ modules: { '@kwsites/cms-instagram-widgets': {
   construct (self, options) {
      // override the validation logic,
      // returning a non-empty string is deemed a validation failure
      self.validateAuthConfig = (req) => '';

      // get the username and password as a string array
      self.getApiAuth = () => ['USERNAME', 'PASSWORD'];
 } } });

Configuration Options

Options passed into the module configuration in your app.js:

  • auth: { source: 'inline' | 'env'; user: string; pass: string } sets the source of your instagram authentication credentials, can be omitted entirely to fetch as a guest (note that guest access will likely not work in production due to rate limiting etc)

  • cacheTTL: number = 86400 sets the duration (in seconds) a profile gallery should be cached before re-fetching

  • cacheEnabled: boolean = true optionally disable the ability to cache profile galleries

  • errorTTL: number = 1200 sets the duration (in seconds) to wait before reattempting to load a profile gallery that returned an error.

  • embed: { source: 'inline' | 'env'; token: string } configure the instagram oembed app token to pass to instagram on request

  • offline: boolean optionally disable the gallery view by setting offline to true

Offline Mode

Set the global apos.options.locals.offline to true by adding offline: true to your data/local.js to prevent attempting to fetch profiles remotely, useful when working offline to return early rather than attempt to connect to the remote instagram server.


At the time of publishing, Apostrophe CMS doesn't automatically support @scoped/ dependency modules, which causes an error when the CMS starts up and is unable to symlink the source of the modules into the /public folder correctly.

To resolve this, you need to manually create the directory /public/modules/@kwsites before starting the server. To have this run automatically after installing dependencies, add the following to your package.json scripts block:

  "scripts": {
    "postinstall": "mkdir -p ./public/modules/@kwsites"


This library uses debug to manage its logging, enable the log by running your application with the DEBUG environment variable:

$ DEBUG=@kwsites/cms-instagram-widgets:* node app.js

Alternatively, set the verbose option for this module in your app.js:

// app.js
  modules: {
    '@kwsites/cms-common': {},
    '@kwsites/cms-instagram-widgets': { verbose: true },