UUIDs that stay put

Features

One custom field, enforced on the server for every write path, plus an admin page to check and repair what is already stored.

Install

Requires Strapi 5.24 or newer (acceptance host: Strapi 5.61.0) and Node.js 22.12 or newer. A fresh Strapi app installs it with npm, Yarn 1 or pnpm without a single peer dependency warning from this package.

1. 1

   Add the package

   Terminalnpm, yarn or pnpm

   npm install strapi-auto-uuid-v5

2. 2

   Enable it

   config/plugins.ts

   export default () => ({
     'field-uuid': {
       enabled: true,
     },
   });

   JavaScript projects use config/plugins.js with module.exports = { 'field-uuid': { enabled: true } };

3. 3

   Add the custom field

   Run npm run build && npm run develop. In the Content-Type Builder choose Add another field, Custom, UUID, pick v4 or v7, and save an entry.

Super Admins see Settings > Auto UUID > UUID management right away. Other roles need the permissions listed under Security.

Examples

A content type ticket with a v7 field ticketId and the prefix tkt_. All values are synthetic.

"ticketId": {
  "type": "customField",
  "customField": "plugin::field-uuid.uuid",
  "unique": true,
  "options": { "uuid-version": "v7", "uuid-prefix": "tkt_" }
}

// request
{ "data": { "title": "Printer offline" } }

// response
{
  "data": {
    "documentId": "k2v8q4n6x0c1m3b5z7l9p2r4",
    "title": "Printer offline",
    "ticketId": "tkt_019a5f3c-8b2e-7d41-9c3a-5e2f1b7a4d10"
  },
  "meta": {}
}

const ticket = await strapi.documents('api::ticket.ticket').create({
  data: { title: 'Printer offline' },
});
strapi.log.info(ticket.ticketId); // tkt_019a5f3c-...

{
  "data": null,
  "error": {
    "status": 400,
    "name": "ValidationError",
    "message": "UUID already exists for field 'ticketId'. Please use a unique value.",
    "details": { "field": "ticketId", "code": "DUPLICATE_UUID" }
  }
}

Other codes: INVALID_UUID, IMMUTABLE_UUID, BULK_UUID_WRITE, INVALID_UUID_FIELD_CONFIG and UUID_TARGET_UNKNOWN.

How values are protected

The plugin's lifecycle hooks apply these rules to every write, whatever the source.

A localized UUID field has its own value per locale; a non-localized one is shared by all locales of a document. UUID fields inside components are filled by the admin only; the server does not generate, validate or repair them.

Gallery

The admin screens follow the Strapi Design System, in light and dark mode and on small screens. All screenshots use synthetic data.

Configuration

Plugin defaults go under the field-uuid key in config/plugins.js or .ts. All keys are optional; unknown keys and wrong types fail at boot.

Field options

Security, privacy and permissions

The plugin has no Content API routes. Its management routes need an admin JWT and a plugin permission, checked on the server.

• Request bodies are validated with strict zod schemas; unknown keys are rejected.
• Errors never contain stack traces, database errors or stored values. Logs record the admin id for repairs, exports and imports, never values or IP addresses.
• Rate limits per admin and minute; with the database store they hold across all instances. Keys are SHA-256 hashes.
• No outbound network requests, no telemetry, no analytics and no license check.

Report vulnerabilities privately through GitHub security advisories.

Admin API

Admin routes under /field-uuid. Write routes default to a preview; send "dryRun": false to write.

Status codes: 400 invalid body, 401 no admin login, 403 missing permission, 409 REPAIR_IN_PROGRESS while another repair or import runs on any instance, 429 rate limit. Only the export contains documentIds and UUID values.

// request
{ "fixEmpty": true, "fixDuplicates": true, "fixInvalid": true }

// response (dryRun defaults to true, nothing is written)
{
  "dryRun": true,
  "fixed": { "empty": 3, "invalid": 0, "legacy": 0, "duplicates": 1 },
  "skipped": 0,
  "errors": [],
  "totalFixed": 4
}

Performance

Checks and exports read rows in pages of 5,000 and select only the columns they need. Imports look up 500 entries per query batch. On SQLite with about 5,000 synthetic entries, the overview scan took 40 ms and a 5,000-value import 315 ms.

Each save looks up the UUID column a few times. For large tables, add an index with a Strapi database migration:

'use strict';

const INDEXES = [['tickets', 'ticket_id']];

async function up(knex) {
  for (const [table, column] of INDEXES) {
    if (!(await knex.schema.hasTable(table)) || !(await knex.schema.hasColumn(table, column))) {
      continue;
    }
    await knex.schema.alterTable(table, (t) => t.index([column], `${table}_${column}_uuid_idx`));
  }
}

module.exports = { up };

Running several instances (Railway replicas, pm2 cluster)

Tested with 8 Node processes on one PostgreSQL 16 database (for example 2 Railway replicas with 4 pm2 workers each). The database is the only shared state.

• PostgreSQL is recommended. MySQL 8 and MariaDB (InnoDB) are supported but not yet tested live. SQLite means one process.
• The database user must be allowed to create the plugin tables at startup, as for Strapi's own schema sync.
• Size the pool for all processes: processes x pool.max must stay below max_connections.
• After a rolling deploy that adds a UUID field, run Check and Repair all once when every replica is up.

Compatibility

Required peers are the ones in the Strapi app template (@strapi/strapi, react, react-dom, react-router-dom, styled-components). @strapi/design-system, @strapi/icons and react-intl are optional peers because Strapi installs them itself.

Upgrading

2.1 needs no changes except, with several processes, create-table rights for the database user. The 2.0 migration from 1.x is stricter:

From Strapi 4: rename the plugin key from strapi-auto-uuid to field-uuid, run the check, export a backup, then repair if needed.

FAQ

Releases and contributing

Conventional Commits and semantic-release on pushes to main. Every release runs lint, format check, tests (including lifecycle and repair tests on a real SQLite database), build and package verification, then publishes to npm with provenance. Pull requests also run the PostgreSQL and 8-process tests on Node.js 22 and 24.

npm ci --legacy-peer-deps
npm run lint
npm run format:check
npm test
npm run test:concurrency
npm run build
npm run verify