@agility/app-sdk
v2.5.0
Published
JavaScript library for building Agility CMS apps.
Keywords
Readme
Agility CMS App SDK
Build your own UI inside Agility CMS.
@agility/app-sdk lets you drop a React app straight into the Agility CMS interface — as a
custom field, a sidebar, a dashboard, a modal, or a button in the rich text editor. Your app
runs on your own infrastructure and talks to the CMS through a small, typed API.
import { useAgilityAppSDK, contentItemMethods } from "@agility/app-sdk"
export default function StarRating() {
const { initializing, fieldValue } = useAgilityAppSDK()
if (initializing) return null
return (
<div>
{[1, 2, 3, 4, 5].map((n) => (
<button key={n} onClick={() => contentItemMethods.setFieldValue({ value: `${n}` })}>
{n <= Number(fieldValue) ? "★" : "☆"}
</button>
))}
</div>
)
}That's a working custom field. The content editor sees stars; Agility stores the value like any other field.
Why apps
Agility's content model covers the general case. Apps cover your case — the field type, the integration, or the workflow shortcut your editors actually need.
- Ship on your own stack and schedule. Your app is your app: your repo, your framework, your deploys. No Agility release is in your way.
- Only build the surfaces you want. One custom field is a complete, publishable app.
- The editor never leaves the CMS. No tab-switching, no copy-pasting IDs between tools.
- Real CMS access when you need it. Ask the host for a Management API token, scoped to the signed-in user's own permissions, and use the Management SDK.
- Private or public. Keep an app to your own organization, or list it on the Agility App Marketplace.
What you can build
| Surface | Where it appears | Typical use | |---|---|---| | Custom field | inside the content form | a colour picker, a product selector, a map input | | Content item sidebar | beside an open content item | SEO scoring, translation, approvals | | Content list sidebar | beside a content list | bulk actions over the selected rows | | Page sidebar | beside a page | preview links, analytics for that URL | | Dashboards | Home, Content and Pages sections | analytics, team to-dos, shortcuts | | Modal | a dialog over any surface | a picker or wizard launched from your own app | | RTE toolbar | the rich text editor toolbar | custom embeds — callouts, flip cards, charts — or plain links | | Section | its own entry in the main navigation, full-pane | a file library, a dashboard of your own, an admin screen | | Report | an entry in the Reports section, under a group heading you choose (your app's name by default), full-pane | usage, audit or sync reports about your app's data | | Stack item | on the item stack, with its own breadcrumb and back button | one folder or record, opened from your section or on top of a content item | | Install screen | during installation | OAuth connect, account pickers |
Installation
npm install @agility/app-sdk
# or
yarn add @agility/app-sdkReact 18 and react-dom 18 are peer dependencies — your app supplies them.
Most apps also want the Management SDK, for reads and writes beyond the current item:
npm install @agility/management-sdkHow it works
Your app is a normal web app that you host. Agility loads it in an <iframe> and the two
sides talk over postMessage; this SDK is the client end of that conversation.
┌──────────── Agility Manager App ────────────┐
│ │
│ ┌────── your app (iframe) ──────┐ │
│ │ useAgilityAppSDK() ──init──►│ │
│ │ ◄─context│ │
│ │ getContentItem() ──req───►│ │
│ │ ◄─reply──│ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────────────┘Three consequences worth knowing up front:
- Nothing works outside the iframe. Every method needs the
?appID=that Agility puts on the URL. Opened directly in a browser tab, the SDK stays inert by design. - Each surface is a route. A custom field named
productmust be served at/fields/product; a modal namedpickerat/modals/picker. See the route table. - Not every method works on every surface.
saveContentItem()means nothing on a dashboard. The availability matrix is the fastest way to avoid the most common bug in app development.
Quick start
1. Declare what your app provides
Serve a manifest at {yourAppUrl}/.well-known/agility-app.json. Include only the
surfaces you implement, and make sure CORS allows Agility to fetch it.
{
"name": "Star Rating",
"version": "1.0.0",
"__sdkVersion": "2.0.0",
"configValues": [],
"capabilities": {
"fields": [
{ "name": "star-rating", "label": "Star Rating", "description": "Rate from 1 to 5." }
]
}
}2. Serve a route for each surface
With Next.js App Router, the manifest above needs one page:
app/fields/star-rating/page.tsx3. Call the hook
"use client"
import { useAgilityAppSDK } from "@agility/app-sdk"
export default function Page() {
const { initializing, field, fieldValue, contentItem } = useAgilityAppSDK()
if (initializing) return null // always wait for this
return <div>{field?.label}: {fieldValue}</div>
}4. Register and install
Register the app against your Agility organization, pointing it at your public base URL, then install it on an instance. See Creating Apps for Agility for the registration walkthrough.
Documentation
| Guide | What's in it | |---|---| | Surfaces | Every surface, its route, its context, and the operation availability matrix | | API Reference | Every hook, method and type | | Architecture | The protocol, the correlation mechanism, and the trust model | | Troubleshooting | Symptom-first fixes for the failure modes apps actually hit | | Contributing | Adding an operation, and the release process |
Official product docs: agilitycms.com/docs/apps
Example apps
The best way to learn the SDK is to read a working app:
- Google Analytics — a dashboard app using OAuth to pull Analytics data
- Google Translate — a sidebar app that translates and detects the language of the current content item
- BigCommerce — a custom field that selects a product, including a modal with a searchable product list
Local Development
To develop this SDK and test it in another project:
Step 1: Clone and install
git clone https://github.com/agility/agility-cms-app-sdk.git
cd agility-cms-app-sdk
yarn installStep 2: Build
yarn buildCleans, compiles and bundles into dist/.
Step 3: Link
cd agility-cms-app-sdk
yarn linkThen in your project:
cd your-project
yarn link "@agility/app-sdk"Step 4: Watch for changes
cd agility-cms-app-sdk
yarn watchAvoiding duplicate React
React is a peer dependency and is never bundled, so your project supplies it. Linking can
still sidestep that and load React twice, which breaks hooks with
Invalid hook call. With Next.js, force a single copy in next.config.js:
webpack: (config) => {
config.resolve.alias = {
...config.resolve.alias,
react: path.resolve(__dirname, "node_modules/react"),
"react-dom": path.resolve(__dirname, "node_modules/react-dom")
}
return config
},As long as your project provides a compatible React version, nothing else is needed.
Unlinking
cd your-project && yarn unlink "@agility/app-sdk"
cd agility-cms-app-sdk && yarn unlinkSupport
- Issues: github.com/agility/agility-cms-app-sdk/issues
- Community: Agility CMS Slack
- Support: help.agilitycms.com
- Docs: agilitycms.com/docs
