Sanity to WordPress migration: Pre-migration

Before diving into the migration process, establishing a robust foundation is critical. In this phase, we focus on technical setup, data backup, and content cleaning in Sanity. Proper preparation reduces risks and ensures a smoother migration.

Setting up environments

Creating distinct environments like local, staging, and production is essential for a controlled and error-free migration. Each environment serves a specific purpose.

Local environment

Purpose: Development and initial testing.

1. Install WordPress locally

Use tools like Local by Flywheel, MAMP, XAMPP, or Docker to set up a local WordPress installation.

Example using Docker: docker run –name wordpress-local -p 8080:80 -d wordpress

2. Configure WordPress for headless use:

Disable frontend rendering:

Install and activate the Headless CMS plugin or similar to disable the default frontend.

Enable REST API and graphQL:

Ensure the WordPress REST API is accessible.

Install the WPGraphQL plugin to provide GraphQL capabilities.

3. Mirror production settings:

Replicate PHP versions, server configurations, and installed plugins/themes used in production to ensure consistency. Example configuration adjustments in wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

• Database setup

Import a snapshot of the production database if available, ensuring that the local environment reflects the production data structure.

Staging environment

Purpose: Testing, quality assurance, and final validations before production.

1. Deploy WordPress: Install WordPress on the staging server using the provider’s tools or manually via FTP/SFTP.
2. Configure for headless use
   1. Apply the same headless configuration as in the local environment.
   2. Ensure APIs are accessible and properly secured.
3. Data synchronization: Regularly sync the staging database and files with the local environment to keep testing aligned with development.
4. Security measures: Restrict access to the staging environment using HTTP authentication or IP whitelisting to prevent unauthorized access.

Production environment

Purpose: Live website serving end-users.

1. Choose a reliable hosting provider: Opt for managed WordPress hosting services that offer scalability, security, and performance optimizations, such as WPVIP or Pagely.
2. Deploy WordPress: Install WordPress on the production server, ensuring all configurations mirror the staging setup.
3. Optimize for performance:
   1. Implement caching solutions (e.g., W3 Total Cache, WP Rocket).
   2. Integrate a Content Delivery Network (CDN) like Cloudflare or MaxCDN to enhance load times globally.
4. Set Up security protocols:
   1. Install security plugins such as Wordfence or Sucuri.
   2. Configure SSL certificates to ensure secure data transmission.
5. Backup solutions: Set up automated backups using plugins like UpdraftPlus or BackupBuddy.

Benefits of a well-prepared environment

• Issue identification: Early detection of compatibility issues and bugs in the local environment prevents disruptions in staging and production.
• Safe testing ground: Staging provides a space to thoroughly test migrations without affecting the live site.
• Consistency: Ensures that all environments are aligned, reducing discrepancies that can lead to unexpected issues post-migration.

Configuring development tools

If your team isn’t already using version control, setting up Git and hosting your repository on GitHub (or a similar platform) is a critical first step. Proper version control and workflow automation streamline collaboration, testing, and code quality throughout the migration process.

Version control with Git and GitHub

1. Initialize a repository
   Start by creating a new Git repository for your migration project. On your local machine, navigate to your project directory and run: git init
2. Connect to GitHub
   Create a new repository on GitHub, then link your local repository to it: git remote add origin https://github.com/yourusername/your-repo.git
3. Adopt a branching strategy: Use a clear branching model to manage changes. For example:

#Create a develop branch for ongoing work:

git checkout -b develop

#For new features, create feature branches from develop:

git checkout -b feature/your-feature

Once a feature is complete, open a pull request on GitHub to merge it back into develop after a review.

In addition, set up workflows for testing and automation. Implement a continuous integration/continuous deployment (CI/CD) process using tools such as GitHub Actions, Jenkins, or similar services. These workflows will automatically run tests, build processes, and deployments on each commit or pull request, catching issues early and streamlining development.

By configuring these development tools and workflows, your team can collaborate effectively, maintain high code quality, and efficiently manage changes during the Sanity to WordPress migration. 

Preparing Sanity content for migration

Before exporting any data, it’s vital to prepare your Sanity content for migration. This step ensures that only relevant, high-quality content is transferred to WordPress, streamlining the process and safeguarding your SEO and usability.

Cleaning and auditing content

Start by thoroughly reviewing your Sanity content. Identify and remove outdated, duplicate, or unnecessary content. This cleanup reduces the volume of data to migrate and ensures that only the most relevant and high-quality material moves to WordPress. By cleaning up in advance, you avoid clutter and potential confusion in your new system, making the migration process more efficient.

Standardizing metadata and content types

Next, focus on consistency. Ensure that all your content has uniform metadata, proper formatting, and adheres to a standardized structure. This could involve:

• Updating tags, categories, and image alt text.
• Refining content types to match a coherent taxonomy.
• Ensuring consistent formatting across posts and pages.

Standardizing these elements before the export simplifies the mapping process later on. It makes it easier to translate your Sanity content into corresponding WordPress structures, preserving SEO value and usability. With clean, well-organized content and metadata, the migration becomes smoother, and your new WordPress site will be easier to manage and more effective at engaging users. 

