Contentful Migration Scripts: Automate Your Data Move

What the Contentful Migration Tool Does

Contentful's open-source migration library (github.com/contentful/contentful-migration, 344 stars, 1,232 commits) handles model and entry transformations programmatically.

It lets you:

• Create or edit content types and fields
• Transform existing entries (batch updates, field renames, type conversions)
• Derive linked entries and cross-references
• Retry failed operations automatically
• Chain operations in a declarative, reproducible format

When to script vs. when to hire help

DIY script migration works best if:

• Your data is less than 500K records
• Content model is relatively flat (few nested references)
• You have 1-2 team members who can code Node.js or Python
• You have 3-5 days to work on it

Consider a professional migration service if:

• You have 1M+ records with complex nested structures
• You rely heavily on Contentful-specific workflows or custom apps
• Your data has edge cases or legacy inconsistencies
• Downtime costs are high (ecommerce, live platforms)
• You need it done in less than 2 days

Contentful to Directus: Field Mapping and Query Syntax

Field Types: Direct Mapping

Most Contentful field types map 1:1 to Directus:

Linked Entries: From References to Foreign Keys

Contentful (REST API):

Entry with linked author reference stored as nested object with sys.id.

Directus equivalent:

Simple foreign key field: author_id = "author-123". In your transform script, extract the sys.id and map it directly.

Locales: Translation Tables

Contentful approach: One entry document per language, linked by contentId.

Directus approach: One record in the main collection plus rows in a translations table. Set default language in Directus settings. Store translations in directus_translations or a custom table. Query with ?filter[language_code][eq]=fr to fetch French content.

Query Syntax: REST and GraphQL

Contentful REST:

GET /spaces/{space}/environments/{env}/entries?content_type=blog-post&limit=100

Directus REST:

GET /items/blog_posts?limit=100&fields[]=.

Directus GraphQL:

Query blog_posts with nested relationships and translations automatically included.

Migration Script Patterns: Extract, Transform, Load

1. Extract from Contentful Management API

Use the contentful npm package or contentful-migration CLI to pull your space. Authenticate with management token. Fetch all entries, content types, and assets. Save to JSON for processing.

Key pattern: Batch requests to respect API rate limits. Contentful free tier allows ~1 request/second. Enterprise plans go higher but you'll still hit limits on large migrations.

2. Transform: Map Fields and Locales

Loop through Contentful entries and build Directus-compatible objects. For each Contentful field:

• Extract the locale value (Contentful stores fields as {"en-US": value, "fr-FR": value})
• Map to Directus field type
• Create translation records for non-default locales

Handle linked entries by extracting the sys.id and creating a foreign key. If you have many-to-many relationships, create a junction table and populate it during transform.

3. Load into Directus

Use Directus REST API (/items/collection_name) or GraphQL mutations. Push data in batches to avoid timeouts (typically 100-500 records per request). Include retry logic for transient failures.

Pattern: Check total record count before and after. If Directus count matches Contentful count, migration succeeded. Log failures for manual review.

4. Validate Counts and Spot-Check Data

After loading, verify:

• Record count matches source
• Locales appear in translation tables
• Foreign keys are not null for required references
• Asset URLs resolve

Spot-check 5-10 entries by hand. Query via GraphQL to ensure relationships render correctly.