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>
This commit is contained in:
milliehartnt123
@@ -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
|
||||
|
||||
|
||||
To create the component:
|
||||
|
||||
- You should see the following screen:
|
||||
1. Select `Create`.
|
||||
|
||||
|
||||
|
||||
|
||||
- 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
|
||||
|
||||
|
||||
5. For this example, enter `tutorial` for the `Name` of the service. and select `NEXT`.
|
||||
|
||||
|
||||
|
||||
6. Enter your GitHub user name as the `Owner`.
|
||||
7. Enter `tutorial` for the `Repository` and select `REVIEW`.
|
||||
|
||||
8. Review the information and select `CREATE`.
|
||||
|
||||
|
||||
|
||||
If you see an error message, similar to the following,
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Selecting `Home` in the sidebar, displays the new `tutorial` component in the catalog.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user