npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@agility/app-sdk

v2.5.0

Published

JavaScript library for building Agility CMS apps.

Readme

Agility CMS App SDK

npm version license

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-sdk

React 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-sdk

How 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:

  1. 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.
  2. Each surface is a route. A custom field named product must be served at /fields/product; a modal named picker at /modals/picker. See the route table.
  3. 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.tsx

3. 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 install

Step 2: Build

yarn build

Cleans, compiles and bundles into dist/.

Step 3: Link

cd agility-cms-app-sdk
yarn link

Then in your project:

cd your-project
yarn link "@agility/app-sdk"

Step 4: Watch for changes

cd agility-cms-app-sdk
yarn watch

Avoiding 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 unlink

Support

License

MIT