@stackbit/extensions

A collection of utilities, actions, and other helpers for implementing common Stackbit patterns.

Requirements

This package is intended to be used in a Stackbit project. In addition to Stackbit requirements, this project requires that you're using TypeScript.

Installation

Add as a dependency to your project:

npm install @stackbit/extensions

Note that if you aren't implementing in files used in the production application, this can be installed as a development dependency.

Extension Usage

The following extensions are available:

• getFieldValue
• ReactPreviewControls.PreviewUrl
• setRandomValue
• updateFieldValue

Utility Functions

Utility functions are typically used within another function.

getFieldValue

Extracts the value for a field from a document. This is useful for extracting the value of a field from a document, particularly when working with nested documents.

Usage:

getFieldValue(document: Document, fieldPath: Array<string | number>)

Parameters:

Name	Type	Description
document	Document	Parent document of the field
fieldPath	Array<string | number>	Path to the field of the parent document used to extract the value

Known Limitations:

• Has only been tested in a limited capacity, alongside the setRandomValue action.
• Does not support localization.

updateFieldValue

Updates a value for a field from a document, and stores the result in the content source. This is particularly useful when working with nested documents.

Usage:

updateFieldValue(options: UpdateFieldOptions)

Options:

Name	Type	Description
params	Parameters<CustomActionField['run']>[0]	Parameters sent to the action callback
fieldPath	Array<string | number>	Field path to update. If omitted, the current field path is used.
modelField	Field | FieldListItems	Field (from schema) to update. If omitted, the current field is used.
value	any	Value to set for the field.

Known Limitations:

• Has only been tested in a limited capacity, alongside the setRandomValue action.
• Does not support localization.

Custom Actions

Custom actions enable editors to trigger events within a specific context.

setRandomValue

Sets a random value for a field from a document, and stores the result in the content source.

Supported Contexts:

• Field

Usage:

setRandomValue(options = {}): CustomActionField

Options:

Name	Required	Type	Description
label	No	string	Label for the trigger button

Field Action Example:

import { setRandomValue } from '@stackbit/extensions';
import { ObjectModel } from '@stackbit/types';

export const ModelName: ObjectModel = {
  name: 'ModelName',
  type: 'object',
  fields: [{ type: 'string', name: 'title', actions: [setRandomValue()] }],
};

Preview Controls

Preview controls provide a way to hook into the preview DOM from the Stackbit editor.

Supported Frameworks

Because preview controls are client-side implementations, they are available in specific framework contexts. Each control is provided as a property within an object that controls all available controls for a given framework.

Supported Frameworks:

Framework	Object Name
React	ReactPreviewControls

Implementation

Preview controls are hooked into your application by importing from this application. They should be made available on any page you want to use them.

For example, in a Next.js application where you'd want a control available on every page, you'd likely want to implement in pages/_app.tsx (if using pages directory) or app/layout.tsx (if using app directory).

Next.js Configuration

Because the source code is written in TypeScript, Next.js typically requires an additional configuration to support TypeScript. Add this package to the transpilePackages option in your next.config.js file:

/** @type {import('next').NextConfig} */

module.exports = {
  transpilePackages: ['@stackbit/extensions'],
  // ...
};

PreviewUrl

Shows a link to the preview URL for the current page.

Supported Frameworks:

• React

Usage:

PreviewUrl(options: PreviewUrlOptions)

Options:

Name	Required	Type	Description
previewBaseUrl	Yes	string	Base URL of the preview website. This gets prepended to the current page path.
currentUrlPath	Yes	string	Current page path. This gets appended to the preview base URL.

React Example:

import { ReactPreviewControls } from '@stackbit/extensions';
import { AppProps } from 'next/app';
import { useRouter } from 'next/router';

export default function MyApp({ Component, pageProps }: AppProps) {
  ReactPreviewControls.PreviewUrl({
    currentUrlPath: useRouter().asPath,
    previewBaseUrl: 'https://www.example.com',
  });

  return (
    <>
      <Component {...pageProps} />
    </>
  );
}