Craft CMS for WordPress Developers

Trying out new technology always brings about a mix of excitement and fear. We’ve assembled a few tools and resources here to help make your first steps with Craft CMS as comfortable and rewarding as possible. Let’s dig in!

• 🪴 Get to know the Craft ecosystem →
• 🪄 Spin up our WordPress starter project →
• 🗃️ Import content from an existing project →

What is Craft? #

Like WordPress, Craft is a flexible, self-hosted content management system written in PHP that stores content in a database and can be extended via a plugin marketplace. Developers love its first-party support and vibrant community, and clients appreciate the fast and focused authoring experience.

Beyond the CMS #

While Craft CMS is our primary product, it exists in an ecosystem of first- and third-party tools that support a delightful developer experience:

• Support — When you have a question about any of our products and services, you talk directly to the people who build them.
• Hosting — Our our zero-ops hosting infrastructure Craft Cloud lets you publish your project with just a few clicks.
• Plugins — Adding radically new functionality to your project or connect with third-party services by installing extensions via Craft’s in-app Plugin Store.
• Ecommerce — Craft Commerce is our first-party ecommerce solution that lets you build the content-rich storefront customers love.

Who is Craft for? #

Craft takes a unique, blank-slate approach to modeling content. This means that—despite not having any inherent notion what a “post” or “page” should be—Craft can be quickly configured to express exactly the content types each project needs. It is equally-well equipped to track huge datasets, compose expressive editorial content, and tame tangled webs of content.

If you have historically used plugins like Advanced Custom Fields to create custom content models and templates in WordPress, Craft’s control panel will immediately feel familiar—in fact, our import tool is able to replicate many ACF configurations into Craft with no additional input!

On the other hand, if you use WordPress solely as a publishing tool, or as a visual website designer (leveraging existing themes and editing tools like Gutenberg or Elementor), you may find Craft’s content-as-data approach too rigid.

You can always spin up one of our demo sites to poke around, before starting with a fresh project or diving directly into an import.

Getting Started #

In addition to the generic installation instructions and blank starter project, we have a couple of dedicated on-ramps for WordPress developers.

WordPress Starter Project #

A great way to familiarize yourself with Craft is through a content model that reflects WordPress’s architecture. The craftcms/starter-wordpress project comes pre-configured with features that mirror a new Wordpress installation—including space to draft and publish posts and pages, compose long-form content a la Gutenberg, moderate comments, and so on.

To create a new development project, the process is almost identical to our normal installation instructions, save for the package name:

1. Install DDEV, our recommended local development environment.

2. Clone the repository and move into it:

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

3. Start DDEV:

    ddev start
   

4. Install dependencies:

    ddev composer install
   

5. Run the Craft setup wizard:

    ddev craft install
   

Once Craft is installed, it will apply the included project config to scaffold the fields, sections, entry types, and a variety of other components that comprise the WordPress-like control panel experience.

Control Panel

To open the Craft control panel and explore the content tools, run ddev launch admin in your terminal or visit https://starter-wordpress.ddev.site/admin in a browser.

• 📝 Compose a post or create a page by visiting Entries in the main sidebar;
• 📤 Upload an image by navigating to Assets;
• 🧬 Create some categories to organize your content via Categories;
• 🗺️ Explore your content in the front-end by clicking the site name in the top-left corner, or open up the GraphQL playground;

Front-End

The WordPress starter project comes with a set of basic Twig templates that allow you to visualize content you create via the control panel—either while drafting changes (using the built-in live preview feature), or to browse

Import from WordPress #

Ready to see your content in Craft? Our dedicated import extension can be added to any Craft project to pull in posts, pages, media, users, comments, and more—including metadata managed via Advanced Custom Fields!

In an existing Craft project (version 5.5.0 or later), install the craftcms/wp-import package using Composer:

ddev composer require craftcms/wp-import --dev

Additionally, our first-party CKEditor plugin is required to import content from the Gutenberg editor:

ddev composer require craftcms/ckeditor

If you would like to include comments in your import, you must also install the Comments plugin by Verbb. (You can also come back and import just comments, later!)

In order for Craft to communicate with your WordPress site, you need to do a bit of setup:

• Install the helper: Add this single-file plugin to your WordPress site’s wp-content/plugins/ directory, and activate it via the dashboard.
• Generate credentials: Log in to your WordPress site as an administrator, and generate an application password via the Profile screen.
• Find site URL: Navigate to General Settings in the WordPress dashboard, and note the read-only WordPress Address value.
• Enable custom post types: (Optional) If you have configured additional custom post types in WordPress, you may need to add them to the REST API.

You may uninstall the wp-import plugin and revoke the application password after the import is complete.

With everything configured, run the wp-import command via Craft’s CLI:

ddev craft wp-import

You will be prompted for your WordPress site’s URL, an administrator’s username, and an application password belonging to them. Use the values you noted in the previous steps!

Craft will output any warnings about the import (like connection problems, limitations on user imports, or the absence of the Comments plugin). Once resolved, you’ll be presented with a summary of content that Craft can see and import. If you would prefer to import only a portion of the listed resources, you can cancel the import using Control + C and re-run the command with one or more supported flags:

