This is the official JavaScript/TypeScript SDK for Agility CMS's Web Studio.
Don't have an Agility CMS instance? Sign up for Free Trial today!
- Enable your website/app to use the new Web Studio features.
- Add the ability to collaborate and comment directly on your website/app.
- Empower your editors to preview content changes in real-time.
You'll need to have an Agility CMS instance to use this SDK. If you don't have one, you can sign up for a Free Trial today!
Once you have an Agility CMS Instance you will need to install the sdk from npm and add a script tag in your website.
<script src="https://unpkg.com/@agility/web-studio-sdk@latest/dist/index.js"></script>You can stop there if you'd like. But to get the most of the SDK, you'll need to decorate your components, fields, and pages with the data-agility-* attributes. This will allow the SDK to interact with your website/app, and enable real-time editing. You'll also need to add your guid as a data-agility-guid attribute to the body element of your website/app.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
</head>
<body data-agility-guid="YOUR_GUID">
<div data-agility-page="YOUR_PAGE_ID">
<header data-agility-component="YOUR_CONTENT_ID">
<h1 data-agility-field="title">{{fields.title}}</h1>
<p data-agility-field="content">{{field.content}}</p>
</header>
</div>
</body>
</html>The SDK uses the data-agility-\* attributes to interact with your website/app. Here are the attributes you can use:
-
data-agility-guid: This is the guid of your website/app. You can find this in the settings of your website in Agility CMS. The SDK uses this to know which instance your website/app is associated with.- Example:
<body data-agility-guid="YOUR_GUID"></body>
-
data-agility-previewbar: This is a boolean attribute that tells the SDK this is the preview bar element, and allows us to hide it using tailwind class. The SDK uses this to know that element should be hidden.- Example:
<div className="bg-agility relative px-8 text-gray-200" data-agility-previewbar > // your preview bar content </div>
-
data-agility-page: This is the id of the page in Agility CMS. The SDK uses this to know which page is being interacted with, so we can track navigations and other page-specific events in Web Studio.- Example:
<body> <main data-agility-page="YOUR_PAGE_ID"></main> </body>
-
data-agility-dynamic-content: This is the content id of the dynamic content in Agility CMS. The SDK uses this to know which dynamic content is being interacted with, so we can track dynamic-content specific events in Web Studio, allowing us to keep navigation and other information in sync.- Example:
<div data-agility-dynamic-content="YOUR_DYNAMIC_CONTENT_ID"></div>
-
data-agility-component: This is the id of the component in Agility CMS. The SDK uses this to know which component is being interacted with, so we can track component-specific events in Web Studio and enable real-time editing.- Example:
<header data-agility-component="YOUR_COMPONENT_ID"></header>
-
data-agility-nested-listitem: This is the content id of a list item inside a linked-content-list field. Use this instead ofdata-agility-componentfor list items that have no per-instance container of their own, so the SDK can still track and enable real-time editing for their fields.- Example:
<li data-agility-nested-listitem="YOUR_CONTENT_ID"> <h2 data-agility-field="title">{{fields.title}}</h2> </li>
-
data-agility-field: This is the name of the field in Agility CMS. The SDK uses this to know which field is being interacted with, so we can track field-specific events in Web Studio and enable real-time editing of their content.- Example:
<h1 data-agility-field="title">{{fields.title}}</h1>
-
data-agility-html: This is a boolean attribute that tells the SDK to treat the element as an HTML field. The SDK uses this to know that the field is an HTML field, so we can enable rich-text editing in Web Studio.- Example:
<div data-agility-field="blog-content" data-agility-html> {{fields.blog-content}} </div>
npm
npm install @agility/web-studio-sdk
yarn
yarn add @agility/web-studio-sdk
You will need to have an Agility CMS instance and a website that you can also run locally. In the root of your site, add the following script tag
<script src="http://127.0.0.1:8080/index.js"></script>-
Clone this repository
-
Run
npm install -
Run
npm run dev -
On the Sitemaps page in Agility CMS, add a preview deployment that points at where your website is running locally, usually
http://localhost:3000. -
Go to the Pages module in Agility CMS and click on the "Preview" button to see Web Studio in action.
Also here is a handy Regex that's useful for debugging frame events in the chrome dev tools console:
/^Web Studio (SDK|CMS)/Releases are published to npm automatically via GitHub Actions
(.github/workflows/npm-publish.yml) whenever a v* tag is pushed.
Steps:
-
Bump
versioninpackage.json, commit it, and merge tomain. -
Tag that commit and push the tag:
git checkout main && git pull git tag v1.0.26 git push origin v1.0.26
The workflow verifies the tag matches package.json's version, builds
(npm run build), and runs npm publish --access public. A version with a
prerelease suffix (e.g. 1.0.26-beta.1) publishes under that npm dist-tag
instead of latest.
Sites that load the SDK via
https://unpkg.com/@agility/web-studio-sdk@latest/dist/index.js (as shown
above) pick up a new release as soon as it's published - unpkg serves
directly from the npm registry, so there's no separate deploy step.
Auth: publishing uses npm's Trusted Publishing (OIDC) - there's no
NPM_TOKENsecret to manage. Configure a Trusted Publisher on npmjs.com for@agility/web-studio-sdkpointing at this repo and.github/workflows/npm-publish.yml.
For docs & help around Agility CMS, please see Agility CMS Documentation
If you would like to contribute to this SDK, you can fork the repository and submit a pull request. We'd love to include your updates.