WordPress Starter Project for Craft CMS

This repository contains a complete Craft CMS application, configured to closely mirror a default WordPress installation. It can be used as an introduction to Craft’s content tools, or as a way to quickly import content from an existing WordPress site.

Tip

See our Craft CMS for WordPress Developers article for additional information about making the switch to Craft!

Features

• Sensible defaults that match WordPress content structure;
• Ready-to-use templates for common WordPress content types;
• Live Preview configured out of the box;
• Pre-packaged with our official WordPress import tool;

Prerequisites

• DDEV or an equivalent local development environment that meets Craft’s system requirements;
• A publicly-reachable WordPress site to migrate from, with administrator-level access;

Installation

1. Clone this repository and move into the folder:

   git clone https://github.com/craftcms/starter-wordpress.git
   cd starter-wordpress/

2. Start DDEV:

   ddev start

3. Install dependencies:

   ddev composer install

4. Run the Craft setup wizard:

   ddev craft install

Congratulations—Craft has been installed! You can explore the control panel by opening https://starter-wordpress.ddev.site/admin in your browser, or continue reading to import existing content.

Note

If you want to use a different subdomain/prefix for this DDEV project, update the name key in .ddev/config.yaml.

Preparing Your WordPress Site

Before migration, you'll need to prepare your WordPress site. See the wp-import repository for complete documentation.

1. Install the import helper:

   • Save plugins/wp-import-helper.php to your WordPress site's wp-content/plugins/ folder
   • Log into WP Admin Dashboard
   • Navigate to Plugins and activate "wp-import helper"

2. Create an application password:

   • In WP Admin Dashboard, go to Users
   • Edit an administrator's account
   • Scroll to "Application Passwords"
   • Enter "Craft CMS" as the name
   • Click "Add New Application Password"
   • Save the username and generated password for later use (you'll need it on the import step)

3. Configure custom post types (if applicable):

   • Ensure 'show_in_rest' => true is set in any calls to register_post_type()

4. Configure ACF fields (if applicable):

   • Enable "Show in REST API" for each field group

Importing Content

The import process is covered in detail in our Craft CMS for WordPress Developers article, but the critical steps are as follows:

1. Run the import script:

   ddev craft wp-import

2. Enter your WordPress site details when prompted:

   • WordPress site URL
   • Admin username
   • Application password (created earlier)

The importer will create:

• A "Posts" section for your posts
• A "Pages" section for your pages
• An "Uploads" filesystem and volume for your media
• A "Post Content" CKEditor field with nested entry types for non-HTML block data

See the wp-import repository for complete documentation, command options, and compatible fields.

Next Steps

We encourage you to explore the control panel at your own pace—if you need some guidance, check out this post-import tour.

Start Templating

This project includes a bare-bones front-end built with Craft’s native template system, Twig. Templates are stored in the templates/ directory—you are welcome to use them as-is, modify them to suit, or remove them entirely and experiment with the GraphQL API!

Note

Some template names and locations are significant—they may be factored in to routing, or used by a section.

Push Changes

To push the code to your own repository, you must replace the default remote:

git remote remove origin
git remote add https://github.com/my-organization/my-repo.git

If the importer created any new resources (typically resulting in new or updated files in config/project/), commit those before pushing!

Deploy

Read our guide on hosting and deployment, or get started with our first-party hosting platform Craft Cloud by spinning up a 7-day free trial:

1. Run the Cloud setup command:

   ddev craft cloud/setup

2. Commit and push those changes to a repository you control;

3. Sign up for Craft Console;

4. Create a new Cloud project;

See our Getting Started on Craft Cloud for details.

Getting Help

If you have any questions or suggestions, you can always reach us at support@craftcms.com or post a GitHub issue.

Thanks for trying Craft!

🍋