diff --git a/.changeset/beige-eagles-cheat.md b/.changeset/beige-eagles-cheat.md new file mode 100644 index 0000000000..5b5081d2ee --- /dev/null +++ b/.changeset/beige-eagles-cheat.md @@ -0,0 +1,5 @@ +--- +'@backstage/cli-node': patch +--- + +Updated doc link. diff --git a/docs/backend-system/architecture/04-plugins.md b/docs/backend-system/architecture/04-plugins.md index 195c32b049..af59c2a48a 100644 --- a/docs/backend-system/architecture/04-plugins.md +++ b/docs/backend-system/architecture/04-plugins.md @@ -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. diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index f16a2ad13e..154f68c7d1 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -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 diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index e7324f4603..1de8874d56 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -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: diff --git a/docs/integrations/github/github-apps.md b/docs/integrations/github/github-apps.md index 6e3d028e6d..b5e252be74 100644 --- a/docs/integrations/github/github-apps.md +++ b/docs/integrations/github/github-apps.md @@ -42,7 +42,7 @@ yarn backstage-cli create-github-app ``` 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 diff --git a/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md b/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md index 8541d64465..aacd60af8c 100644 --- a/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md +++ b/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md @@ -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. ::: diff --git a/docs/plugins/create-a-plugin.md b/docs/plugins/create-a-plugin.md index 481b610e4e..d80e9cd57e 100644 --- a/docs/plugins/create-a-plugin.md +++ b/docs/plugins/create-a-plugin.md @@ -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 diff --git a/docs/plugins/testing.md b/docs/plugins/testing.md index bc212a2581..a97b3d8166 100644 --- a/docs/plugins/testing.md +++ b/docs/plugins/testing.md @@ -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) diff --git a/docs/references/glossary.md b/docs/references/glossary.md index 6db16443e2..906260e710 100644 --- a/docs/references/glossary.md +++ b/docs/references/glossary.md @@ -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) diff --git a/docs/releases/v1.20.0.md b/docs/releases/v1.20.0.md index 921b8219fb..0d0075aa41 100644 --- a/docs/releases/v1.20.0.md +++ b/docs/releases/v1.20.0.md @@ -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 ⚡ diff --git a/docs/local-dev/cli-overview.md b/docs/tooling/cli/01-overview.md similarity index 82% rename from docs/local-dev/cli-overview.md rename to docs/tooling/cli/01-overview.md index 4ab8bb21ac..78c4b2755f 100644 --- a/docs/local-dev/cli-overview.md +++ b/docs/tooling/cli/01-overview.md @@ -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 diff --git a/docs/local-dev/cli-build-system.md b/docs/tooling/cli/02-build-system.md similarity index 99% rename from docs/local-dev/cli-build-system.md rename to docs/tooling/cli/02-build-system.md index ddcfa44cf5..bfdb21f45f 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -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. diff --git a/docs/local-dev/cli-commands.md b/docs/tooling/cli/03-commands.md similarity index 95% rename from docs/local-dev/cli-commands.md rename to docs/tooling/cli/03-commands.md index 173d616e61..234d0d04b7 100644 --- a/docs/local-dev/cli-commands.md +++ b/docs/tooling/cli/03-commands.md @@ -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] ## 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. diff --git a/docs/local-dev/debugging.md b/docs/tooling/local-dev/debugging.md similarity index 100% rename from docs/local-dev/debugging.md rename to docs/tooling/local-dev/debugging.md diff --git a/docs/local-dev/linking-local-packages.md b/docs/tooling/local-dev/linking-local-packages.md similarity index 100% rename from docs/local-dev/linking-local-packages.md rename to docs/tooling/local-dev/linking-local-packages.md diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index db84defd91..dcd8a66ee6 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -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: diff --git a/microsite/sidebars.json b/microsite/sidebars.json index a3d9f4dbec..5ddd2f97f1 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -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", diff --git a/mkdocs.yml b/mkdocs.yml index 66ce7d8def..026e76d531 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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' diff --git a/packages/backend-legacy/README.md b/packages/backend-legacy/README.md index 20e68dc746..0de555fe70 100644 --- a/packages/backend-legacy/README.md +++ b/packages/backend-legacy/README.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/): diff --git a/packages/cli-node/src/roles/types.ts b/packages/cli-node/src/roles/types.ts index a913ff29b6..d6eff04541 100644 --- a/packages/cli-node/src/roles/types.ts +++ b/packages/cli-node/src/roles/types.ts @@ -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 */