@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

$3

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:

``ts
getFieldValue(document: Document, fieldPath: Array)
`

Parameters:

| Name | Type | Description |
| ----------- | ------------------------- | ------------------------------------------------------------------ |
| document | Document | Parent document of the field |
| fieldPath | Array | 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:

`ts
updateFieldValue(options: UpdateFieldOptions)
`

Options:

| Name | Type | Description |
| ------------ | ----------------------------------------- | --------------------------------------------------------------------- |
| params | Parameters[0] | Parameters sent to the action callback |
| fieldPath | Array | 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.

$3

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:

`ts
setRandomValue(options = {}): CustomActionField
`

Options:

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

Field Action Example:

`ts
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()] }],
};
`

$3

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:

`js
/* @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:

`tsx
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:

`tsx
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 (
<>


);
}
``