/handbook/sanity-to-wordpress-migration/pre-migration/
What We Do
Digital Platform MigrationsKey SolutionsManaged ServicesStaffing SolutionsIndustriesProducts
OnePress
Unify multiple brands on one governed WordPress platform.
Design & UI/UX
Gutenberg-native UX, UI, and design systems for visitors and editors.
WordPress Modernization
Modernize WordPress for better performance, architecture, and AI readiness.
WordPress as a DXP
WordPress as a composable DXP when monolithic systems no longer cut it.
Headless WordPress
Omnichannel content delivery without sacrificing marketing autonomy.
Frappe/ERPNext
Build scalable ERP and custom applications, from implementation to ongoing support.
Discovery
Strategic consultancy & project roadmap
Growth Services
On demand development & consultation
Site Maintenance
Annual maintenance. Done for you
QE Services
Testing across SDLC for assured quality
Hosting Migration
Move to a performant hosting with zero downtime
WooCommerce
Enterprise commerce delivered without lock-in
AI
Unlock real use cases and integrations
All Services
A suite of services for any need
Technology STACK
eCommerce
Scale your e-commerce with WooCommerce, integrations, and custom extensions for growth.
EasyEngine
Server management tool that makes using WordPress on Nginx easy.
Web Auditor
Performance Audit & Insights for your Website.
rtMedia
A complete media management plugin for WordPress.
Resources
About Us
CLEAR
Resources Sanity to WordPress migration guide Pre-migration setup
Topics
On this page
- Sanity to WordPress migration guide
- Business case for migration
- Migration process, timeline & team
- Planning the migration
- Pre-migration setup
- Frontend, backend & content migration
- Quality assurance
- Site launch
- Post-migration checks
- How can rtCamp help
Setting up environments
Local environment
Staging environment
Production environment
Benefits of a well-prepared environment
Configuring development tools
Version control with Git and GitHub
Preparing Sanity content for migration
Cleaning and auditing content
Standardizing metadata and content types
Backing up Sanity data
Prerequisites
Exporting with Sanity CLI
Content mapping
Mapping sanity documents to WordPress entities
Handling rich text conversion
Last updated on Apr 1, 2026
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.
- 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
- 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.
- 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);ndefine('WP_DEBUG_LOG', true);ndefine('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.
-
Deploy WordPress: Install WordPress on the staging server using the provider’s tools or manually via FTP/SFTP.
-
Configure for headless use
- Apply the same headless configuration as in the local environment.
- Ensure APIs are accessible and properly secured.
-
Data synchronization: Regularly sync the staging database and files with the local environment to keep testing aligned with development.
-
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.
-
Choose a reliable hosting provider: Opt for managed WordPress hosting services that offer scalability, security, and performance optimizations, such as WPVIP or Pagely.
-
Deploy WordPress: Install WordPress on the production server, ensuring all configurations mirror the staging setup.
-
Optimize for performance:
- Implement caching solutions (e.g., W3 Total Cache, WP Rocket).
- Integrate a Content Delivery Network (CDN) like Cloudflare or MaxCDN to enhance load times globally.
-
Set Up security protocols:
-
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
- 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 - Connect to GitHub
Create a new repository on GitHub, then link your local repository to it: git remote add origin https://ancillary-proxy.atarimworker.io?url=https%3A%2F%2Fgithub.com%2Fyourusername%2Fyour-repo.git - Adopt a branching strategy: Use a clear branching model to manage changes. For example:
#Create a develop branch for ongoing work:nngit checkout -b developnn#For new features, create feature branches from develop:nngit 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
Sanity elementWordPress equivalentTransformation notesSanity Document (e.g., blog)WordPress Post or Custom Post Type (CPT)Map fields from Sanity document to WordPress post fieldsSanity Author DocumentWordPress User or Custom Author TaxonomyConvert author details into WordPress user profiles or taxonomiesPortable Text (Rich Text)Gutenberg Blocks or Custom FieldsConvert Portable Text to HTML or structured blocksSanity Image AssetWordPress Media Library AssetUpload images to WordPress, update URLs and metadataSlug FieldWordPress Slug/PermalinkMap Sanity slug to WordPress permalinkSEO MetadataSEO Plugin Fields (Yoast, Rank Math)Transfer meta titles, descriptions, alt text for SEO preservation
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.
Planning the migration
PREVIOUS
Frontend, backend & content migration
NEXT
Credits
Shreya Agarwal
Author
Shreya Agarwal
Author
Shreya Agarwal is a Growth Engineer at rtCamp, she brings active, hands-on WordPress development credentials to everything she writes and reviews. A WordPress Core Contributor with merged pull requ…
Good Work. Good People.
Industry partnerships
Compliance certifications
United States India
© rtCamp Inc. since 2009. All rights reserved.
Terms of Service · Privacy Policy · Trust Center
Company
Solutions
Subscribe to Campfire for fresh insights and stories from people behind rtCamp
Δ
Email(Required)
Submit
United States India
© rtCamp Inc. since 2009. All rights reserved.
Terms of Service · Privacy Policy · Trust Center
Cookie Consent
We value your privacy
We use cookies to give you the best possible experience. By clicking “Accept,” you consent to our use of cookies to improve site functionality, analyze usage, and personalize content and communications. Your privacy matters to us, and we are committed to handling your data responsibly and transparently. Please check our Privacy Policy for more details.
Manage PreferencesDon’t AllowAllow All
Why do we use cookies?
×
By clicking "Accept" or "Decline All" at the bottom, you consent to the use of cookies and other tools as described in our Cookie Policy in accordance with your settings and accept our Terms of Service.
Toggle EssentialEssential
Essential cookies enable basic functions and are necessary for the proper function of the website.
Name
Description
Duration
Geolocation Config
This cookie is used to store the consent settings based on the visitor's location.
30 days
Cookie Preferences
This cookie is used to store the user's cookie consent preferences.
30 days
Toggle CloudFlareCloudFlare
CloudFlare provides web performance and security solutions, enhancing site speed and protecting against threats.
Service URL: developers.cloudflare.com (opens in a new window)
Name
Description
Duration
cf_clearance
Whether a CAPTCHA or Javascript challenge has been solved.
session
Toggle CommentsComments
These cookies are needed for adding comments on this website.
Name
Description
Duration
comment_author
Used to track the user across multiple sessions.
Session
comment_author_email
Used to track the user across multiple sessions.
Session
comment_author_url
Used to track the user across multiple sessions.
Session
Toggle GodamGodam
GoDAM" is primarily a specialized WordPress plugin and media management service designed to enhance video hosting, marketing, and asset management directly within the WordPress dashboard.
Service URL: godam.io (opens in a new window)
Name
Description
Duration
user_image
Temporarily stores the path to the user's avatar or profile picture for quick rendering in the website header.
session
user_id
Stores the numerical ID of the logged-in user to maintain session continuity and basic site operations.
session
full_name
Stores the logged-in user's display name to personalize the site interface without needing database queries.
session
system_user
First-party cookie used to store basic application state identifying the current system user role.
session
sid
A generic session ID cookie used to maintain user state and functionality as the visitor navigates through the site.
session
Toggle Google reCAPTCHAGoogle reCAPTCHA
Google reCAPTCHA helps protect websites from spam and abuse by verifying user interactions through challenges.
Name
Description
Duration
_GRECAPTCHA
Google reCAPTCHA sets a necessary cookie (_GRECAPTCHA) when executed for the purpose of providing its risk analysis.
179 days
Toggle Google Tag ManagerGoogle Tag Manager
Google Tag Manager simplifies the management of marketing tags on your website without code changes.
Name
Description
Duration
cookiePreferences
Registers cookie preferences of a user
2 years
td
Registers statistical data on users' behaviour on the website. Used for internal analytics by the website operator.
session
Toggle StatisticsStatistics
Statistics cookies collect information anonymously. This information helps us understand how visitors use our website.
Toggle Factors AIFactors AI
Factors.ai is a B2B account intelligence and marketing analytics platform that helps Go-To-Market (GTM) teams identify anonymous website visitors, track buyer journeys, and measure the ROI of marketing campaigns.
Service URL: www.factors.ai (opens in a new window)
Name
Description
Duration
_fuid
It is sent to capture session details and track user behavior across your website to provide behavioral data and intent signals.
1 Year
Toggle Google AnalyticsGoogle Analytics
Google Analytics is a powerful tool that tracks and analyzes website traffic for informed marketing decisions.
Service URL: policies.google.com (opens in a new window)
Name
Description
Duration
FPGSID
Stores a session or user identifier to track how visitors interact with a website. This helps Google Analytics measure website performance, user engagement, and usage patterns.
Session
FPLC
Used by Google Analytics to link visitor interactions and sessions across multiple related domains.
20 hours
FPID
A server-side Google Analytics cookie used as an alternative user identifier when third-party cookies are restricted.
2 years
_ga
ID used to identify users
2 years
_ga_
ID used to identify users
2 years
Toggle Jetpack StatsJetpack Stats
Jetpack's built-in visitor analytics. It records page views, referring sites, search terms, and outbound link clicks, and also carries the shared visitor-tracking library used by Jetpack Instant Search and WooCommerce Analytics.
Service URL: automattic.com (opens in a new window)
Name
Description
Duration
tk_aip
Stores a list of anonymous visitor IDs so they can be merged into one identity once a visitor is recognized.
Up to 5 years
tk_tc
Used once per page load to work out which cookie domain the Tracks library should use, then removed as soon as it's read back.
Session (deleted immediately after use)
tk_qs
Queues analytics events for Jetpack's Tracks library so none are lost if the page closes before they can be sent.
30 minutes
tk_ai
Stores a randomly-generated anonymous visitor ID so Jetpack's Tracks analytics library can link tracking events to the same visitor.
Session in wp-admin; up to 5 years on the frontend
Toggle Microsoft ClarityMicrosoft Clarity
Clarity is a web analytics service that tracks and reports website traffic.
Service URL: clarity.microsoft.com (opens in a new window)
Name
Description
Duration
CLID
Identifies the first-time Clarity saw this user on any site using Clarity.
12 months
ANONCHK
Indicates whether MUID is transferred to ANID, a cookie used for advertising. Clarity doesn't use ANID and so this is always set to 0.
Session
_clck
Persists the Clarity User ID and preferences, unique to that site is attributed to the same user ID.
12 months
_clsk
Connects multiple page views by a user into a single Clarity session recording.
12 months
Toggle Parse.lyParse.ly
Parse.ly is a content analytics platform that helps publishers optimize audience engagement and content performance.
Name
Description
Duration
_parsely_session
JSON document storing information identifying a browsing session according to Parsely’s proprietary definition
30 minutes
_parsely_visitor
JSON document uniquely identifying a browser and counting its sessions
13 months
cookies.js_dtest
This cookie determines whether the browser accepts cookies.
session
Toggle MarketingMarketing
Marketing cookies are used to follow visitors to websites. The intention is to show ads that are relevant and engaging to the individual user.
Toggle Bing / MicrosoftBing / Microsoft
Bing, powered by Microsoft, is a search engine providing web, image, video, and map search capabilities.
Name
Description
Duration
MR
Used to collect information for analytics purposes.
6 months
ANONCHK
Used to store session ID for a users session to ensure that clicks from adverts on the Bing search engine are verified for reporting purposes and for personalisation
10 minutes
SM
Used by Microsoft in synchronizing the MUID across multiple Microsoft domains to track users for advertising.
session
MUID
Identifies unique web browsers visiting Microsoft sites. These cookies are used for advertising, site analytics, and other operational purposes.
1 year
Toggle DoubleClick/Google MarketingDoubleClick/Google Marketing
A comprehensive digital advertising platform for managing campaigns, optimizing performance, and analyzing audience data.
Name
Description
Duration
IDE
This cookie is used for targeting, analyzing and optimisation of ad campaigns in DoubleClick/Google Marketing Suite
2 years
ar_debug
Store and track conversions
Persistent
Toggle LinkedInLinkedIn
LinkedIn is a professional networking platform for job seekers, employers, and industry connections.
Name
Description
Duration
bscookie
Used by LinkedIn to track the use of embedded services.
1 year
AnalyticsSyncHistory
Used to store information about the time a sync with the lms_analytics cookie took place for users in the Designated Countries
30 days
bcookie
Used by LinkedIn to track the use of embedded services.
1 year
li_sugr
Used to make a probabilistic match of a user's identity outside the Designated Countries
90 days
lidc
Used by the social networking service, LinkedIn, for tracking the use of embedded services.
1 day
UserMatchHistory
Used by LinkedIn Ads to synchronize and match user IDs across different ad networks and data providers.
30 days
Toggle LinkedIn InsightLinkedIn Insight
LinkedIn Insight is a web analytics service that tracks and reports website traffic.
Service URL: www.linkedin.com (opens in a new window)
Name
Description
Duration
li_sugr
Used to make a probabilistic match of a user's identity.
90 days
lidc
Used for routing and session management.
24 hours
Toggle LiveIntentLiveIntent
LiveIntent provides a platform for email advertising and identity-driven marketing solutions.
Name
Description
Duration
_lc2_fpi_js
Companion cookie to _lc2_fpi used by JavaScript to facilitate cross-domain ad tracking and user identification.
1 year
_lc2_fpi
First-party tracking cookie usually associated with LiveRamp to identify users across devices for targeted advertising.
1 Year
_li_ss
Sets a unique ID for the visitor, that allows third party advertisers to target the visitor with relevant advertisement. This pairing service is provided by third party advertisement hubs, which facilitates real-time bidding for advertisers.
1 month
lidid
Collects data on visitors' behaviour and interaction - This is used to make advertisement on the website more relevant. The cookie also allows the website to detect any referrals from other websites.
2 years
Toggle Cookie PolicyCookie Policy
You can find more information in our Privacy Policy.
Allow AllDecline All
Accept