From 490a905199241be9c90c32b1481572129fc454b1 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 7 Oct 2021 11:08:31 +0200 Subject: [PATCH] docs: rename CLI section to Local Development + move in linking docs Signed-off-by: Patrik Oldsberg --- docs/deployment/docker.md | 2 +- docs/getting-started/create-an-app.md | 53 ------------------ .../commands.md => local-dev/cli-commands.md} | 4 +- .../index.md => local-dev/cli-overview.md} | 6 +- docs/local-dev/linking-local-packages.md | 56 +++++++++++++++++++ docs/plugins/create-a-plugin.md | 3 +- docs/plugins/github-apps.md | 2 +- microsite/sidebars.json | 9 ++- mkdocs.yml | 8 ++- 9 files changed, 78 insertions(+), 65 deletions(-) rename docs/{cli/commands.md => local-dev/cli-commands.md} (99%) rename docs/{cli/index.md => local-dev/cli-overview.md} (97%) create mode 100644 docs/local-dev/linking-local-packages.md diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index ba32706cc4..7230f5cf16 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -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 diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index ac78685a82..e5d15d5845 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -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`. diff --git a/docs/cli/commands.md b/docs/local-dev/cli-commands.md similarity index 99% rename from docs/cli/commands.md rename to docs/local-dev/cli-commands.md index 5727833562..0397ffa09c 100644 --- a/docs/cli/commands.md +++ b/docs/local-dev/cli-commands.md @@ -1,6 +1,6 @@ --- -id: commands -title: Commands +id: cli-commands +title: CLI Commands description: Descriptions of all commands available in the CLI. --- diff --git a/docs/cli/index.md b/docs/local-dev/cli-overview.md similarity index 97% rename from docs/cli/index.md rename to docs/local-dev/cli-overview.md index 1b2e01be62..de9e378632 100644 --- a/docs/cli/index.md +++ b/docs/local-dev/cli-overview.md @@ -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 diff --git a/docs/local-dev/linking-local-packages.md b/docs/local-dev/linking-local-packages.md new file mode 100644 index 0000000000..40b722e302 --- /dev/null +++ b/docs/local-dev/linking-local-packages.md @@ -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`. diff --git a/docs/plugins/create-a-plugin.md b/docs/plugins/create-a-plugin.md index c35f4b91fa..ef415d107a 100644 --- a/docs/plugins/create-a-plugin.md +++ b/docs/plugins/create-a-plugin.md @@ -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 diff --git a/docs/plugins/github-apps.md b/docs/plugins/github-apps.md index f9f7590e09..ef0b21d902 100644 --- a/docs/plugins/github-apps.md +++ b/docs/plugins/github-apps.md @@ -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 diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 9cf3b204c2..bc9f827edc 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -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", diff --git a/mkdocs.yml b/mkdocs.yml index 366411c7c4..b668ffdb15 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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'