Skip to main content

Repository

Notes for contributors and maintainers. To use the plugin, start with getting started.

Layout​

  • plugin/: the payload-crowdin-sync package published to npm.
  • document/: the payload-localized-fields package — walk localized Payload fields for import, export, or translation plugins.
  • adapters/: the payload-localization-adapters package — writer/reader contracts for a json/html document slice. Phrase and Lokalise plugins will live alongside this.
  • dev/: Payload install used for integration tests.
  • docs-site/: this documentation site, built with Docusaurus and published to GitHub Pages.

The repository is an Nx monorepo. See Nx for general Nx commands.

Scripts​

npm install
npm run test                 # unit and integration tests
npm run test:coverage        # the same, with coverage reports in coverage/<project>
npm run generate:importmaps  # regenerate the Payload import map in dev/
npm run docs:serve           # run this site locally

See development for how the tests are organised, and why import maps matter.

Continuous integration​

On every pull request and push to main, CI:

  • checks that the Payload import map is committed and up to date
  • runs all tests with coverage
  • uploads coverage to Codecov and keeps the reports as a build artifact for 14 days

See PR labels for how pull requests are labelled.

Release​

Releases are managed by release-please. Packages in release-please-config.json (. / source, plugin / payload-crowdin-sync, document / payload-localized-fields, adapters / payload-localization-adapters, dev) share one chore: release main PR. Changelog files live next to each package (plugin/CHANGELOG.md, document/CHANGELOG.md, adapters/CHANGELOG.md, dev/CHANGELOG.md) — changelog-path is relative to the package directory, not the repo root. Do not add text above the :robot: marker in a release PR body; that prevents GitHub releases from being created and blocks later release PRs.

When a release PR is merged to main, the release-please workflow tags payload-crowdin-sync-vX, payload-localized-fields-vX, payload-localization-adapters-vX, source-vX, and dev-vX, then builds and publishes the public packages to npm via trusted publishing (OIDC).

First publish of a new package must be manual (cd dist/<package> && npm publish --access public); trusted publishing cannot create the package. After nx build <package>, run node tools/scripts/rewrite-dist-entrypoints.mjs dist/<package> so the tarball points at compiled .js rather than the workspace ./src/index.ts entry. Then, on npmjs.com, payload-localized-fields, and payload-localization-adapters, go to Settings > Trusted publishing and add a GitHub Actions publisher for repository thompsonsj/payload-crowdin-sync and workflow filename release-please.yml. After verifying automated publishes work, revoke the NPM_TOKEN repository secret. Plugin publish fails until payload-localization-adapters at the version in plugin/package.json exists on npm (or is published earlier in the same job). Do not ship the plugin while that dependency is still 0.0.0.

Manual publish remains available as a fallback:

npm run release

Other notes​