Working with Contentful

Environments

Types of environments

• Environment - Container entities within a space that allow you to create and maintain multiple versions of your content types, and make changes to them in isolation.
• Environment Alias - Environment alias is a static ID that allows you to access and modify the data of its selected target environment. The environment alias target can be quickly switched to a different environment.
• Custom Alias - Custom environment aliases that work like master but can be quickly switched to different environments for development. Only available to Premium tier customers.

Best practices

• For production, use the master environment or the master alias.
• Everything else is a "sandbox" environment.
• Sandbox environments are intended for non-production development and testing and must not be used for production.

Environment Usage Patterns

Local development

• The environment ID should be set using your .env or .env.local file.
• Do not use the master environment for local development.
• Create a new environment by cloning it from an environment that runs your production content.
• Connect to the sandbox environment to be iterate and test changes locally.

Staging / QA

• The environment ID should be set in your CI/CD pipeline.
• Do not use the master environment for staging or QA.
• Create staging and QA environments to test changes before applying them to production.

Workflow example

1. Developers work on a development environment cloned from master
2. Changes are applied to the QA environment for testing
3. QA engineers perform manual and automated tests
4. If tests pass, changes are applied to staging for final testing
5. Finally, changes are applied to the master environment

Editorial workflows

Recommended approach

• Editors work with content in the master environment or master alias
• Developers work on new features in sandbox environments
• Changes are applied from sandbox environments to master when ready

Custom aliases

Apart from the master alias, you can create custom environment aliases with any custom ID (e.g., development, staging).

Important limitations

• Custom environment aliases must not be used for production content
• Requests to the CDA on any environment or environment alias except master are neither cached nor covered by Contentful SLAs
• Custom environment aliases are available to Premium tier customers only

Migration Scripts

Contentful migrations allow you to make reproducible changes to your content model programmatically. This ensures consistency across environments and enables version control for your content structure.

When to use migrations

Required for:

• Breaking changes (field deletions, content type changes)
• Data transformations (renaming fields, changing types)

Optional for:

• Adding new optional fields
• Creating new content types
• Simple additions that don't affect existing content

Manual changes are fine for prototyping, but migration scripts provide version control and consistency across environments.

How migrations work

Migrations are written using the Contentful Migration DSL and executed via the Contentful CLI. They allow you to:

• Create, update, or delete content types
• Modify field properties and validation rules
• Add or remove fields from content types
• Create and manage entries and assets
• Transform existing content

Migration process

// migrations/add-blog-author-field.js
module.exports = function (migration) {
  const blogPost = migration.editContentType("blogPost");

  blogPost.createField("author").name("Author").type("Symbol").required(true);

  blogPost
    .createField("authorBio")
    .name("Author Bio")
    .type("Text")
    .validations([{ size: { max: 500 } }]);
};

# Create a test environment
contentful space environment create --environment-id test-migration

# Run migration in test environment
contentful space migration --environment-id test-migration migrations/add-blog-author-field.js

# Apply migration to master environment
contentful space migration --environment-id master migrations/add-blog-author-field.js

Best practices for migrations

Script organization

• Keep migrations small and focused on single changes
• Use descriptive filenames with timestamps: 2024-01-15-add-blog-author-field.js
• Store migrations in version control
• Document complex transformations

Testing strategy

• Always test migrations in sandbox environments first
• Verify content model changes don't break existing entries
• Test rollback procedures when possible
• Use the Contentful CLI's --dry-run flag to preview changes

Content transformation

When modifying existing content types, handle data migration carefully:

// Example: Renaming a field
module.exports = function (migration) {
  const blogPost = migration.editContentType("blogPost");

  // Create new field
  blogPost.createField("newTitle").name("New Title").type("Symbol");

  // Copy data from old field to new field
  migration.transformEntries({
    contentType: "blogPost",
    from: ["oldTitle"],
    to: ["newTitle"],
    transformEntryForLocale: function (fromFields, currentLocale) {
      return {
        newTitle: fromFields.oldTitle[currentLocale],
      };
    },
  });

  // Remove old field after transformation
  blogPost.deleteField("oldTitle");
};

Rollback considerations

While Contentful doesn't provide automatic rollback for migrations, you can:

• Use environment aliases to quickly switch to previous environments if needed
• Keep migration scripts in version control for reference
• Document manual rollback procedures for complex changes