From ec98492a5f1444d30d7227f79296449c8ed3771e Mon Sep 17 00:00:00 2001 From: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> Date: Wed, 5 Nov 2025 10:52:42 -0500 Subject: [PATCH] Revise component creation guide Updated the guide to create a component using Software Templates, enhancing clarity and structure. Added detailed steps, additional supporting information, and corrected formatting for better readability. Updated graphics. Signed-off-by: milliehartnt123 <108491788+milliehartnt123@users.noreply.github.com> --- docs/getting-started/create-a-component.md | 111 +++++++++++++++++---- 1 file changed, 91 insertions(+), 20 deletions(-) diff --git a/docs/getting-started/create-a-component.md b/docs/getting-started/create-a-component.md index 29ba99db83..37dd7514cc 100644 --- a/docs/getting-started/create-a-component.md +++ b/docs/getting-started/create-a-component.md @@ -6,38 +6,109 @@ description: Leverage the scaffolder to start creating components with best prac Audience: Developers -## Summary +## Overview -This guide will walk you through how to use Software Templates to create new components with baked in best practices. +Components in the software catalog are created using a software template. Templates load skeletons of code, which can include some variables, and incorporate your company's best pracitces. The templates are published to a location, such as GitHub or GitLab. + +The standalone Backstage application includes the `Example Node.js Template`, which is an example template for the scaffolder that creates a simple Node.js service. You can also [create your own templates](../features/software-templates/adding-templates.md). ## Prerequisites -:::note +For this example, the default Note.js template will be used. The template creates a repository in GitHub and adds the necessary files to it so that the component is integrated into the software catalog. Because you are creating a repository, you must first create an integration between Backstage and GitHub. -If you're running Backstage with Node 20 or later, you'll need to pass the flag `--no-node-snapshot` to Node in order to use the templates feature. One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage: `export NODE_OPTIONS=--no-node-snapshot` +- You should have already [installed a standalone app](../getting-started/index.md). -::: +- If you are running Backstage with Node 20 or later, pass the flag `--no-node-snapshot` to Node in order to use the templates feature to create new components. One way to do this is to specify the `NODE_OPTIONS` environment variable before starting Backstage: -You should already have [a standalone app](./index.md). + ``` + export NODE_OPTIONS=--no-node-snapshot + ``` -You will also need to register the [GitHub Scaffolder Action module](../features/software-templates/builtin-actions.md#installing-action-modules) before moving forward. +- Register the [GitHub Scaffolder Action module](../features/software-templates/builtin-actions.md#installing-action-modules). -## Creating your component +- [Setup up a GitHub Integration](../getting-started/config/authentication.md#setting-up-a-github-integration) with Backstage, using a GitHub Personal Access Token. -- Go to `create` and choose to create a website with the `Example Node.js Template` -- Type in a name, let's use `tutorial` and click `Next Step` +## Creating the component -![Software template deployment input screen asking for a name](../assets/getting-started/b-scaffold-1.png) +To create the component: -- You should see the following screen: +1. Select `Create`. -![Software template deployment input screen asking for the GitHub username, and name of the new repo to create](../assets/getting-started/b-scaffold-2.png) + ![select create for new component](../assets/getting-started/select-create-for-new-component.png) -- For host, it should default to github.com -- As owner, type your GitHub username -- For the repository name, type `tutorial`. Go to the next step +2. Select `Service` in the `CATEGORIES` dropdown list. +3. Select the `Owner`. For this example, you can select `guest`. +4. Select `Choose` in the `Example Node.js Template`. -- Review the details of this new service, and press `Create` if you want to - deploy it like this. -- You can follow along with the progress, and as soon as every step is - finished, you can take a look at your new service + ![setup-nodejs-categories-owners](../assets/getting-started/setup-nodejs-cat-owner.png) + +5. For this example, enter `tutorial` for the `Name` of the service. and select `NEXT`. + + ![enter name of new component](../assets/getting-started/enter-name-of-new-component.png) + +6. Enter your GitHub user name as the `Owner`. +7. Enter `tutorial` for the `Repository` and select `REVIEW`. + ![select review create component](../assets/getting-started/select-review-create-component.png) +8. Review the information and select `CREATE`. + + ![select create to make component](../assets/getting-started/select-create-to-make-component.png) + +If you see an error message, similar to the following, + + ![error creating new component](../assets/getting-started/error-creating-new-component.png) + +Perform the following steps: + +1. Close the Backstage app. +2. Enter `CTRL-C` in the terminal window to stop the Backstage frontend and backend. +3. In the terminal window, enter: + + ``` + export NODE_OPTIONS=--no-node-snapshot + ``` + +4. Enter `yarn start` to restart the Backstage application. + e. Repeat steps to create the component. + +Otherwise, you can follow along with the progress, and as soon as every step is finished, you can take a look at your new service in either the repository or the catalog. + +![run of example of create component](../assets/getting-started/successful-create-new-coponent.png) + +Selecting `REPOSITORY` displays the files in the main branch of the new `tutorial` repository. When you created the new `tutorial` component, three files were created in the repository + +- **catalog-info.yaml** - Describes the entity for the software catalog. [Descriptor Format of Catalog Entities](../features/software-catalog/descriptor-format.md) provides additional information. + + ``` + apiVersion: backstage.io/v1alpha1 + kind: Component + metadata: + name: "tutorial" + spec: + type: service + owner: user:guest + lifecycle: experimental + ``` + +- **index.js** - + + ``` + console.log('Hello from tutorial!'); + ``` + +- **package.json** - + + ``` + { + "name": "tutorial", + "private": true, + "dependencies": {} + } + ``` + +Selecting `OPEN IN CATALOG` displays details of the new component, such as its relationships, links, and subcomponents. + +![select open in catalog](../assets/getting-started/tutorial-component-open-in-catalog.png) + +Selecting `Home` in the sidebar, displays the new `tutorial` component in the catalog. + +![new turorial component in software catalog](../assets/getting-started/new-tutorial-component-in-software-catalog.png)