Backing up Sanity data

Before migrating from Sanity to WordPress, it’s essential to back up all your data. This ensures that your content, assets, and schemas are preserved safely, reducing risk and laying the groundwork for a smooth transition. Using Sanity’s export tools, we can create comprehensive backups, typically in JSON format, which are ideal for later transformation and migration.

Prerequisites

Before diving into the export process via the command line, make sure you have a few prerequisites in place

• Node.js and npm installed: These are required to install and run the Sanity CLI.
• Sanity CLI installed: Run npm install -g @sanity/cli to install the Sanity Command Line Interface globally.
• Access to your Sanity project: Ensure you have the necessary project credentials and permissions to export the dataset.

Having these prerequisites ready will make the following steps smoother and more efficient.

Exporting with Sanity CLI

Now, let’s walk through a practical example of exporting data using the Sanity CLI. This demonstration will guide you through the process step by step and show you how to secure your Sanity data for migration.

Watch this video demonstration before you begin

In the video, we cover the installation of Sanity CLI, running the export command, unzipping the archive, and converting NDJSON to JSON.

Step 1: Install Sanity CLI
Ensure the Sanity CLI is installed globally on your machine:

npm install -g @sanity/cli

This command provides access to Sanity commands directly from your terminal.

Step 2: Run the Export Command
Navigate to your Sanity project directory and execute:

sanity dataset export production ./exported-data.zip

Replace production with your dataset name and adjust the output path if needed. This command packages all your Sanity data into a ZIP file named exported-data.zip.

Step 3: Extract and Inspect the Data
After the export finishes, unzip exported-data.zip. Inside, you’ll find files such as *nd.json along with other metadata. The *nd.json file contains your content in a Sanity-specific format.

Step 4: Convert NDJSON to Standard JSON
The *nd.json file may include Sanity-specific formatting, which can complicate further processing. To simplify this, convert *nd.json to a standard JSON format:

node convert-ndjson.js

This script reads *nd.json, processes the content, and outputs a clean, standard JSON file named sanity.json. Now your dataset is ready for mapping and migration.

Why Convert?

Converting to a standard JSON format simplifies the next steps. A clean JSON file is easier to parse and transform, which streamlines the process of mapping and importing content into WordPress.

This hands-on example demonstrates how to securely export and prepare your Sanity data. While this walkthrough covers a basic scenario, real-world migrations may be more complex. However, the core principles remain the same: carefully back up and prepare your data to ensure a successful migration to WordPress.

At last, Verify that the backups are complete and accurate. Check exported files to confirm that all necessary content and metadata have been captured. This step provides peace of mind and a safety net, knowing that your data is secure and can be restored if needed. 

Content mapping

Mapping content from Sanity to WordPress involves a careful process of translating your Sanity documents into WordPress equivalents while preserving structure, relationships, and SEO value. This ensures that your content continues to perform well and remains organized in its new home. The process unfolds in several interconnected steps, guiding you from understanding document types to automating the entire mapping and import.

Mapping sanity documents to WordPress entities

Once your Sanity data is exported and cleaned, the first step is to examine each document type and determine its best fit in WordPress. For example:

• Blog posts in Sanity typically become WordPress posts or custom post types.
• Author profiles may map to WordPress user profiles or be managed as custom taxonomy terms.
• Custom content types from Sanity can be recreated as WordPress custom post types, with associated custom fields and taxonomies to maintain a similar organizational structure.

By defining these mappings clearly, we ensure that each piece of content finds its appropriate place in WordPress, preserving context and relationships.

Handling rich text conversion

As we map these documents, we also need to address how rich text is handled. Sanity often uses Portable Text for rich text fields, which supports complex formatting and embedded media. To ensure this content translates well into WordPress:

• We plan to convert Portable Text into HTML that fits seamlessly within the WordPress editor.
• Alternatively, we break down Portable Text into Gutenberg blocks. This method preserves complex formatting and interactive elements, offering a familiar editing experience.

Handling rich text conversion at this stage ensures that content displays correctly and remains editable after the migration.

Below is a simplified mapping of common Sanity document types and fields to their WordPress equivalents

This overview provides a clear snapshot of how different types of content will be handled during the migration.

After planning and mapping, the next natural step is to automate the transformation and import process to handle large volumes of content efficiently:

• We develop scripts in Node.js, PHP, or another language to read the cleaned JSON export from Sanity.
• These scripts apply the mapping rules we’ve defined, transforming each Sanity document into the correct WordPress format.
• Using WordPress’s REST API or WP-CLI, the scripts then automatically create corresponding WordPress entries, upload media, and set metadata.

Automation ties together the previous steps by taking the detailed mappings and converting them into actionable code that streamlines the migration. It minimizes manual effort, reduces errors, and ensures consistency across your entire dataset.Tip: As you build and refine these scripts, begin with a small batch of documents. Verify that WordPress posts are created correctly, rich text is converted properly, and relationships such as author assignments are maintained. Once satisfied, scale up to handle the full dataset, confident that the process works as intended.