Streamlining Java Development with Backstage: A Guide to Software Templates

Starting a new software project can be exciting, but it often comes with challenges. You may need to set up the project structure, choose the right libraries, and follow your company’s standards. This takes time and can slow you down.
Backstage helps solve this problem. It provides tools to organize internal workflows, manage resources, and start new projects faster. One of its key features are software templates, which makes it easy to create new projects with all the right pieces in place.
In this article, you will learn why software templates are useful, how they work in Backstage, and how you can create your own for Java development. Even if you are new to Backstage, this article helps you to start.

Backstage: From Spotify to CNCF and Its Role in Platform Engineering

Backstage was originally built by Spotify to solve a common problem: managing tools, resources, and workflows across a fast-growing engineering organization. Spotify’s teams were spending too much time searching for information, configuring tools, or setting up new projects. Backstage became their developer portal – a single place where engineers could access everything they needed to build, deploy, and maintain software efficiently.

Recognizing its potential to help other organizations, Spotify open-sourced Backstage in 2020. Since then, it has gained rapid adoption across companies of all sizes. Its importance was solidified when it was accepted as a Cloud Native Computing Foundation (CNCF) project. This move has made Backstage a cornerstone of modern platform engineering practices, backed by a community of contributors and robust CNCF support.

Why Developer Portals Are Essential for Platform Engineering

In platform engineering, the goal is to provide developers with self-service capabilities while fostering best practices and ensuring compliance. A developer portal like Backstage is a critical part of this strategy. It gives developers a central place to:

• Find tools and services: Everything from CI/CD pipelines to APIs and documentation is in one place.
• Onboard new projects: Software templates let teams start projects quickly while adhering to organizational standards.
• Manage complexity: As organizations grow, so does the number of tools and processes. A portal reduces this complexity by integrating them into a unified interface.

By providing a consistent developer experience, a portal like Backstage improves productivity, reduces frustration, and helps engineers focus on building great software.

Why should Java Developers Care?

For Java developers, embracing a developer portal like Backstage isn’t just about using the platform; it’s about becoming active contributors to it. In a platform-as-a-product mindset, platforms are treated like products built for internal teams. Developers play a key role by:

• Defining templates: Creating Java project templates that standardize best practices and support new team members.
• Contributing plugins: Adding integrations for frameworks like Spring Boot or tools like Maven and Gradle.
• Improving workflows: Sharing feedback to enhance the platform and make development smoother.

In the world of microservices, APIs, and cloud-native development, a developer portal becomes the glue that holds teams and tools together. By contributing to Backstage, Java developers can shape their platform to better meet their needs while ensuring the entire organization benefits from consistency and automation.

Why Software Templates?

One of the main motivations for using software templates is to reduce repetitive work. Developers frequently perform the same setup tasks for every new project or service, such as creating boilerplate code, setting up directory structures, or adding standard configurations for tools like Maven, Gradle, or Podman. Automating these repetitive steps with templates saves significant time and reduces frustration, allowing developers to focus on the actual coding.

Another benefit of software templates is ensuring that best practices are consistently followed. Many organizations have specific requirements for how projects should be structured or how certain tools should be used. These might include guidelines for security libraries, CI/CD pipelines, or API design standards. With templates, these rules and practices are embedded into every new project, ensuring that developers automatically adhere to organizational guidelines without extra effort. Consistency across projects is another major advantage of using templates. In large organizations, inconsistency in project setups can lead to inefficiencies and confusion. For example, if one team uses a different logging library than another, it can complicate troubleshooting or maintenance. By starting every project from a standardized template, teams ensure a consistent foundation, making projects easier to manage and understand. Finally, software templates enable self-service development. A central goal of platform engineering is to empower developers with tools that let them work independently. Templates are a cornerstone of this approach, allowing developers to create new services, libraries, or applications without needing constant support from operations or platform teams. This self-service capability accelerates development while keeping teams aligned with organizational standards.

