Skip to content

docs: fix React 19 script-tag install, normalize package metadata, add AGENTS.md and context7.json - #8092

Open
martinjagodic wants to merge 4 commits into
mainfrom
chore/readme-metadata-agents
Open

martinjagodic wants to merge 4 commits into
mainfrom
chore/readme-metadata-agents

Conversation

@martinjagodic

Copy link
Copy Markdown
Member

Fixes setup snippets and metadata that people and AI coding agents copy from the README, npm and Context7.

Changes

1. Script-tag install in the decap-cms-app README (React 19)

The README loaded react@^18 UMD builds next to decap-cms-app. The current decap-cms-app peer-depends on React 19, and React 19 ships no UMD builds (https://cdn.jsdelivr.net/npm/react@19/umd/react.production.min.js returns 404). The old snippet as written is broken too: in Chrome it throws TypeError: Cannot read properties of undefined (reading 'S') and then DecapCmsApp is not defined.

  • The README now says decap-cms-app is for npm installs with a bundler (npm i decap-cms-app react react-dom).
  • For a script-tag install it points to the decap-cms bundle, which includes React and exposes window.CMS. The example uses window.CMS_MANUAL_INIT plus CMS.init(), matching the old snippet's manual init, and mentions window.h and window.createClass. All of these are set in packages/decap-cms/src/index.js.
  • The S3 media library is added to the list of extensions decap-cms-app leaves out. decap-cms registers it in src/extensions.js; decap-cms-app doesn't.

No other README or doc in this repo had the umd/react pattern.

2. package.json metadata (47 packages)

  • repository is now {"type": "git", "url": "git+https://github.com/decaporg/decap-cms.git", "directory": "packages/<dir>"} everywhere. Before, it was a /tree/main/... URL, or /tree/master/... for decap-cms-widget-richtext.
  • Existing homepages are kept: https://www.decapcms.org on decap-cms and decap-cms-app, and the per-widget docs anchors on the widgets. The 28 packages with no homepage now point at their README on GitHub.
  • bugs was already https://github.com/decaporg/decap-cms/issues everywhere.
  • Nothing else changed: no versions, dependencies, or catalog:/workspace: specifiers.

3. AGENTS.md

A short guide for coding agents, built from the root package.json scripts, pnpm-workspace.yaml, lerna.json, commitlint/husky, the CI and publish workflows, and CONTRIBUTING. It covers:

  • layout
  • commands
  • conventional commits
  • the pnpm catalog rule
  • the release process, including "never lerna publish"
  • where user docs live (decap-website, decapcms.org, /llms.txt, /llms-full.txt)

It links to CONTRIBUTING.md instead of repeating it.

4. context7.json

Context7 currently surfaces CONTRIBUTING and release internals as the top install snippets. This file uses only the fields in Context7's published schema (https://context7.com/schema/context7.json):

  • projectTitle, description
  • folders: ["packages"]. The root README is always included.
  • excludeFolders: .github, dev-test, cypress, scripts, __tests__, __fixtures__, __mocks__, dist, node_modules
  • excludeFiles: CHANGELOG, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, AGENTS, LICENSE, PR template
  • five short rules

No previousVersions.

5. Quick start link

https://www.decapcms.org/docs/quick-start/ is a meta-refresh page that forwards to /docs/basic-steps/. The root README and the decap-cms package README now link https://decapcms.org/docs/basic-steps/ directly.

Verification

  • Every CDN and docs URL kept or added returns 200 with curl: decap-cms@^3.0.0/dist/decap-cms.js (3.18.0), /docs/, /docs/basic-steps/, /llms.txt, /llms-full.txt.
  • I loaded the new script-tag snippet in Chrome from a local static server with a test-repo config:
    • With CMS_MANUAL_INIT, CMS.init() brings up the CMS.
    • CMS.registerPreviewTemplate with a template written using window.h renders in the preview pane.
    • Without the flag, it initializes on its own.
  • All package.json files parse.
  • pnpm install --frozen-lockfile --offline reports "Already up to date".
  • pnpm run test:package-integrity passes.
  • context7.json validates against Context7's JSON schema with ajv.
  • prettier --check passes on AGENTS.md and context7.json. The repo's lint and format scripts don't cover Markdown or JSON.

Note for the next release

lerna.json ignores *.md changes but not package.json changes. So the metadata commit marks every package as changed, and the next lerna version will bump all 47 packages, at least by a patch.

The decap-cms-app README loaded React 18 UMD builds next to a
decap-cms-app bundle that now expects React 19, which ships no UMD
builds. Pointed script-tag users at the self-contained decap-cms bundle
instead, kept decap-cms-app for bundler installs, and listed the S3
media library among the extensions it leaves out.
Every published package now declares its repository as the monorepo
git URL with a `directory`, instead of a GitHub tree URL (one of which
still pointed at `master`). Packages without a homepage get their
README on GitHub; existing decapcms.org homepages are kept.
AGENTS.md gives coding agents the layout, commands, commit format,
catalog rules and release process, linking to CONTRIBUTING.md for the
rest. context7.json points Context7 at the package READMEs and away
from changelogs, contributor docs, tests and CI files, and adds a few
usage rules.
https://www.decapcms.org/docs/quick-start/ is a redirect page that
forwards to /docs/basic-steps/. Link the target instead.
@martinjagodic
martinjagodic requested a review from a team as a code owner November 19, 2026 13:19
@netlify

netlify Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for decap-cms ready!

Name Link
🔨 Latest commit 733dbc5
🔍 Latest deploy log https://app.netlify.com/projects/decap-cms/deploys/6afef775c465ea060d1bdb3d
😎 Deploy Preview https://deploy-preview-8092--decap-cms.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@martinjagodic martinjagodic mentioned this pull request Nov 19, 2026
6 tasks done

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant