Setting the file. One moment.
Skill 07 · Contentful Migration
Subchapter 7.1
references/api-reference.mdMarkdown15 KBView on GitHub
Complete reference for the contentful-migration library API.
Creates a new content type. Returns a ContentType object for chaining.
Options (also available as chained methods):
name (string) — display namedescription (string) — descriptiondisplayField (string) — field ID used as the entry title (must be a Symbol field)const post = migration.createContentType('post')
.name('Post')
.description('Blog post')
.displayField('title')Returns an existing content type for modification. Same options as createContentType.
Deletes a content type. The type must have zero published or draft entries.
All field methods are called on a ContentType object.
Creates a field. Returns a Field object for chaining.
Options (also available as chained methods):
name (string, required) — display nametype (string, required) — field typerequired (boolean) — marks as requiredlocalized (boolean) — enables per-locale valuesdisabled (boolean) — prevents editing in the web appomitted (boolean) — field is not included in API responsesdefaultValue (object) — locale-keyed defaults: { 'en-US': 'value' }validations (array) — validation rulesitems (object) — for Array type: { type, linkType?, validations? }linkType (string) — for Link type: 'Asset' or 'Entry'allowedResources (array) — for ResourceLink typeEdits an existing field. Same options as createField.
Deletes a field and its content from all entries. This is irreversible.
Renames a field ID. Content is preserved.
Returns a Movement object:
.toTheTop() — move to first position.toTheBottom() — move to last position.beforeField(fieldId) — position before another field.afterField(fieldId) — position after another fieldShort text, max 256 characters. Used for titles, slugs, short strings.
field.type('Symbol')Long text, max 50,000 characters. Used for descriptions, body text (plain text).
field.type('Text')Whole number.
field.type('Integer')Decimal number (floating point).
field.type('Number')ISO 8601 date/time string.
field.type('Date')True or false.
field.type('Boolean')Arbitrary JSON object. Useful for structured metadata.
field.type('Object')Geographic coordinates (latitude/longitude).
field.type('Location')Structured rich text with embedded entries and assets. Configure allowed node types and marks via validations:
field.type('RichText').validations([
{
enabledNodeTypes: [
'heading-1', 'heading-2', 'heading-3',
'ordered-list', 'unordered-list',
'blockquote', 'hyperlink',
'embedded-entry-block', 'embedded-asset-block',
],
},
{
enabledMarks: ['bold', 'italic', 'underline', 'code'],
},
])Available node types: heading-1 through heading-6, ordered-list, unordered-list, blockquote, hr, hyperlink, entry-hyperlink, asset-hyperlink, embedded-entry-block, embedded-asset-block, embedded-entry-inline, table.
Available marks: bold, italic, underline, code, superscript, subscript.
List of values or references. Requires items configuration:
// Array of symbols
field.type('Array').items({ type: 'Symbol' })
// Array of entry references
field.type('Array').items({
type: 'Link',
linkType: 'Entry',
validations: [{ linkContentType: ['tag', 'category'] }],
})
// Array of asset references
field.type('Array').items({
type: 'Link',
linkType: 'Asset',
validations: [{ linkMimetypeGroup: ['image'] }],
})Single reference to an entry or asset. Requires linkType:
// Entry reference
field.type('Link').linkType('Entry')
.validations([{ linkContentType: ['author'] }])
// Asset reference
field.type('Link').linkType('Asset')
.validations([{ linkMimetypeGroup: ['image', 'video'] }])Cross-space reference. Requires allowedResources:
field.type('ResourceLink').allowedResources([{
type: 'Contentful:Entry',
source: 'crn:contentful:::content:spaces/other-space-id',
contentTypes: ['article'],
}])Apply validations with .validations([...]) on a field. Multiple validations can be combined in one array.
Restricts to a set of allowed values. Works with Symbol, Integer, Number.
field.validations([{ in: ['draft', 'review', 'published'] }])Ensures values are unique across all entries at publication time.
field.validations([{ unique: true }])Min/max constraint on length (text) or count (array).
field.validations([{ size: { min: 1, max: 10 } }])Min/max for numeric values.
field.validations([{ range: { min: 0, max: 100 } }])Regular expression pattern match.
field.validations([{ regexp: { pattern: '^[a-z0-9-]+$', flags: 'i' } }])Min/max date constraint.
field.validations([{ dateRange: { min: '2020-01-01T00:00:00Z', max: '2030-12-31T23:59:59Z' } }])Restricts which content types a Link or Array of Links can reference.
field.validations([{ linkContentType: ['author', 'organization'] }])Restricts asset MIME types. Groups: attachment, plaintext, image, audio, video, richtext, presentation, spreadsheet, pdfdocument, archive, code, markup.
field.validations([{ linkMimetypeGroup: ['image', 'video'] }])Min/max file size in bytes.
field.validations([{ assetFileSize: { min: 0, max: 5242880 } }]) // max 5 MBMin/max width/height in pixels.
field.validations([{
assetImageDimensions: {
width: { min: 100, max: 4000 },
height: { min: 100, max: 4000 },
},
}])Sets the UI widget for a field.
Widget namespaces:
builtin — standard Contentful widgetsextension — UI extensions (installed separately)app — custom Contentful apps| Widget ID | Field types | Settings |
|---|---|---|
singleLine | Symbol | helpText |
urlEditor | Symbol | helpText |
slugEditor | Symbol | helpText, trackingFieldId |
dropdown | Symbol, Integer, Number | helpText |
radio | Symbol, Integer, Number | helpText |
tagEditor | Symbol (Array) | helpText |
listInput | Symbol (Array) | helpText |
checkbox | Symbol (Array) | helpText |
multipleLine | Text | helpText |
markdown | Text | helpText |
richTextEditor | RichText | helpText |
numberEditor | Integer, Number | helpText |
rating | Integer, Number | helpText, stars (default: 5) |
boolean | Boolean | helpText, trueLabel, falseLabel |
datePicker | Date | helpText, format (dateonly, time, timeZ), ampm (12, 24) |
locationEditor | Location | helpText |
objectEditor | Object | helpText |
entryLinkEditor | Link (Entry) | helpText, showCreateEntityAction, showLinkEntityAction |
entryLinksEditor | Array (Entry) | helpText, bulkEditing, showCreateEntityAction, showLinkEntityAction |
entryCardEditor | Link (Entry) | helpText, showCreateEntityAction, showLinkEntityAction |
entryCardsEditor | Array (Entry) | helpText, bulkEditing, showCreateEntityAction, showLinkEntityAction |
assetLinkEditor | Link (Asset) | helpText, showCreateEntityAction, showLinkEntityAction |
assetLinksEditor | Array (Asset) | helpText, showCreateEntityAction, showLinkEntityAction |
assetGalleryEditor | Array (Asset) | helpText |
Resets a field to its default widget.
Copies widget settings from one field to another.
Editor layouts let you organize fields into tabs and collapsible sections.
Creates an editor layout. Returns an EditorLayout object.
Creates a field group (tab or section). Options: name (string).
Edits an existing field group.
Deletes a field group.
Renames a field group.
Configures how a field group renders.
Built-in group widgets:
topLevelTab — renders as a tab. Settings: helpText.fieldset — renders as a collapsible section. Settings: helpText, collapsible (boolean), collapsedByDefault (boolean).editorLayout.moveField(fieldId) returns an EditorLayoutMovement with:
.toTheTopOfFieldGroup(groupId?) — move to top of group.toTheBottomOfFieldGroup(groupId?) — move to bottom of group.beforeField(fieldId) — before a specific field.afterField(fieldId) — after a specific field.beforeFieldGroup(groupId) — before a field group.afterFieldGroup(groupId) — after a field groupconst layout = page.createEditorLayout()
layout.createFieldGroup('content', { name: 'Content' })
layout.changeFieldGroupControl('content', 'builtin', 'topLevelTab')
layout.createFieldGroup('seo', { name: 'SEO' })
layout.changeFieldGroupControl('seo', 'builtin', 'topLevelTab')
layout.createFieldGroup('openGraph', { name: 'Open Graph' })
layout.changeFieldGroupControl('openGraph', 'builtin', 'fieldset', {
helpText: 'Social sharing metadata',
collapsedByDefault: true,
})
layout.moveField('title').toTheTopOfFieldGroup('content')
layout.moveField('body').afterField('title')
layout.moveField('metaTitle').toTheTopOfFieldGroup('seo')
layout.moveField('ogImage').toTheTopOfFieldGroup('openGraph')Adds a widget to the sidebar. Widget namespaces: sidebar-builtin, extension.
Updates an existing sidebar widget’s settings.
Removes a widget from the sidebar.
Resets sidebar to default configuration.
const page = migration.editContentType('page')
page.addSidebarWidget('sidebar-builtin', 'publication-widget')
page.addSidebarWidget('extension', 'translationExtension', {
sourceLocale: 'en-US',
})
page.removeSidebarWidget('sidebar-builtin', 'versions-widget')Creates a tag. Options: name (string). Visibility: 'public' (default) or 'private'.
Edits an existing tag.
Deletes a tag. Works even if the tag is attached to entries or assets.
Assigns tags to entries based on field values.
contentType (required) — content type IDfrom (required) — array of field IDs to readsetTagsForEntry (required) — (entryFields, currentTags, allTags) => ITagLink[]migration.createTag('region-eu').name('Region: EU')
migration.createTag('region-us').name('Region: US')
migration.setTagsForEntries({
contentType: 'office',
from: ['region'],
setTagsForEntry: (fields, currentTags, allTags) => {
const region = fields.region['en-US']
const tagId = region === 'Europe' ? 'region-eu' : 'region-us'
const newTag = allTags.find((t) => t.sys.id === tagId)
return [...currentTags, newTag!]
},
})Sets annotations on a content type.
Available annotations:
Contentful:AggregateRootContentful:AggregateComponentSets annotations on a field. Options: parameters (object with appFunctionId, appDefinitionId).
Available field annotations:
Contentful:GraphQLFieldResolverRemoves all annotations.
const page = migration.createContentType('page')
page.setAnnotations(['Contentful:AggregateRoot'])
const computed = page.createField('computed')
.type('Symbol')
.name('Computed Value')
computed.setAnnotations(['Contentful:GraphQLFieldResolver'], {
parameters: { appFunctionId: 'func-123', appDefinitionId: 'app-456' },
})Adds a taxonomy validation. linkType: 'TaxonomyConcept' or 'TaxonomyConceptScheme'. Options: { required: boolean }.
Removes all taxonomy validations.
Replaces all taxonomy validations.
const article = migration.editContentType('article')
article.addTaxonomyValidation('topic-taxonomy', 'TaxonomyConcept', { required: true })
article.addTaxonomyValidation('content-category', 'TaxonomyConceptScheme')Taxonomy concepts and schemes must already exist (create them via the web app or CMA).
The second parameter to the migration function provides:
Direct access to the Contentful Management API. Uses Axios-style configuration.
import type { MigrationFunction } from 'contentful-migration'
const migration: MigrationFunction = async (migration, { makeRequest }) => {
const response = await makeRequest({
method: 'GET',
url: '/content_types?limit=100',
})
const contentTypes = response.items
}
export = migrationThe current space ID (string).
The current management access token (string).
This file
Nearby