Development
Monorepo
The repository is an Nx monorepo with these projects:
plugin: thepayload-crowdin-syncpackage published to npm.document: workspace librarypayload-localized-fields— Payload field walks used by the plugin and by other import/export plugins in this repo.adapters: workspace librarypayload-localization-adapters— vendor-neutralSourceWriter/TranslationReadercontracts. Phrase and Lokalise plugins in this monorepo will depend on it.dev: a Payload install that uses the plugin, for integration tests. Tests that need a different plugin config passpluginOptionsOverridetoinitPayloadInt.docs-site: this documentation site.tools: build scripts (vendor workspace libraries into the plugin tarball, rewrite published entrypoints).
How document/, adapters/, and plugin/ call each other, and what a "document slice" is, is in packages.
Build
In the root of the repository:
nx build plugincompiles TypeScript todist/plugin. That output still imports the workspace libraries by package name.nx run plugin:packagethen copies compileddocument/andadapters/intodist/plugin/vendor, rewrites those imports, and pointspackage.jsonat.js/.d.ts. That is the layout published to npm.nx build document/nx build adapterscompile the workspace libraries.nx build plugin --watchrebuilds when files change.nx run plugin:native-esmrunsplugin:package, then loads that tarball layout with Node's native ESM resolver.documentandadaptersnative-esm targets still check those libraries in isolation.
Lint
nx lint pluginnx lint dev
Test
Tests use Vitest. In the root of the repository:
npm run testruns all tests.npm run test:coverageruns all tests with coverage. Reports are written tocoverage/<project>.nx test pluginruns plugin unit tests only.nx test documentrunspayload-localized-fieldsunit tests.nx test adaptersrunspayload-localization-adaptersunit tests.nx test toolsruns tests for the vendor and entrypoint scripts.nx test devruns integration tests against the Payload install.
Plugin unit tests (*.spec.ts) sit next to the code they test in plugin/src. payload-localized-fields specs sit in document/src. Writer/reader specs sit in adapters/src. Payload field walks and the json/html document slice (getLocalizedFields, traverseFields, restoreOrder, buildJsonObject, buildHtmlObject, buildUpdateObject) live in the payload-localized-fields library (document/). Vendor-neutral upload/download orchestration (syncDocumentSource, applyDocumentSlice) lives in payload-localization-adapters (adapters/). Crowdin wrappers and rich-text HTML conversion stay in plugin/src/lib/utilities/. The Crowdin plugin re-exports the adapter contracts.
Integration tests (*.test.ts) are in dev/src/tests. They use Payload's Local API against a real Payload install with an in-memory MongoDB database. Calls to the Crowdin API are intercepted with nock, so tests check which requests the plugin makes without needing a Crowdin account.
To start Payload with a different plugin config, pass pluginOptionsOverride to initPayloadInt. The override is shallow-merged over the default test options, so { collections: undefined } replaces the default collections list. Pass the same override to pluginConfig when setting up Crowdin mocks.
CI runs npm run test:coverage and uploads the results to Codecov. Plugin coverage also includes document/src and adapters/src so Crowdin wrapper specs still count hits on the shared libraries. This needs the CODECOV_TOKEN repository secret.
Import maps
Payload finds custom admin components through an import map. After changing admin components in dev/, regenerate it:
npm run generate:importmaps
CI fails if the committed import map is missing or out of date.
Running the integration tests can overwrite dev/src/app/(payload)/admin/importMap.js with an empty map. Restore it with git restore before committing.
Run a Payload install locally
cd dev
npm run dev
A local install is useful for trying out changes in the admin panel, and for generating fixtures for integration tests.