Backstage’s software templates take these benefits a step further by offering a flexible and scalable framework for defining reusable project blueprints. Developers can use templates to customize inputs, automate repetitive tasks, and integrate key organizational tools like compliance checks or Kubernetes deployments. For Java developers, this means faster project initiation, better standardization, and fewer roadblocks to innovation, freeing them to focus on writing the code that drives their business forward.

The Main Components of a Backstage Template

Backstage templates are designed to streamline project creation by providing a standardized and customizable framework. The Software Templates part of Backstage is a tool that can help you create Components inside Backstage. By default, it has the ability to load skeletons of code, template in some variables, and then publish the template to some locations like GitHub or GitLab. Templates are stored in the Software Catalog under a kind Template. Get an overview of the process and how they are loaded into Backstage in the official documentation.

Input Form: Collecting Customization Details

The input form is the initial interface presented to developers when initiating a new project. It gathers information to tailor the template to specific project requirements. For instance, a Java project template might request:

• Project Name: To define the repository, package, or application name.
• Team Ownership: To assign the appropriate team for responsibilities and notifications.
• Framework Selection: Options such as Quarkus, Langchain4J, or the specific Java version.

These fields are defined in the template’s YAML file, specifying parameters, validation rules, and default values.
For detailed guidance on defining input forms, refer to the Backstage documentation on writing templates.

Scaffolder: Generating the Project
After the input form is completed, the scaffolder processes the provided data to generate the actual project structure. Its responsibilities include:

• File Generation: Creating boilerplate code, configuration files, and directory structures.
• Content Customization: Incorporating input data to personalize files (e.g., replacing placeholders with the project name or team details).
• Command Execution: Running scripts to initialize the project, install dependencies, or generate additional resources.

In a Java project context, the scaffolder might create a Maven pom.xml file, configure a Quarkus application, and initialize a Git repository. The scaffolder comes with several built-in actions for fetching content, registering in the catalog and of course actions for creating and publishing a git repository. Scaffolder modules can extend scaffolding actions and provide additional functionality. Think of them as plug-ins that can be added.

The Red Hat Developer Hub Software Templates Library contains a collection of software templates designed to illustrate best practices in software development and deployment. They cover a wide range of technologies and frameworks, ensuring you have a suitable starting point for your project’s needs. You can also find some Quarkus and Maven based examples in there.

Steps in the Scaffolding Action: Orchestrating Project Setup
What could be confused for a real workflow is basically just steps to be executed during the scaffolding process. Steps define the sequence of actions that must occur to create the project. These steps allow for granular customization of the setup process and may include tasks such as:

• Repository Creation: Automatically setting up a GitHub or GitLab repository and pushing the initial code.
• CI/CD Pipeline Configuration: Establishing continuous integration and deployment pipelines tailored to the new project.
• Environment Provisioning: Deploying the application to development environments like Kubernetes or cloud platforms.
• Notifications and Follow-up Actions: Sending alerts to the responsible team or prompting additional actions.

While Backstage excels in standardizing project creation and management, it lacks native support for complex workflow orchestration. To address this gap, third-party plugins like the Orchestrator Plugin have been developed. This plugin enhances Backstage by enabling the design and execution of intricate workflows, offering features such as a graphical editor for visualization, integration with the service catalog, form generation, and runtime monitoring of workflow instances. By incorporating such plugins, organizations can extend Backstage’s capabilities to include comprehensive workflow management, thereby streamlining development processes and improving operational efficiency.

Bringing it all together

While software templates are basically yaml files with some logic, the custom scaffolder actions and a company specific selection of project types and artifacts make any Backstage instance a rich source of knowledge over time.

As Backstage continues to evolve under the CNCF, its open-source ecosystem provides a unique opportunity for Java developers to contribute and shape its future. By creating custom templates, plugins, and enhancements, developers can ensure the platform meets their specific needs while helping their organizations succeed in an increasingly complex software landscape. With tools like Backstage and its growing ecosystem, Java developers are well-positioned to embrace platform engineering and drive innovation across their teams.

If you want to get started quickly, take a look at the Red Hat Developer Hub and the supporting GitHub repositories with templates and further information to get you started.