docs: restructure local-dev and rename to tooling

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2024-05-17 11:28:17 +02:00
parent e6fb2dc950
commit a1ae9cc72c
20 changed files with 66 additions and 53 deletions
@@ -0,0 +1,5 @@
+---
+'@backstage/cli-node': patch
+---
+
+Updated doc link.
@@ -78,4 +78,4 @@ Plugins must always be designed to be horizontally scalable. This means that you

 ### Isolated

-Plugins must never communicate with each other directly through code, they may only communicate over the network. Plugins that wish to expose an external interface for other plugins and modules to use are recommended to do so through a [node-library](../../local-dev/cli-build-system.md#package-roles) package. The library should export an API client service to make calls to your plugin, or similar construct.
+Plugins must never communicate with each other directly through code, they may only communicate over the network. Plugins that wish to expose an external interface for other plugins and modules to use are recommended to do so through a [node-library](../../tooling/cli/02-build-system.md#package-roles) package. The library should export an API client service to make calls to your plugin, or similar construct.
@@ -101,7 +101,7 @@ CMD ["node", "packages/backend", "--config", "app-config.yaml"]

 For more details on how the `backend:bundle` command and the `skeleton.tar.gz`
 file works, see the
-[`backend:bundle` command docs](../local-dev/cli-commands.md#backendbundle).
+[`backend:bundle` command docs](../tooling/cli/03-commands.md#backendbundle).

 The `Dockerfile` is located at `packages/backend/Dockerfile`, but needs to be
 executed with the root of the repo as the build context, in order to get access
@@ -13,7 +13,7 @@ starting point that's meant to be evolved.

 The Backstage CLI has a command to bump all `@backstage` packages and
 dependencies you're using to the latest versions:
-[versions:bump](https://backstage.io/docs/local-dev/cli-commands#versionsbump).
+[versions:bump](https://backstage.io/docs/tooling/cli/03-commands#versionsbump).

 ```bash
 yarn backstage-cli versions:bump
@@ -70,7 +70,7 @@ example, depends on global referential equality. This can cause problems in
 Backstage with API lookup, or config loading.

 To help resolve these situations, the Backstage CLI has
-[versions:check](https://backstage.io/docs/local-dev/cli-commands#versionscheck). This
+[versions:check](https://backstage.io/docs/tooling/cli/03-commands#versionscheck). This
 will validate versions of `@backstage` packages in your app to check for
 duplicate definitions:

@@ -42,7 +42,7 @@ yarn backstage-cli create-github-app <github org>
 ```

 You can read more about the
-[`backstage-cli create-github-app`](../../local-dev/cli-commands.md#create-github-app) command.
+[`backstage-cli create-github-app`](../../tooling/cli/03-commands.md#create-github-app) command.

 Once you've gone through the CLI command, it should produce a YAML file in the
 root of the project which you can then use as an `include` in your
@@ -39,7 +39,7 @@ For this tutorial, we've automatically exported all permissions from this file (

 :::note Note

-We use a separate `todo-list-common` package since all permissions authorized by your plugin should be exported from a ["common-library" package](https://backstage.io/docs/local-dev/cli-build-system#package-roles). This allows Backstage integrators to reference them in frontend components as well as permission policies.
+We use a separate `todo-list-common` package since all permissions authorized by your plugin should be exported from a ["common-library" package](https://backstage.io/docs/tooling/cli/build-system#package-roles). This allows Backstage integrators to reference them in frontend components as well as permission policies.

 :::

@@ -11,7 +11,7 @@ A Backstage Plugin adds functionality to Backstage.
 To create a new frontend plugin, make sure you've run `yarn install` and installed
 dependencies, then run the following on your command line (a shortcut to
 invoking the
-[`backstage-cli new --select plugin`](../local-dev/cli-commands.md#new))
+[`backstage-cli new --select plugin`](../tooling/cli/03-commands.md#new))
 from the root of your project.

 ```bash
@@ -369,4 +369,4 @@ Note: wrapping in the test application **requires** you to do a `find()` or

 ## Debugging Jest Tests

-You can find it [here](https://backstage.io/docs/local-dev/cli-build-system#debugging-jest-tests)
+You can find it [here](https://backstage.io/docs/tooling/cli/build-system#debugging-jest-tests)
@@ -201,7 +201,7 @@ A service that hosts [packages](#package). The most prominent example is [NPM](h

 ## Package Role

-The declared role of a package, see [package roles](../local-dev/cli-build-system.md#package-roles).
+The declared role of a package, see [package roles](../tooling/cli/02-build-system.md#package-roles).

 ## Permission (core Backstage plugin)

@@ -12,7 +12,7 @@ A huge thanks to the whole team of maintainers and contributors as well as the a

 ### Support for experimental type build has been removed

-The `--experimental-type-build` option is no longer supported by any commands in the Backstage CLI. Existing usage should be migrated to using [subpath exports](https://backstage.io/docs/local-dev/cli-build-system#subpath-exports) instead.
+The `--experimental-type-build` option is no longer supported by any commands in the Backstage CLI. Existing usage should be migrated to using [subpath exports](https://backstage.io/docs/tooling/cli/build-system#subpath-exports) instead.

 ### Experimental support for Vite ⚡

@@ -1,5 +1,5 @@
 ---
-id: cli-overview
+id: overview
 title: Overview
 description: Overview of the Backstage CLI
 ---
@@ -7,12 +7,12 @@ description: Overview of the Backstage CLI
 ## Introduction

 A goal of Backstage is to provide a delightful developer experience in and
-around the project. Creating new [apps](../references/glossary.md#app) and
-[plugins](../references/glossary.md#plugin) should be simple, iteration
+around the project. Creating new [apps](../../references/glossary.md#app) and
+[plugins](../../references/glossary.md#plugin) should be simple, iteration
 speed should be fast, and the overhead of maintaining custom tooling should be
 minimal. As a part of accomplishing this goal, Backstage provides its own build
 system and tooling, delivered primarily through the
-[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) [package](../references/glossary.md#package). When
+[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) [package](../../references/glossary.md#package). When
 creating an app using
 [`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app),
 you receive a project that's already prepared with a typical setup and package
@@ -23,8 +23,8 @@ Under the hood the CLI uses [Webpack](https://webpack.js.org/) for bundling,
 [Jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for
 linting. It also includes tooling for working within Backstage apps, for example
 for keeping the app up to date and verifying static configuration. For a more
-in-depth look into the tooling, see the [build system](./cli-build-system.md)
-page, and for a list of commands, see the [commands](./cli-commands.md) page.
+in-depth look into the tooling, see the [build system](./02-build-system.md)
+page, and for a list of commands, see the [commands](./03-commands.md) page.

 While the Backstage tooling is opinionated in how it works, it is also possible
 to use your own tooling either partially or fully. For example, the CLI provides
@@ -1,5 +1,5 @@
 ---
-id: cli-build-system
+id: build-system
 title: Build System
 description: A deep dive into the Backstage build system
 ---
@@ -74,7 +74,7 @@ implemented in a typical Backstage app.

 ## Package Roles

-> Package roles were introduced in March 2022. To migrate existing projects, see the [migration guide](../tutorials/package-role-migration.md).
+> Package roles were introduced in March 2022. To migrate existing projects, see the [migration guide](../../tutorials/package-role-migration.md).

 The Backstage build system uses the concept of package roles in order to help keep
 configuration lean, provide utility and tooling, and enable optimizations. A package
@@ -258,7 +258,7 @@ When building CommonJS or ESM output, the build commands will always use
 `src/index.ts` as the entrypoint. All non-relative modules imports are considered
 external, meaning the Rollup build will only compile the source code of the package
 itself. All import statements of external dependencies, even within the same
-[monorepo](../references/glossary.md#monorepo), will stay intact.
+[monorepo](../../references/glossary.md#monorepo), will stay intact.

 The build of the type definitions works quite differently. The entrypoint of the
 type definition build is the relative location of the package within the
@@ -308,7 +308,7 @@ support for them instead.
 ### Frontend Production

 The frontend production bundling creates your typical web content
-[bundle](../references/glossary.md#bundle), all contained within a single
+[bundle](../../references/glossary.md#bundle), all contained within a single
 folder, ready for static serving. It is used when building packages with the
 `'frontend'` role, and unlike the development bundling there is no way to
 build a production bundle of an individual plugin.
@@ -1,5 +1,5 @@
 ---
-id: cli-commands
+id: commands
 title: Commands
 description: Descriptions of all commands available in the CLI.
 ---
@@ -102,7 +102,7 @@ Options:

 ## package start

-Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./cli-build-system.md#bundling) section for more details.
+Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./02-build-system.md#bundling) section for more details.

 ```text
 Usage: backstage-cli package start [options]
@@ -119,7 +119,7 @@ Options:

 ## package build

-Build an individual package based on its role. See the build system [building](./cli-build-system.md#building) and [bundling](./cli-build-system.md#bundling) sections for more details.
+Build an individual package based on its role. See the build system [building](./02-build-system.md#building) and [bundling](./02-build-system.md#bundling) sections for more details.

 ```text
 Usage: backstage-cli package build [options]
@@ -139,7 +139,7 @@ Options:
 Lint a package. In addition to the default `eslint` behavior, this command will
 include TypeScript files, treat warnings as errors, and default to linting the
 entire directory if no specific files are listed. For more information, see the
-build system [linting](./cli-build-system.md#linting) section.
+build system [linting](./02-build-system.md#linting) section.

 ```text
 Usage: backstage-cli package lint [options]
@@ -165,7 +165,7 @@ a yarn workspaces monorepo by automatically creating one grouped configuration
 that includes all packages that have `backstage-cli test` in their package
 `test` script.

-For more information about configuration overrides and editor support, see the [Jest Configuration section](./cli-build-system.md#jest-configuration) in the build system documentation.
+For more information about configuration overrides and editor support, see the [Jest Configuration section](./02-build-system.md#jest-configuration) in the build system documentation.

 ```text
 Usage: backstage-cli package test [options]
@@ -190,7 +190,7 @@ Delete cache directories

 This command should be added as `scripts.prepack` in all packages. It enables
 packaging- and publish-time overrides for fields inside `packages.json`.
-For more details, see the build system [publishing](./cli-build-system.md#publishing) section.
+For more details, see the build system [publishing](./02-build-system.md#publishing) section.

 ```text
 Usage: backstage-cli package prepack [options]
@@ -369,8 +369,8 @@ Usage: backstage-cli build-workspace [options] <workspace-dir>
 ## create-github-app

 Creates a GitHub App in your GitHub organization. This is an alternative to
-token-based [GitHub integration](../integrations/github/locations.md). See
-[GitHub Apps for Backstage Authentication](../integrations/github/github-apps.md).
+token-based [GitHub integration](../../integrations/github/locations.md). See
+[GitHub Apps for Backstage Authentication](../../integrations/github/github-apps.md).

 Launches a browser to create the App through GitHub and saves the result as a
 YAML file that can be referenced in the GitHub integration configuration.
@@ -10,7 +10,7 @@ information about the change can be found in the [original RFC](https://github.c

 Package roles are implemented through a well-known `"backstage"."role"` field in the
 `package.json` of each package. There are a handful of roles defined so far, and it
-is not possible to use values outside the [set of predefined roles](../local-dev/cli-build-system.md#package-roles).
+is not possible to use values outside the [set of predefined roles](../tooling/cli/02-build-system.md#package-roles).

 With roles in place in all packages, the Backstage CLI is able to automatically
 determine how to handle each package. For example, the different build commands
@@ -55,7 +55,7 @@ yarn backstage-cli migrate package-roles

 The automatic detection is not perfect, so it is recommended to manually review the
 roles that were assigned to each package.
-You can use the [package role definitions](../local-dev/cli-build-system.md#package-roles) as a reference.
+You can use the [package role definitions](../tooling/cli/02-build-system.md#package-roles) as a reference.

 ### Step 2 - Migrate package scripts

@@ -85,7 +85,7 @@ If you in the end do not want to use this exact script setup, it is still recomm

 ### Step 3 - Migrate package ESLint configurations

-An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the [build system documentation](../local-dev/cli-build-system.md#linting).
+An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the [build system documentation](../tooling/cli/02-build-system.md#linting).

 To migrate the ESLint configuration of all packages in your project, run the following command:

@@ -97,7 +97,7 @@ This will migrate all existing `.eslintrc.js` that extend the old configuration

 ### Step 4 - Use `backstage-cli repo`

-The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn` and can operate on multiple packages at once. You can read more about the `repo` command in the [CLI command documentation](../local-dev/cli-commands.md#repo-build).
+The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn` and can operate on multiple packages at once. You can read more about the `repo` command in the [CLI command documentation](../tooling/cli/03-commands.md#repo-build).

 The way to execute this step of the migration is not as well defined as the previous steps, as it depends on what your development and CI/CD setup looks like. Look for the following patterns to replace in your root `package.json` as well as CI/CD setup:

@@ -69,19 +69,6 @@
      "getting-started/keeping-backstage-updated",
      "getting-started/concepts"
    ],
-    "Local Development": [
-      {
-        "type": "category",
-        "label": "CLI",
-        "items": [
-          "local-dev/cli-overview",
-          "local-dev/cli-build-system",
-          "local-dev/cli-commands"
-        ]
-      },
-      "local-dev/linking-local-packages",
-      "local-dev/debugging"
-    ],
    "Core Features": [
      {
        "type": "category",
@@ -358,6 +345,25 @@
        ]
      }
    ],
+    "Tooling": [
+      {
+        "type": "category",
+        "label": "Backstage CLI",
+        "items": [
+          "tooling/cli/overview",
+          "tooling/cli/build-system",
+          "tooling/cli/commands"
+        ]
+      },
+      {
+        "type": "category",
+        "label": "Local Development",
+        "items": [
+          "tooling/local-dev/linking-local-packages",
+          "tooling/local-dev/debugging"
+        ]
+      }
+    ],
    "Deployment": [
      "deployment/index",
      "deployment/scaling",
@@ -33,12 +33,6 @@ nav:
          - Create a component: 'getting-started/create-a-component.md'
      - Keeping Backstage Updated: 'getting-started/keeping-backstage-updated.md'
      - Key Concepts: 'getting-started/concepts.md'
-  - Local Development:
-      - CLI:
-          - Overview: 'local-dev/cli-overview.md'
-          - Build System: 'local-dev/cli-build-system.md'
-          - Commands: 'local-dev/cli-commands.md'
-      - Linking in Local Packages: 'local-dev/linking-local-packages.md'
  - Core Features:
      - Software Catalog:
          - Overview: 'features/software-catalog/index.md'
@@ -178,6 +172,14 @@ nav:
      - Contributing New Providers: 'auth/add-auth-provider.md'
      - Service to Service Auth: 'auth/service-to-service-auth.md'
      - Troubleshooting Auth: 'auth/troubleshooting.md'
+  - Tooling:
+      - Backstage CLI:
+          - Overview: 'tooling/cli/01-overview.md'
+          - Build System: 'tooling/cli/02-build-system.md'
+          - Commands: 'tooling/cli/03-commands.md'
+      - Local Development:
+          - Linking in Local Packages: 'tooling/local-dev/linking-local-packages.md'
+          - Debugging Backstage: 'tooling/local-dev/debugging.md'
  - Deployment:
      - Deploying Backstage: 'deployment/index.md'
      - Scaling: 'deployment/scaling.md'
@@ -31,7 +31,7 @@ The backend starts up on port 7007 per default.

 ### Debugging

-The backend is a node process that can be inspected to allow breakpoints and live debugging. To enable this, pass the `--inspect` flag to [backend:dev](https://backstage.io/docs/local-dev/cli-build-system#backend-development).
+The backend is a node process that can be inspected to allow breakpoints and live debugging. To enable this, pass the `--inspect` flag to [backend:dev](https://backstage.io/docs/tooling/cli/build-system#backend-development).

 To debug the backend in [Visual Studio Code](https://code.visualstudio.com/):

@@ -15,7 +15,7 @@
 */

 /**
- * Backstage package role, see {@link https://backstage.io/docs/local-dev/cli-build-system#package-roles | docs}.
+ * Backstage package role, see {@link https://backstage.io/docs/tooling/cli/build-system#package-roles | docs}.
 *
 * @public
 */