Modular Backstage Plugins: Solving the Monolithic Plugin Problem

[JayGolf]

Authored by: Yashika Bhatia 

Co-Authored by: Sonu Singh

Introduction

Backstage.io is a powerful tool for building developer portals, and it offers a convenient way to create plugins that extend its capabilities. However, a common challenge when working with Backstage is that the default plugin creation process generates a monolithic structure. All plugins are created within a single repository, which leads to issues when you want to develop, build, and run plugins individually. This structure makes it difficult to scale, maintain, and test plugins in isolation, particularly when working with backend plugins that involve database interactions or proxy services. In this post, we’ll explore a solution to this problem: a Backstage template that allows you to create individual frontend and backend plugins, each with all necessary capabilities, including proxy services, database connections, and a Makefile to handle building and running them independently.

The Problem: Monolithic Plugin Architecture in Backstage

When you create a plugin in Backstage, it typically gets added to a single repository, along with all other plugins. While this approach works for small projects, it quickly becomes a burden in larger, more complex environments. The monolithic architecture has several drawbacks:

1. Difficult to Scale: As the number of plugins grows, managing them becomes increasingly complex.
2. Lack of Modularity: Each plugin is tightly coupled to the rest of the system, making it hard to develop or test in isolation.
3. Build and Deployment Challenges: Changes to one plugin often require rebuilding the entire project, slowing down development.
4. Backend Integration: Plugins that require backend services, such as those that interact with databases, become harder to manage because they cannot be easily separated from the front end and other parts of the system.

To address these challenges, we need a modular approach where each plugin can be built and run independently, yet still leverage the full power of Backstage.

The Solution: A Modular Backstage Template

The solution lies in creating a Backstage template that generates both frontend and backend plugins as independent entities, each capable of running and building separately. This approach allows developers to work on each plugin in isolation while retaining the ability to use essential Backstage features, such as the proxy service and backend integrations for handling database-related changes. With this template, every plugin will include:

1. Frontend and Backend Skeleton: A pre-configured structure for both frontend and backend plugins.
2. Proxy Service Integration: A built-in proxy setup to handle API requests from the frontend to the backend.
3. Backend Plugin with Database Support: A backend structure that supports database interactions and other backend-specific logic.
4. Makefile for Independent Builds: A Makefile for each plugin, allows developers to build and run them separately without touching the rest of the repository.

Why Modularity Matters

The modular approach offers several key advantages over the traditional monolithic setup:

1. Independent Development: Each plugin can be developed, built, and tested individually. This means changes to one plugin don’t affect others, making it easier to manage large projects with multiple teams.
2. Simplified CI/CD Pipelines: With modular plugins, you can set up CI/CD pipelines that only trigger for the plugin being modified, rather than for the entire project.
3. Better Scalability: As your Backstage instance grows, you can add or remove plugins without disrupting the core system.
4. Backend Flexibility: Backend plugins can be managed separately, making it easier to handle database schema changes, migrations, or scaling services independently.

How the Template Works

The template we’re using creates both frontend and backend plugins under a single plugin entity. Each plugin contains everything it needs to run independently while being fully integrated with Backstage. Here’s what you get in the template:

1. Frontend Plugin: A basic setup that includes routes, proxy configuration, and any required UI components.
2. Backend Plugin: A backend structure that handles services, such as database interactions or external API calls. This plugin is ready for additional backend logic like migrations or handling specific API requests.
3. Proxy Service: A pre-configured proxy setup that ensures the frontend can communicate securely with the backend plugin, following Backstage’s best practices.
4. Makefile: Each plugin comes with a Makefile that includes commands to build and start the plugin independently. This allows you to work on each plugin without needing to start the entire Backstage app.

Step-by-Step Guide: Setting Up Modular Plugins with Predefined Templates

In this section, we’ll walk through the process of setting up modular plugins using predefined templates available in our Backstage instance. These templates are designed to generate the structure for both frontend and backend plugins, allowing you to quickly customize and build upon them. You’ll also be prompted to enter specific details, such as app name and repository, to create the plugins.

Step 1: Use the Predefined Templates to Generate the Plugins

Our Backstage instance comes with two predefined templates:

• Frontend Plugin Template: This creates a plugin structure with routes, UI components, and proxy configuration.
• Backend Plugin Template: This generates a backend structure with database integration, proxy service setup, and additional backend logic.

To create a plugin, navigate to the Backstage Software Templates under /create endpoint in your instance. You’ll be prompted to select either the Frontend Plugin Template or the Backend Plugin Template depending on what you need.

Step 2: Fill in the Required Fields

After selecting the appropriate template, you will be asked to provide some necessary fields for both frontend and backend plugins:

• App Name: The name of the plugin being created.
• Repository: The Git repository where the plugin’s code will be stored.

These fields are crucial for setting up the plugin in your Backstage instance and integrating it into your overall system.

Step 3: Customize the Generated Plugin

Once the plugin is generated, you will have a predefined structure for both the frontend and backend. You can now begin customizing the code to meet your specific needs. The plugin folders include:

• Frontend code: A basic structure with components and routing.
• Backend code: Includes proxy service and database interaction setup, allowing for backend logic to be added as needed.

Step 4: Use the Makefile to Build and Run Plugins

Each plugin comes with a Makefile to simplify the build and run process. Use the following commands to build and run them independently:

To build both the frontend and backend plugins:

make build

To run both the frontend and backend plugins:

make run

• The frontend plugin will be available at http://localhost:7003 by default.
• The backend plugin will be running at http://localhost:7000.

Conclusion

By using this modular approach with a Backstage template that generates both frontend and backend plugins, you can solve the problem of monolithic plugin structures. This approach enables independent development, easier scaling, and better flexibility when dealing with backend services like databases. If you’re working on a growing Backstage instance, this solution will make it easier to manage plugins, improve your development workflow, and allow for better scaling as your project expands. With this blog, you provide a clear problem and a practical solution, making it easier for developers to adopt modular plugin development in Backstage. Let me know if you’d like to make any adjustments!