# View supported options:
ddev craft wp-import --help

# Import only posts and media:
ddev craft wp-import --type post,media

# Do a “dry-run”:
ddev craft wp-import --dry-run

See the craftcms/wp-import readme for information on the supported Gutenberg block types and ACF field types.

Depending on the number of posts and pages in your site, the import may take anywhere from a few seconds to an hour or more. You can resume an interrupted import any time, or force it to completely restart with the --update option.

During the import, you will see a combination of content and schema changes logged to the console. As Craft processes content, it adds any missing resources “just in time,” rather than creating everything up-front (and leaving you with a bunch of features that aren’t actually used in your site).

When the import is complete, you can visit the Craft control panel to explore your content in its new home!

ddev launch admin

Tour #

Depending on your WordPress site’s configuration (and what was successfully imported), the Craft control panel will look a bit different. Most sites, though, will get access to a few main areas:

Entries #

Your posts, pages, and custom post types were imported here, as entries, within sections. Each entry was populated with a combination of native attributes (like a slug, post date, author, and status) or, in cases where Craft didn’t have an equivalent native feature, custom fields (like post content, the excerpt, or cover photo).

If you imported posts that used Advanced Custom Fields, those values were copied into new custom fields.

Assets #

Any media Craft found while importing content was imported as assets. A new volume and filesystem were created to store the underlying files—you can either leave this as an on-disk filesystem, or upload your files (currently in web/uploads/) to a dedicated storage service and install the relevant remote filesystem adapter.

Categories #

Post categories were imported here. Note that they have retained their hierarchy, kind of like the Pages section. In Craft, we call this a structure.

Users #

If you upgraded to Craft Team or Pro during the import, additional users were imported here.

Settings #

Configuration for all of the above is accessible via the Settings screen:

• Sections define the primary, top-level buckets for the imported entries. Each section controls how its entries are organized, and what their URLs look like.
• Entry Types are shared between sections, Matrix fields, and CKEditor fields. You’ll see a type for Post, Page, Media, as well as a dedicated type for any complex Gutenberg block types your site used.
• Fields contains all the custom fields Craft created to hold your content. Each field can be attached to multiple field layouts with a new name and handle.
• Categories and Tags will typically contain a single group, each. Groups determine what fields are available when editing a category or tag, and what a category’s URL looks like.

Perhaps most importantly, we create a WordPress ID field to stash the legacy ID for posts, pages, comments, media, and so on. Later in the import (or when re-importing content using the --update option), we can match up the records and connect them correctly in Craft, even though they receive new IDs.

Vocabulary #

While Craft has a lot of features that end up being equivalent to something WordPress offers, we might have a different way of naming or describing them. Many of these concepts, taken in isolation, can be confusing or worrisome. For example, themes (in the WordPress sense) are absent from Craft—but it still has a great templating environment called Twig that lets you build exactly the front-end experience you want.

This list is adapted from the official Getting started with the WordPress dashboard lesson, and supplemented by terms in the WordPress Glossary.

Alternatives + Further Reading #

Popular Solutions #

So far, we’ve only discussed core Craft CMS features, and those of two relatively focused plugins (CKEditor and Comments). Let’s look at a few popular WordPress plugins and their Craft equivalents.

WooCommerce

We have three first-party plugins to support storefronts of any scale:

• Craft Commerce is a fully-fledged ecommerce system with sophisticated pricing, organization, inventory, and payment tools.
• Shopify connects to a Shopify store and synchronizes product data into Craft, which you can use just like any other element.
• Stripe operates similarly to Shopify, but directly exposes your products and prices as Craft elements, allowing customers to purchase single items (or start a recurring subscription), using Stripe’s Checkout system.

All these options represent your products with elements, so they automatically get access to the same powerful content tools as entries.

Yoast

Our community’s de facto SEO solution is SEOMatic, a deeply-configurable suite of tools for generating and outputting HTML and JSON-LD metadata.

WPForms

Formie and Freeform are highly-capable form-building tools. Without plugins, you can set up a permissions scheme for logged-in users that makes it possible to intake forms as entries; if you need to let guests create entries, check out our Guest Entries plugin!

Gutenberg + Design Tools

While not a plugin, per se, WordPress’s Gutenberg editor doesn’t have a direct replacement in the Craft ecosystem—but the Vizy plugin provides an enhanced rich-text environment like CKEditor, with some additional flexibility when working on content, in-line.

Craft’s built-in content tools tend to perform best in tightly-structured design systems, rather than ad-hoc

Limitations #

If the import tool is missing functionality that your site requires, please let us know!

• Revision history is not imported, but each post-type’s sections in Craft is set up to track them, going forward.
• WooCommerce products and orders are currently not imported, but it is something we are keen on supporting via Craft Commerce.
• Site- or page-builder plugins like Elementor that store content in a proprietary format won’t work, but you may be able to set up a custom importer if such a tool is used in a predictable way.