Merge pull request #7491 from backstage/rugvip/tooling
docs: rename CLI section to Tooling + move in package linking docs
This commit is contained in:
Patrik Oldsberg
@@ -76,7 +76,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](../cli/commands.md#backendbundle).
|
||||
[`backend:bundle` command docs](../local-dev/cli-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
|
||||
|
||||
@@ -132,56 +132,3 @@ Now you're free to hack away on your own Backstage installation!
|
||||
As you get more experienced with the app, in future you can run just the
|
||||
frontend with `yarn start` in one window, and the backend with
|
||||
`yarn start-backend` in a different window.
|
||||
|
||||
## Linking in local Backstage packages
|
||||
|
||||
It can often be useful to try out changes to the packages in the main Backstage
|
||||
repo within your own app. For example if you want to make modifications to
|
||||
`@backstage/core-plugin-api` and try them out in your app.
|
||||
|
||||
To link in external packages, add them to your `package.json` and `lerna.json`
|
||||
workspace paths. These can be either relative or absolute paths with or without
|
||||
globs. For example:
|
||||
|
||||
```json
|
||||
"packages": [
|
||||
"packages/*",
|
||||
"plugins/*",
|
||||
"../backstage/packages/core-plugin-api", // New path added to work on @backstage/core-plugin-api
|
||||
],
|
||||
```
|
||||
|
||||
Then reinstall packages to make yarn set up symlinks:
|
||||
|
||||
```bash
|
||||
yarn install
|
||||
```
|
||||
|
||||
With this in place you can now modify the `@backstage/core-plugin-api` package
|
||||
within the main repo, and have those changes be reflected and tested in your
|
||||
app. Simply run your app using `yarn dev` (or `yarn start` for just frontend) as
|
||||
normal.
|
||||
|
||||
Note that for backend packages you need to make sure that linked packages are
|
||||
not dependencies of any non-linked package. If you for example want to work on
|
||||
`@backstage/backend-common`, you need to also link in other backend plugins and
|
||||
packages that depend on `@backstage/backend-common`, or temporarily disable
|
||||
those plugins in your backend. This is because the transformation of backend
|
||||
module tree stops whenever a non-local package is encountered, and from that
|
||||
point node will `require` packages directly for that entire module subtree.
|
||||
|
||||
Type checking can also have issues when linking in external packages, since the
|
||||
linked in packages will use the types in the external project and dependency
|
||||
version mismatches between the two projects may cause errors. To fix any of
|
||||
those errors you need to sync versions of the dependencies in the two projects.
|
||||
A simple way to do this can be to copy over `yarn.lock` from the external
|
||||
project and run `yarn install`, although this is quite intrusive and can cause
|
||||
other issues in existing projects, so use this method with care. It can often be
|
||||
best to simply ignore the type errors, as app serving will work just fine
|
||||
anyway.
|
||||
|
||||
Another issue with type checking is that the incremental type cache doesn't
|
||||
invalidate correctly for the linked in packages, causing type checking to not
|
||||
reflect changes made to types. You can work around this by either setting
|
||||
`compilerOptions.incremental = false` in `tsconfig.json`, or by deleting the
|
||||
types cache folder `dist-types` before running `yarn tsc`.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
id: commands
|
||||
title: Commands
|
||||
id: cli-commands
|
||||
title: CLI Commands
|
||||
description: Descriptions of all commands available in the CLI.
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
id: index
|
||||
title: Overview
|
||||
id: cli-overview
|
||||
title: CLI Overview
|
||||
description: Overview of the Backstage CLI
|
||||
---
|
||||
|
||||
@@ -20,7 +20,7 @@ Under the hood the CLI uses [Webpack](https://webpack.js.org/) for bundling,
|
||||
linting. It also includes custom tooling for working within Backstage apps, for
|
||||
example for keeping the app up to date and verifying static configuration.
|
||||
|
||||
For a full list of CLI commands, see the [commands](./commands.md) page.
|
||||
For a full list of CLI commands, see the [commands](./cli-commands.md) page.
|
||||
|
||||
## Introduction
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
id: linking-local-packages
|
||||
title: Linking in Local Packages
|
||||
description: How to link in other local packages into your Backstage monorepo
|
||||
---
|
||||
|
||||
It can often be useful to try out changes to the packages in the main Backstage
|
||||
repo within your own app. For example if you want to make modifications to
|
||||
`@backstage/core-plugin-api` and try them out in your app.
|
||||
|
||||
To link in external packages, add them to your `package.json` and `lerna.json`
|
||||
workspace paths. These can be either relative or absolute paths with or without
|
||||
globs. For example:
|
||||
|
||||
```json
|
||||
"packages": [
|
||||
"packages/*",
|
||||
"plugins/*",
|
||||
"../backstage/packages/core-plugin-api", // New path added to work on @backstage/core-plugin-api
|
||||
],
|
||||
```
|
||||
|
||||
Then reinstall packages to make yarn set up symlinks:
|
||||
|
||||
```bash
|
||||
yarn install
|
||||
```
|
||||
|
||||
With this in place you can now modify the `@backstage/core-plugin-api` package
|
||||
within the main repo, and have those changes be reflected and tested in your
|
||||
app. Simply run your app using `yarn dev` (or `yarn start` for just frontend) as
|
||||
normal.
|
||||
|
||||
Note that for backend packages you need to make sure that linked packages are
|
||||
not dependencies of any non-linked package. If you for example want to work on
|
||||
`@backstage/backend-common`, you need to also link in other backend plugins and
|
||||
packages that depend on `@backstage/backend-common`, or temporarily disable
|
||||
those plugins in your backend. This is because the transformation of backend
|
||||
module tree stops whenever a non-local package is encountered, and from that
|
||||
point node will `require` packages directly for that entire module subtree.
|
||||
|
||||
Type checking can also have issues when linking in external packages, since the
|
||||
linked in packages will use the types in the external project and dependency
|
||||
version mismatches between the two projects may cause errors. To fix any of
|
||||
those errors you need to sync versions of the dependencies in the two projects.
|
||||
A simple way to do this can be to copy over `yarn.lock` from the external
|
||||
project and run `yarn install`, although this is quite intrusive and can cause
|
||||
other issues in existing projects, so use this method with care. It can often be
|
||||
best to simply ignore the type errors, as app serving will work just fine
|
||||
anyway.
|
||||
|
||||
Another issue with type checking is that the incremental type cache doesn't
|
||||
invalidate correctly for the linked in packages, causing type checking to not
|
||||
reflect changes made to types. You can work around this by either setting
|
||||
`compilerOptions.incremental = false` in `tsconfig.json`, or by deleting the
|
||||
types cache folder `dist-types` before running `yarn tsc`.
|
||||
@@ -10,7 +10,8 @@ A Backstage Plugin adds functionality to Backstage.
|
||||
|
||||
To create a new 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 create-plugin`](../cli/commands.md#create-plugin))
|
||||
invoking the
|
||||
[`backstage-cli create-plugin`](../local-dev/cli-commands.md#create-plugin))
|
||||
from the root of your project.
|
||||
|
||||
```bash
|
||||
|
||||
@@ -36,7 +36,7 @@ that we provide. This gives us a way to automate some of the work required to
|
||||
create a GitHub app.
|
||||
|
||||
You can read more about the
|
||||
[`backstage-cli create-github-app` method](../cli/commands.md#create-github-app).
|
||||
[`backstage-cli create-github-app` method](../local-dev/cli-commands.md#create-github-app).
|
||||
|
||||
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
|
||||
|
||||
@@ -29,7 +29,14 @@
|
||||
"getting-started/contributors",
|
||||
"getting-started/project-structure"
|
||||
],
|
||||
"CLI": ["cli/index", "cli/commands"],
|
||||
"Local Development": [
|
||||
{
|
||||
"type": "subcategory",
|
||||
"label": "CLI",
|
||||
"ids": ["local-dev/cli-overview", "local-dev/cli-commands"]
|
||||
},
|
||||
"local-dev/linking-local-packages"
|
||||
],
|
||||
"Core Features": [
|
||||
{
|
||||
"type": "subcategory",
|
||||
|
||||
+5
-3
@@ -27,9 +27,11 @@ nav:
|
||||
- Key Concepts: 'getting-started/concepts.md'
|
||||
- Contributors: 'getting-started/contributors.md'
|
||||
- Project Structure: 'getting-started/project-structure.md'
|
||||
- CLI:
|
||||
- Overview: 'cli/index.md'
|
||||
- Commands: 'cli/commands.md'
|
||||
- Local Development:
|
||||
- CLI:
|
||||
- Overview: 'local-dev/cli-overview.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'
|
||||
|
||||
Reference in New Issue
Block a user