🔄 This is the official Strapi v5 continuation of Cringe-Studio/strapi-auto-uuid
The original plugin only supports Strapi v4. This fork provides full Strapi v5 compatibility with new features and improvements.
A powerful UUID custom field plugin for Strapi v5 that automatically generates and manages UUID v4/v7 values for your content types.
- Auto-generation: Automatically generates UUID on entry creation
- UUID v4 & v7 Support: Choose between random (v4) or time-sortable (v7) UUIDs
- Uniqueness Validation: Prevents duplicate UUIDs across entries
- Copy to Clipboard: One-click copy button in the admin panel
- Admin Panel Management: Diagnose, auto-fix, and generate missing UUIDs
- Migration Support: Built-in tools to migrate from older versions
- Export/Import: Backup and restore UUID mappings
- Configurable: Extensive configuration options via
config/plugins.js - Per-field Options: Configure UUID version and prefix per field
npm install strapi-auto-uuid-v5
# or
yarn add strapi-auto-uuid-v5- Enable the plugin in
config/plugins.js:
module.exports = {
'field-uuid': {
enabled: true,
config: {
// Optional configuration (see Configuration section)
},
},
};-
Add the UUID field to your content type via Content-Type Builder:
- Go to Content-Type Builder
- Select your content type
- Click "Add another field"
- Choose "UUID" from Custom fields
-
That's it! UUIDs will be automatically generated for new entries.
Configure the plugin in config/plugins.js:
module.exports = {
'field-uuid': {
enabled: true,
config: {
// UUID version: 'v4' (random) or 'v7' (time-sortable)
defaultVersion: 'v4',
// Auto-generate UUIDs on create (default: true)
autoGenerate: true,
// Validate uniqueness before save (default: true)
validateUniqueness: true,
// Allow manual UUID editing in admin panel (default: false)
allowManualEdit: false,
// Maximum retry attempts for UUID collision (default: 3)
maxRetryAttempts: 3,
// Run auto-migration on bootstrap (default: false)
// Warning: This modifies data on server start
autoMigrate: false,
// Log level: 'debug', 'info', 'warn', 'error' (default: 'info')
logLevel: 'info',
},
},
};When adding a UUID field in Content-Type Builder, you can configure:
| Option | Description |
|---|---|
| UUID Version | v4 (random) or v7 (time-sortable) |
| Prefix | Optional prefix for all UUIDs (e.g., usr_) |
| Disable auto-generation | Require manual UUID input |
| Allow manual editing | Let users edit the UUID value |
| Private | Hide field from API responses |
- Completely random identifiers
- No ordering properties
- Best for: General purpose unique identifiers
- Time-based with millisecond precision
- Naturally sortable by creation time
- Best for: Database indexes, chronological ordering
Example:
v4: 550e8400-e29b-41d4-a716-446655440000
v7: 018f6b3c-8e2d-7f00-8000-000000000000
Access UUID management at: Settings > Auto UUID > UUID Management
- Dashboard: Overview of content types with UUID fields
- Diagnosis: Scan for duplicates, empty fields, and invalid UUIDs
- Auto-Fix: Automatically replace duplicate UUIDs
- Generate Missing: Create UUIDs for empty fields
- Export/Import: Backup and restore UUID mappings
All endpoints require admin authentication.
POST /api/field-uuid/check-duplicate
Body: { contentType, field, uuid, excludeDocumentId? }
GET /api/field-uuid/diagnose
POST /api/field-uuid/autofix
Body: { dryRun: boolean }
POST /api/field-uuid/generate-missing
Body: { dryRun: boolean }
GET /api/field-uuid/models
GET /api/field-uuid/migration/status
POST /api/field-uuid/migration/run
Body: { dryRun: boolean, fixEmpty: boolean, fixInvalid: boolean, fixDuplicates: boolean }
GET /api/field-uuid/migration/export
POST /api/field-uuid/migration/import
Body: { mappings: object, dryRun: boolean, overwrite: boolean }
GET /api/field-uuid/stats
The v5 version includes breaking changes to support Strapi 5. Here's how to migrate:
Change from:
// Old (Strapi 4)
module.exports = {
'strapi-auto-uuid': {
enabled: true,
},
};To:
// New (Strapi 5)
module.exports = {
'field-uuid': {
enabled: true,
},
};After upgrading, go to Settings > Auto UUID > UUID Management and click "Run Diagnosis" to check for any issues.
If duplicates or invalid UUIDs are found:
- Use the "Auto-Fix Duplicates" feature with "Dry Run" first
- Review the changes
- Run without dry run to apply fixes
- UUIDs are preserved: The underlying data type change from
uidtostringdoes not affect existing UUID values - Backup recommended: Always backup your database before running migrations
- Dry run available: All migration operations support dry run mode
Ensure the plugin is properly enabled:
- Check
config/plugins.jshas'field-uuid': { enabled: true } - Restart Strapi:
npm run develop
This usually means the plugin name in config/plugins.js doesn't match. Use 'field-uuid' (not 'strapi-auto-uuid').
Run the diagnostic tool:
- Go to Settings > Auto UUID > UUID Management
- Click "Run Diagnosis"
- Use "Auto-Fix Duplicates" to resolve
For large datasets:
- Set
validateUniqueness: falsein config (if uniqueness is ensured elsewhere) - Use database-level unique constraints
- Consider using UUID v7 for better index performance
Contributions are welcome! Please read our contributing guidelines and submit PRs.
MIT License - see LICENSE file for details.
- GitHub Issues: Report bugs
- Documentation: Full docs
This plugin is a Strapi v5 continuation of the original strapi-auto-uuid by Cringe Studio. Thanks for the great foundation!
- 🚀 Complete rewrite for Strapi v5
- ✨ Added UUID v7 support (time-sortable)
- 🎨 New admin panel with management tools
- 🔄 Migration support from Strapi v4
- 📦 Export/Import functionality
- ⚙️ Per-field configuration options
- 📋 Copy to clipboard button
- 🔧 Improved uniqueness validation
See Cringe-Studio/strapi-auto-uuid for Strapi v4 releases.