docs: start creating a golden path (#30925)

* docs: starting to fill out the plugin golden path Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * another bit of work Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * create-app docs Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * Apply suggestions from code review Co-authored-by: Peter Macdonald <peterm4c@pm.me> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> * address PR feedback Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * update to rspack Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * fix lint errors Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * add flag for golden paths Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> --------- Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Co-authored-by: Peter Macdonald <peterm4c@pm.me>
2025-10-22 12:02:43 -04:00
parent 2a49760606
commit 9f298e81ee
18 changed files with 1348 additions and 38 deletions
@@ -0,0 +1,55 @@
+---
+id: 001-first-steps
+sidebar_label: 001 - Scaffolding the plugin
+title: How to scaffold a new plugin?
+---
+
+# Scaffolding a new plugin
+
+<!-- Talk through how to run the `backstage-cli create` command as well as what the output it creates is. This should touch on why we install this into `packages/backend`. -->
+
+## `yarn new`
+
+A new, bare-bones backend plugin package can be created by issuing the following
+command in your Backstage repository's root directory and selecting `backend-plugin`:
+
+```sh
+yarn new
+```
+
+You will be asked to supply a name for the plugin. This is an identifier that
+will be part of the NPM package name, so make it short and containing only
+lowercase characters separated by dashes, for our example, you should provide `todo`. For plugins you may write in the future, this should be an easy to remember indicator of what this plugins does, like if it's a
+package that adds an integration with a system named Carmen, you would want to name it `carmen`.
+
+This will create a new NPM package with a package name something like `@internal/plugin-carmen-backend`, depending on the other flags passed to the `new` command, and your settings for the `new` command in your root `package.json`. For future reference, we also support additional flags and configuration. Learn more at [the CLI docs](../../../tooling/cli/03-commands.md#new).
+
+Creating the plugin will take a little while, so be patient. If it runs with no issues, it will run the initial installation and build commands, so that your package is ready to be hacked on!
+
+Once the commands complete, you should see a new folder `plugins/todo-backend` with content like the below tree:
+
+```
+/ <- your Backstage app's root directory
+    /plugins/
+        /todo-backend/
+            package.json
+            README.md
+            eslintrc.js
+            /dev/
+                index.ts
+            /src/
+                plugin.ts
+                index.ts
+                router.ts
+                /services/
+                    /TodoListService/
+                        TodoListService.ts
+                        types.ts
+                        index.ts
+```
+
+<!-- TODO: describe each of the above files -->
+
+### FAQs
+
+<!-- List of commonly occurring problems during install -->
@@ -0,0 +1,34 @@
+---
+id: 002-poking-around
+sidebar_label: 002 - Poking around
+title: 002 - Poking around
+---
+
+## Default plugin functionality
+
+By default, that plugin that you just created hosts a simple todo list application. It exposes an HTTP API at `http://localhost:7007/api/todo/todos` that allows you to create TODOs, list existing TODOs, and get a specific TODO. It stores those TODOs in memory, which means that you would lose all of your TODOs if you restarted your application. It also allows you to tag TODOs with a Software Catalog entity, which will be useful for our frontend integration.
+
+To make this plugin production ready, we'll need to adjust a few things,
+
+1. Write our TODOs to a database so they don't get lost on restart.
+2. Write some proper tests to make sure everything works the way we expect.
+3. Get user feedback.
+
+## Testing locally
+
+Before we jump in to making this plugin ready to ship, let's walk through how to run it locally. If you open your backend plugin's manifest (`plugins/todo-backend/package.json`), and look at the `scripts` section, you'll notice a few important commands. The ones relevant to use right now are
+
+1. `yarn start` - Starts a local development server using the content in `dev/index.ts` as the backend.
+2. `yarn test` - Runs all of the tests for your backend plugin.
+
+If you run `yarn start`, you should see a custom backend for just your plugin start up. This will simplify plugin development and iteration for you or your team by easily testing out new features in just your plugin - just make sure you add what you need to the global `packages/backend`. The important log for us to look for is
+
+```
+2025-06-08T16:14:53.229Z rootHttpRouter info Listening on :7007
+```
+
+This indicates that your HTTP server is up and running and we can start sending test HTTP requests. Grab your favorite HTTP client and let's get testing! If you aren't sure what to use, I'd recommend the `humao.rest-client` VSCode extension which can easily be run in VSCode itself with very little extra set up.
+
+```
+
+```
@@ -88,44 +88,6 @@ After verifying everything, introduce the problem of persistence - the todos are

 Saving values to the database. Writing a migrations file. Plumbing through the database service.

-## Integrations
-
-Now that our plugin is ready for prime time, let's see how we can really leverage the rest of the Backstage ecosystem. Backstage provides a set of core features out of the box, namely, the Software Catalog, Search, Permissions, and Notifications.
-
-### Catalog
-
-We want to show our todos as separate Catalog entities. How can we make this happen?
-
-### Search
-
-We want to make our todos searchable.
-
-### Permissions
-
-We only want users to be able to find their own todos.
-
-### Notifications
-
-We want to set an alarm time for todos that sends a notification when the time is met.
-
 ## SCM Integrations

 Our users love the new plugin, and now they want it to automatically fetch todos from their source code.
-
-## Additional Resources and Further Reading
-
- **Real-world Implementations and Lessons**
-
-  - [Case studies and examples from the community](https://github.com/backstage/community#newsletters).
-  - Best practices derived from mature implementations.
-  - [Existing open-source community-maintained plugins](https://github.com/backstage/community-plugins).
-
- **Resource Compendium**
-
-  - [Backstage Glossary](https://backstage.io/docs/references/glossary) of key terms.
-  - Recommended readings and tools for advanced developers.
-
- **Certification and Learning Pathways**
-  - Pathways to deepen your understanding and expertise in plugin development for Backstage.
-
-Stay tuned for detailed exploration and guidance in each of these modules. We're excited to accompany you on your plugin development journey!
@@ -0,0 +1,23 @@
+## Learning Recap
+
+With this golden path, you learned how to,
+
+<!-- TODO -->
+
+## Additional Resources and Further Reading
+
+- **Real-world Implementations and Lessons**
+
+  - [Case studies and examples from the community](https://github.com/backstage/community#newsletters).
+  - Best practices derived from mature implementations.
+  - [Existing open-source community-maintained plugins](https://github.com/backstage/community-plugins).
+
+- **Resource Compendium**
+
+  - [Backstage Glossary](https://backstage.io/docs/references/glossary) of key terms.
+  - Recommended readings and tools for advanced developers.
+
+- **Certification and Learning Pathways**
+  - Pathways to deepen your understanding and expertise in plugin development for Backstage.
+
+Stay tuned for detailed exploration and guidance in each of these modules. We're excited to accompany you on your plugin development journey!
@@ -0,0 +1,12 @@
+POST http://localhost:7007/api/todo/todos
+Content-Type: application/json
+
+{
+  "title": "My First TODO"
+}
+
+###
+
+GET http://localhost:7007/api/todo/todos
+
+###
@@ -0,0 +1,33 @@
+---
+id: index
+sidebar_label: Backstage Plugins!
+title: How to create plugins with Backstage
+---
+
+### Prerequisites
+
+- We expect that you have finished the create-app golden path.
+
+### Scenario
+
+You have an awesome idea to create a todo list tracker in your Backstage instance at an upcoming company hackathon. Backstage is supposed to unify all of our information after all, it should track future tasks to complete as well!
+
+Many of the great Backstage plugins started in a similar way, a developer noticed that others on their team or in the company were:
+
+- Wasting time manually compiling spreadsheets filled with error-prone data
+- Spending hours every week trying to find that one specific link from that one site
+- A million other problems that impact developer flow or are just toil
+
+  And they decided to create a shared plugin in Backstage to solve that problem.
+
+This guide will teach you how to deliver high-quality Backstage plugins with confidence. Both so you can impress everyone at the hackathon and set yourself up for success when you inevitably are asked to make your plugin production-ready.
+
+### Structure
+
+To start, this guide will walk through creating a backend plugin. You'll get your feet wet working with an HTTP API, a database and the Backstage backend system. Then, we'll move to the frontend, where we'll show you how to create a new page that's visible to your Backstage users as well as how to call your API. Finally, we'll walk through some common integrations you may want to consider as you write plugins.
+
+### Next Steps
+
+- [Why build plugins?](./why-build-plugins.md)
+- [Sustainable plugin development](./sustainable-plugin-development.md)
+- [Golden path: Backend plugins](./backend/001-first-steps.md)
@@ -0,0 +1,19 @@
+## Integrations
+
+Now that our plugin is ready for prime time, let's see how we can really leverage the rest of the Backstage ecosystem. Backstage provides a set of core features out of the box, namely, the Software Catalog, Search, Permissions, and Notifications.
+
+### Catalog
+
+We want to show our todos as separate Catalog entities. How can we make this happen?
+
+### Search
+
+We want to make our todos searchable.
+
+### Permissions
+
+We only want users to be able to find their own todos.
+
+### Notifications
+
+We want to set an alarm time for todos that sends a notification when the time is met.
@@ -0,0 +1,29 @@
+---
+id: sustainable-plugin-development
+sidebar_label: Sustainable plugin development
+title: Sustainably developing plugins in Backstage
+---
+
+Plugins are not created in a vacuum, they generally solve a customer ask, be that
+
+- a business problem, like showing cloud spend
+- a new integration, like showing data from an external vendor such as Pagerduty
+- a developer pain point, like organizing information from disjoint or disorganized systems.
+
+To ensure that your plugin lives the test of time, you'll need to figure out how to keep it up-to-date,
+
+### Finding your stakeholders
+
+<!-- TODO -->
+
+### Iterating on your plugin
+
+In many cases, your first version of a plugin will cut a few corners - this is a good sign, you're more focused on delivering a strong use case to continue development than over-indexing on your initial code. It may be temporary after all, if you don't get the response you're looking for!
+
+So, how do you decide when you should iterate on your plugin?
+
+<!-- TODO -->
+
+### Ensuring the success of your plugin
+
+<!-- TODO -->
@@ -0,0 +1,33 @@
+---
+id: why-build-plugins
+sidebar_label: Why build plugins?
+title: Introduction to the Value and Impact of Plugins within Backstage
+---
+
+Backstage plugins are essential components that enable the integration of various tools and services into a unified developer portal. Here’s a detailed look at why building plugins for Backstage can be highly beneficial:
+
+## Enhancing Developer Productivity
+
+Plugins in Backstage centralize and simplify access to tools, reducing the time developers spend switching between different systems. By providing a consistent interface and user experience, plugins minimize cognitive load and streamline workflows, allowing developers to focus more on coding and less on tool management. Plugins can leverage platform APIs and reusable UI components to integrate external data and services seamlessly.
+
+## Customizable and Extensible Platform
+
+Backstage's plugin architecture is designed to be highly flexible, enabling the integration of nearly any infrastructure or software development tool. This extensibility allows organizations to tailor Backstage to meet their specific needs, integrating internal tools, third-party services, and other custom functionalities seamlessly. For detailed guidelines on plugin development, refer to the [Backstage Plugin Development documentation](https://backstage.io/docs/plugins/plugin-development/).
+
+## Improved Collaboration and Knowledge Sharing
+
+Plugins facilitate better collaboration among teams by consolidating documentation, code repositories, CI/CD pipelines, and monitoring tools in one place. This centralization makes it easier for team members to find information, share insights, and collaborate on projects, enhancing overall team productivity and coherence.
+
+## Consistency and Best Practices
+
+By adhering to Backstage’s design guidelines, plugins ensure a consistent user experience across the platform. This consistency helps in maintaining usability and reducing the learning curve for new users, promoting the adoption of best practices within development teams. More details can be found in the [Introduction to Plugins](https://backstage.io/docs/plugins/) section.
+
+## Scalability and Maintenance
+
+Backstage plugins are designed to be modular and independent, allowing for easy updates and maintenance without affecting the overall system. This modularity supports horizontal scalability, where each plugin can be scaled independently according to the needs of the application, ensuring robust performance and reliability. For more on structuring and connecting plugins, see the [Structure of a Plugin](https://backstage.io/docs/plugins/structure-of-a-plugin) documentation.
+
+## Community and Ecosystem Growth
+
+Developing and contributing plugins to the Backstage community helps in expanding the ecosystem. Open-source contributions foster innovation and collaboration, allowing developers to leverage a wide range of existing plugins and avoid reinventing the wheel. This collaborative environment accelerates the development of new features and enhances the overall value of the Backstage platform.
+
+Building plugins for Backstage significantly enhances developer productivity, promotes best practices, supports scalability, and fosters community growth. These plugins transform Backstage into a comprehensive developer portal that can adapt to the unique needs of any organization. For more detailed information, refer to the [Backstage Plugin Development documentation](https://backstage.io/docs/plugins/plugin-development/) and the [Introduction to Plugins](https://backstage.io/docs/plugins/).