engineering

Empty States That Onboard: Turning Blank Pages Into a First-Run Journey

Empty States That Onboard: Turning Blank Pages Into a First-Run Journey
6 min read
Krešimir Čoko

TL;DR: ByteChef's empty pages used to say "No Projects" or "No Project Deployments" and offer one button. Each empty page now explains what belongs there, shows the four steps from a first project to a first run, and works out which step you're on, so the button it offers leads somewhere you can finish.

New users see your empty states before anything else, and a workflow automation platform like ByteChef has a lot of empty pages: Projects, Connections, Deployments, Executions. Ours mostly told people there was nothing there.

Below is what we changed, the bug that made us rethink the whole set, and the rules we ended up with.

1. The Problem: Empty States That Said Nothing

Here's what the Projects page used to tell a new user:

No Projects. Get started by creating a new project.

It's accurate, but it doesn't say what a project is or what comes after creating one, and the other pages used the same template.

The Executions page was worse. New users open it early, because "did my workflow run?" is a natural first question, and they found one sentence with no way forward next to six filters for an empty list.

The Deployments page had an actual dead end. Its empty state offered Create Deployment, which opened a dialog whose version picker only lists published project versions. A brand-new user has none, so the most prominent button on the page opened a form nobody could submit. That bug is why every empty state now checks where the user is before it offers a button.

2. The Journey: Four Steps to a First Run

Before an automation runs, four things have to happen:

  1. Create a project
  2. Build and test a workflow
  3. Publish a version
  4. Deploy and enable

These steps live in a small reusable JourneySteps component. Each step is complete, current or upcoming. Completed steps get a check mark, and the current one carries aria-current="step" for screen readers. The component has two layouts: a compact horizontal strip, and a vertical checklist that can hold an action button and a hint for the current step.

The empty Executions page titled No workflow runs yet, with a four-step checklist where the first three steps are done and Deploy and enable is current, next to a Go to Deployments button

3. Working Out Where the User Is

A checklist only helps if it's right. We derive the stage from data the app already has, the user's projects and deployments, instead of tracking onboarding progress separately:

  • No projects yet: create a project.
  • A project with no workflows: build a workflow.
  • Workflows, but nothing published: publish.
  • A published version, but no deployment: deploy.
  • A deployment with nothing that can run: enable.
  • An enabled workflow in an enabled deployment: live.
A flowchart of five yes or no checks, from an enabled workflow in an enabled deployment down to any project at all, each yes leading to a stage (Live, Enable, Deploy, Publish, Build workflow) and the last no leading to Create project, with the journey steps each stage marks as done or current

Each signal implies the ones before it, so the stage is the furthest signal that holds:

const getStage = (projects: Project[], projectDeployments: ProjectDeployment[]) => {
    if (projectDeployments.some(canRun)) return 'live';
    if (projectDeployments.length > 0) return 'enable';
    if (projects.some((project) => project.lastPublishedDate != null)) return 'deploy';
    if (projects.some(hasWorkflows)) return 'publish';
    if (projects.length > 0) return 'buildWorkflow';

    return 'createProject';
};

Since there's no separate onboarding record, there's nothing to fall out of sync. Delete your only deployment and the journey moves back a step by itself.

The journey is also cheap to load. Only an empty state requests it, so a page full of items makes no extra requests, and its queries share cache keys with the Projects and Deployments lists, so the data is usually cached already.

4. One Page, Several Empty States

With the stage known, a page can have more than one empty state. Deployments now has three:

  • "Nothing to deploy yet" appears before any workflow exists and sends you to Projects.
  • "Publish a project to deploy it" explains that deployments run a published, read-only version. If exactly one project is ready to publish, its button opens that project.
  • "Create your first deployment" is the only one that offers the deployment dialog, because at that stage you can finish it.
The empty Deployments page titled Create your first deployment, with a Create Deployment button, a horizontal journey with three completed steps and Deploy and enable current, a note that deployments are separate for each environment, and a How deployments work link

Executions got the same treatment. On a first run it hides the filters and shows the vertical journey with an action for the current step. With a disabled deployment it asks you to enable a deployed workflow. With an enabled one it shows "Waiting for the first run" and points out that test runs from the editor aren't listed there.

When a page is empty because of your filters rather than your progress, it says nothing matches and offers Clear filters.

5. The Rules We Ended Up With

The shared EmptyState component handles most of these:

  1. Explain what belongs on the page. "A connection stores the credentials an app needs, like an API key or an OAuth sign-in, so workflow steps can act for you" tells a new user far more than "No connections."
  2. Offer a next step the user can finish, and never a button into a dead end.
  3. Show where the page sits in the journey.
  4. Hide controls with nothing to act on. First-run pages drop their category and tag sidebars and their filters.
  5. Say when a list is scoped. With more than one environment, a note says the list is separate for each environment and names the one you're viewing, which heads off "where did my connection go?"
  6. Link to the docs for anyone who wants the long version.
  7. Track the clicks. Every empty-state button sends an analytics event with the page, the action and the journey stage, so we can see where people get stuck.
The empty Connections page titled Connect your first app, explaining that a connection stores the credentials an app needs, with a Create Connection button, an environment note and a How connections work link

Conclusion

Our empty pages used to describe what was missing. They now read the user's projects and deployments, say which of the four steps comes next, and only offer buttons that lead somewhere the user can finish.

Create a fresh workspace in ByteChef, open the Executions page and follow the steps, then tell us on GitHub where you got stuck.

Related posts