DEV Community

rob-kingsbury
rob-kingsbury

Posted on

I got tired of explaining WordPress to my clients, so I built this

#webdev #php #wordpress #opensource

The handoff call is always the same.

I walk the client through their dashboard, they nod, I leave, and three days later I get a text: "Hey, how do I add a blog post again?"

I tried Loom videos. Nobody watched them. Wrote a Google Doc. Nobody opened it. Built a custom help tab right inside their WordPress admin. Still got the texts.

So I built a stupid simple plugin.

WP Client Tour shows your client a guided tour the first time they log in, walking them through the actual pages they'll use. Then it disappears and never fires again unless they ask for a replay. The whole thing runs off a single JSON file you drop in a folder, no subscription required and nothing to install beyond the plugin itself.

How it works

Add a file to tours/:

{
  "id": "woocommerce-orders",
  "target_page": "admin.php?page=wc-orders",
  "target_roles": ["shop_manager"],
  "trigger": "auto_once",
  "steps": [
    {
      "selector": "#toplevel_page_woocommerce",
      "position": "right",
      "title": "Your WooCommerce Menu",
      "body": "Everything for your store lives here."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

The plugin scans that folder on every admin page load. If the file validates, the tour runs. A tour for shop_manager won't fire for admins. Tours can span multiple pages and pick up exactly where they left off after navigating. The renderer is 15kB of vanilla ES6 with no jQuery involved, so nothing fights with your client's plugin stack.

Why not Shepherd.js?

Shepherd and Intro.js are solid. I've used both. But they're built for product teams shipping their own apps, not for someone handing off a WooCommerce store to a restaurant owner who's never touched a CMS.

This is WordPress-native. It knows about user roles and admin pages out of the box, with no custom integration work on your end.

There's an AI authoring option if you want it

Point it at a real wp-admin page, it screenshots the UI and produces a tour.json ready to drop in. Works with Claude Code, Cursor, or ChatGPT. Each step gets a confidence flag so you know which selectors are worth double-checking. Useful, but the plugin works fine without it.

It's free

MIT licensed. I built it because I got tired of answering the same support calls after every handoff. If you've got a better way to handle this, I'd love to hear your take on it.

Demo: https://kingsbury-labs.github.io/wp-client-tour/
Repo: https://github.com/kingsbury-labs/wp-client-tour

Full disclosure: I write code, not tech papers, and AI helped me put this post together. Don't beat me up, it's my first time being a human on the internet.

Top comments (0)