The source of the two npm packages that DatoCMS plugins are built with.
| Package | Source | Docs |
|---|---|---|
datocms-plugin-sdk |
packages/sdk |
Plugin SDK documentation · changelog |
datocms-react-ui |
packages/react-ui |
Component docs · README · changelog |
The SDK connects a plugin to DatoCMS. The React components give a plugin the look of the DatoCMS interface.
This repository is a copy of a private repository, and each release replaces its content. Pull requests are welcome, but we do not merge them here: see Contributing.
| Branch | Holds | On npm |
|---|---|---|
master |
Version 3 of both packages, a prerelease | npm install datocms-plugin-sdk@next datocms-react-ui@next |
2.x |
datocms-react-ui 2.x |
npm install datocms-react-ui |
A plain npm install gets version 2 of both packages. If your plugin uses version 2 of datocms-react-ui, read its source on the branch 2.x, not here. The SDK is developed only on master: the branch 2.x does not have it.
You do not need this repository to build a plugin. Start from the Plugin SDK documentation: it has the guides, the API reference, and the plugin template, which already installs both packages.
packages/sdk: the SDK.ARCHITECTURE.mdexplains how a plugin talks to DatoCMS.packages/react-ui: the component library.src/has the adapter between the components and thectxof a plugin:Canvas,useCtx, andContextInspector.bin/builds the output.packages/ui-public: the components themselves. The build of react-ui bundles them into the package. Only the modules that react-ui ships are here.
The source of a component is in packages/ui-public, not in packages/react-ui. To find the file behind datocms-react-ui/Button:
packages/react-ui/entries.mjslists the public entries. It mapsButtontoui-public/Button.- The
exportsofpackages/ui-public/package.jsonmap./Buttontosrc/actions/Button.tsx.
The CSS of the components is in packages/ui-public/styles.
You need Node 24 (see .nvmrc).
git clone https://github.com/datocms/plugins-sdk && cd plugins-sdk
npm ci
npm run build # the SDK first, then react-ui: react-ui reads the types of the SDK
npm test # the tests of the SDK
npm run tsc # the types of the three packages
npm run lint # the lint of the three packages
npx biome ci . # the formatThese are the commands that the CI runs. npm run format fixes what npx biome ci . reports.
For the SDK, one script builds the package and copies it over the copy that the plugin has installed:
cd packages/sdk
INSTALL_PATH=/path/to/my-plugin npm run install-in-placeFor react-ui, pack the build and install the tarball in the plugin:
cd packages/react-ui
npm pack --pack-destination /tmp
cd /path/to/my-plugin
npm install /tmp/datocms-react-ui-*.tgzIf the plugin uses Vite, restart its dev server with --force after each install: Vite keeps a cache of the dependencies.
To go back to the versions of npm, run this in the plugin. For react-ui, first put the version back in its package.json:
rm -rf node_modules/datocms-plugin-sdk node_modules/datocms-react-ui node_modules/.vite && npm installReport a bug or ask for a feature in the issues of this repository. For a question about your own plugin or your project, write to our support team.
Pull requests are welcome, with one difference from most repositories: we do not merge them here. This is how a change gets in:
- Open a pull request to
master. The CI installs, builds, tests, and lints it, so run the commands of Build first. - A maintainer reviews it and applies your commits to the private repository, with you as their author.
- The next release brings the change to
master, and the pull request closes.
Things to know:
- Open an issue before a large change. The CMS uses the same components, so a change to a component also changes the CMS. We can tell you early if it fits.
- You do not add a changeset or change a version. The maintainer does it.
- A fix for
datocms-react-ui2.x goes to the branch2.x, with a pull request to that branch. - Some files are generated, and a change to them does not apply as it is: the files at the root of the repository, the
package.jsonof each package, andpackages/ui-public/tsconfig.json. Say in the pull request what you need, and a maintainer changes the source.
DatoCMS develops these packages in a private repository, together with the CMS, which uses the same components. At each release, a script copies here the files that the npm packages are built from, and replaces the whole content of master. A check makes sure that the build of master is the same, file for file, as the build in the private repository. What you build here is what npm has.
Some comments point to a file of the private repository, such as an AGENTS.md file. These files are not here.
MIT, see LICENSE.md.
Source commit: 522da2dd11c1c776cdbceab9f1d2d890da605c22