DEV Community

Cover image for Tips and tricks for Backstage Software Templates
Jean-Louis FEREY
Jean-Louis FEREY

Posted on

Tips and tricks for Backstage Software Templates

Intro

I'm a big fan of Backstage.

If you don't know what Backstage is, have a look on this short video:

Software templates

There is a lot of interesting features in Backstage, but one of my favorite is the Software Templates. This feature is already well explained by Ricardo Castro on dev.to.

I like this feature because it permit what I call "standardization by ease", in opposition to standardization by constraint when somewhere in your organization, a "code police", impose a law without telling how to implement it in your code.

With Software Templates, you can provide to your developers some state-of-the-art project (in term of coding, ci/cd, security, documentation) which will be automatically pushed in a repo of your scm system (Github, Gitlab Bitbucket, ...). And they will follow the best practices because it helps them.

Software Templates can also be used to onboard an existing component in Backstage by creating a pull request (on Github) or a merge request (on Gitlab) which propose to the project to add in the repo the catalog-info.yaml file used by Backstage to index the project.

Learn from the community

The best way to start with Software Templates is to learn from others.

The first place to learn is, of course, the Backstage documentation.

But, in my opinion, it's easier to see how others are building their templates. For that you should have a look on:

Use Backstage tools

When you begin on Software Templates, as for any other languages, you make mistakes and it's a little bit boring to modify your code, to push it in your Software Templates repository, then to try it in Backstage, to see it does not work.

Fortunately, Backstage will help you with that. There is a special place in Backstage for trying and tuning your templates. You can try it on https://YourBackstageInstance/create/edit. For instance, on the janus showcase portal:

Backstage create edit page

Edit template form

When you click on Edit template form, you access to a place where you will be able to write your template, and to see immediately if it works:

Backstage create edit template form

Custom field explorer

Paraphrasing the documentation of Backstage, collecting input from the user is a very large part of the scaffolding process and Software Templates as a whole. These input are made in software templates by using custom fields, for instance the Repository Picker.

Sometimes, it's not easy to understand all the possibilities of these objects.

Here again, you can explore them with the custom field explorer, for instance the OwnerEntityPicker:

Backstage create edit custom field

In this example, we add group in allowedKinds to limit the choice on groups, and we can see immediately the result:

Backstage create edit custom field result

Built-in actions

There are three parts in a software template:

  • the parameters where you get inputs from your customer
  • the steps where you do some things with information collected in the first part
  • the output where you give some information to your customer about the tasks done by the template.

To do things in steps, you use builtin actions, and all these actions are not listed in the documentation. But there are listed directly in the application on https://YourBackstageInstance/create/actions. For instance, on the janus showcase portal:

Backstage builtin actions page

It's very useful when you want to know all capabilities of an action, for instance publish:gitlab

Backstage builtin actions publish gitlab

Some actions have even some examples:

Backstage builtin actions debug examples

Conclusion

To faster you Backstage Software Templates learning curve:

Top comments (0)