A tool for managing BigCommerce widgets

The development workflow for BigCommerce widgets can be a bit fiddly – modifying your schema or template and then sending the update via Postman.

🛠 Recently, I stumbled on a utility by Patrick Puente that shortens the lifecycle of updating widgets by specifying separate files for your widget schema, template and optionally storefront GraphQL query.

I recommend checking it out ➡️



I’ve talked a few times before about BigCommerce PageBuilder where you can help the content management of any sort of page within BigCommerce through the use of widgets – different sort of reusable components that can be plonked on the page, wherever you like.

So here I have an example widget, that I’ve talked about from our hack day and the actual admin interface for it, you can click on, insert a new row of cards, a widget, and update the images and text now, as I’ve said before, we’re using widgets extensively within our BigCommerce projects to enable this level of customizability for new projects.

Which makes a lot of sense. And to actually create a widget, you need to send an API request with a little bit of information in. So you need to send the name of the widget. So it’s visible in the admin area, the template, so BigCommerce uses handlebars. So you need your handlebars template there, and then you need your schema.

So the actual definition of the configuration options you will have in the admin area. You may also have things like the storefront graphQL query, which is a recent addition to maybe we need to pull additional information from the store and consume that in your template. Now this is all great, but you know, we’re finding now we’re having multiple widgets and on a store that we co-locate that code and the template and the schema in particular with our BigCommerce theme. And then on our deployment, we want to make sure that the theme is up to date and all of our widgets are up to date.

And even in development, kind of working directly with Postman for API requests, is a bit slow. And you don’t want to have to worry about compiling the template ready in this JSON format ready for submission. So we’ve been talking internally about having a little tool that would pull this information together: so you have a template file, you have a schema file and perhaps have a graphQL query file. And it’s just a little lightweight wrapper, so you can kind of update the template easily and quickly be able to push an update to BigCommerce. Now I was browsing around and actually found there was already a tool out there that will help us do this.

So hatertron3000, great name is actually Patrick Puente. I’m hoping I’m not doxing him at this point. Patrick Puente, Enterprise Solution Architect at BigCommerce. And now this is exactly what we need to do. It will take your API details for your BigCommerce store. And then it works just on an individual template, individual widget, right now.

But then it has separate files as I was describing. So you can manage your schema, your GraphQL queries and your templates. So I was going to quickly take you through what it looks like to use.

If I hop over to visual studio. I have here just a very simple widget. I was discussing with somebody recently who was trying to get a widget working.

It was just a good use case. So, if we get started again, just clear this, once you’ve installed it – it’s an NPM package, you can init it and I’ll ask you a few basic questions. So first is what’s your widgets template going to be called? Let’s call it Big Widget Demo. And then you have a few different options for actually getting you up and running.

Some basic schemas, i.e. the configuration area options. I’m going to choose tab for this one. And then we’ll need our API token. So you need to get this created by the store owner in the BigCommerce admin area. And it will particularly need the content modify permission. Put my token in, along with the store path.

Then it has finished and created some new files for me, a secrets file as well as a config file.

Now. If we look here we have our basic template as you’ve been able to see I’ve already modified this for the use case I’m discussing and similarly the schema.

You chose a tab which helped me get started, but I’ve then added to that. So here, we’re just having some basic typography options. So there’s a select box. It’s going to have heading “Heading”, with a few different h1 to h6 options as well as our paragraph option. And then we have an input class and ID field that you can complete it.

So once you’ve done that and you’re, you’re happy and you want to add this to BigCommerce, you would simply say big-widget push. And then it sends that to the BigCommerce. So you can see it’s been successful. We should have a new widget called Big Widget Demo. And then, once you got to get into the weeds with widgets, they have different versions as well as IDs.

So if we swap back to our page builder, I should now be able to refresh this page and here we have our new widget, so I can drop this into the top here. And we can see that we have all new dropdown with H1 to H6, we can enter our tests and have test classes and test IDs. And we have our new, new heading.

And I can go ahead and save that. That’ll take a little while and I’ll update the front end. Great. Now you can imagine if you need to kind of modify this template again, maybe change the schema. So maybe we’ll just tweak the heading text. Choose a heading style. Just kind of show you then we’ll go back to push our widget again.

Created a new version for us. And you see how this is kind of a lot easier than kind of fiddling with Postman, particularly for modifying templates. Now, once you have updated it, as I mentioned earlier, we have a versioning in widgets. So, because we’ve got a new version now, when we click on this, we’ll see a little pop up saying here, new widget update is available and we can force update this and get our new options shown in the admin. And obviously that’s a protection for when you’re releasing new widgets, we don’t necessarily want them all to be kind of immediately take effect on the site. So we don’t want to, you know, particular, if you’re shipping them with an app or something like that, you don’t want to kind of immediately change the look and feel of people’s sites, you need to kind of give that control to them. So this is a great way of doing that and it’s built into, to the to Page Builder. But you can also force it as well. So there’s an option when I’m submitting to force override and create, modify the same version. So that’s a quick tool. Was I, it doesn’t seem like many people have found it so far. So I just wanted to share as a great way of managing your widget templates in BigCommerce. Cheers.

Tom Robertshaw
Stay up to date with Hypa news and features