How do you build custom settings pages for “modern” WordPress?

My next big project is a WordPress multisite with a smooth onboarding / settings experience so that an in-house marketing team can spin up and customize new sites on the network quickly. It feels like the perfect use case for full site editing. In the wake of the OllieWP theme release debate, Justin Tadlock opened up an interesting discussion on the Make WordPress blog about handling custom Settings screens in block themes, something I’m thinking about deeply as I embark on this project.

To quickly summarize what had happened, OllieWP’s new block theme included a custom, React-based onboarding screen to help users set up their site. The theme review team, however, didn’t feel they had the time/experience to handle auditing this sort of advanced code and asked that it be stripped down or removed, mostly so that it didn’t set a precedent for other themes to follow. Overall I think the right decisions were made by all involved- I love the idea of WordPress themes becoming leaner and solely focusing on design, not admin functionality (even though Ollie’s onboarding experience was quite good and felt very native). Moving it to a companion plugin (Ollie Dash) makes sense.

Ollie Dash comes with a very user-centric approach that lets you set up a few basic page templates, brand colors, and WordPress options when you launch a site with the Ollie theme. Very similar to what I’m trying to accomplish for this client. My clients want that smooth experience whenever they add a new site to the network: pick a theme, enter settings, authenticate with a couple of external APIs, scaffold the site with populated pages and patterns, and then jump into the site editor to mess with colors and fonts.

That’s why I’m very interested to see (and help explore) where the community goes with this. While the context of Justin’s post is guidelines for the WordPress theme directory, I believe we should all be exploring the best practices for future WordPress development, especially as we move into phase 3 of Gutenberg. Which begs the question:

How should I build my custom onboarding/settings page today?

The current “best practice” that the theme guidelines recommend is to use the Customizer. I’m honestly not even considering this approach at all, mainly because it feels like the Customizer is not long for this world. (And I really was a Customizer fan.)

The next option would be to use the Settings API and create a classic WordPress settings page in PHP. Again, I’m optimistic that most of the admin interface is going to move into the Gutenberg design language (just look at the progress being made on the post and page list tables), so I don’t really want to spin up an old-school settings page if I can avoid it. It feels like many of the top plugins (Yoast, WooCommerce) have moved into using React and either the @wordpress/components library or their own variation. These settings pages just feel more modern.

The downside here, is that there’s still no “recommended approach” or scaffolding available to doing this. There’s really no core API for setting up JavaScript-based settings pages yet. Looking around, it seems like the most common approach is to:

• register a traditional settings page
• make a custom WP REST API endpoint to handle saving/validating your options data,
• use the WordPress component library and mount a UI onto the settings page, and
• connect the two using @wordpress/api-fetch.

So, the basic pieces are there, if you’re willing to do a little legwork. This is probably the approach I’ll take as well, as it seems the most future-proof.

(One of the very cool things Ollie does is make their settings page look like the Site Editor, dark sidebar navigation and all. I assume that one day developers will be able to register their own screens in the site editor, but until then, I’m not sure I want to build on top of the experimental NavigatorProvider just yet.)

Now, I can understand why the team at OllieWP wants their onboarding experience to be so deeply integrated with their theme, but honestly, I would have loved to see it as a theme-agnostic plugin, abstracting the integration out through WordPress hooks so that any theme could integrate with it. Maybe it becomes a sort of next-generation framework in the footsteps of the old Kirki Customizer. Make more of it extensible for other developers, while still making your integration the best.

I realize this is a lot to ask for, especially when I just want to use it to make something for a client project. WordPress core hasn’t even made the Site Editor extensible for plugins yet, so I’m definitely not saying OllieWP should, just that I wish they could. It probably isn’t even possible yet (especially when different themes don’t even use the same names for colors). At the end of the day, the OllieWP team has open sourced the codebase, so we can all learn from it. That’s what’s truly important here.

I think this goes to a core issue of modern WordPress, something I hear a lot of developers talking a lot about: WordPress core and many popular plugins are much less extensible these days. There’s a reason: actions and filters feel so much harder to execute properly in Gutenberg than in core, in JavaScript than in PHP.

There has been some recent focus on this, though, so I’m optimistic that priorities are changing! And hopefully I learn something new as I explore this project and I share what I learn and together as a community we can start defining what we think the future of extending the WordPress admin interface will look like.