diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 452e90add5..831e8af145 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -38,6 +38,34 @@ app-folder is the name that was provided when prompted. Inside that directory, it will generate all the files and folder structure needed for you to run your app. +### Troubleshooting + +The create app command doesn't always work as expected, this is a collection of +some of the commonly encountered issues and solutions. + +#### Couldn't find any versions for "file-saver" + +You may encounter the following error message: + +```text +Couldn't find any versions for "file-saver" that matches "eligrey-FileSaver.js-1.3.8.tar.gz-art-external" +``` + +This is likely because you have a globally configured NPM proxy, which breaks +the installation of the `material-table` dependency. This is a known issue and +being worked on in `material-table`, but for now you can work around it using +the following: + +```bash +NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx @backstage/create-app +``` + +#### Can't find Python executable "python" + +The install process may also fail if no Python installation is available. Python +is commonly available in most systems already, but if it isn't you can head for +example [here](https://www.python.org/downloads/) to install it. + ### General folder structure Below is a simplified layout of the files and folders generated when creating an diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index a9ac770f90..4ca2f431a7 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -24,9 +24,11 @@ Requests towards this repo. Backstage provides the `@backstage/create-app` package to scaffold standalone instances of Backstage. You will need to have [NodeJS](https://nodejs.org/en/download/) Active LTS Release installed -(currently v12), and [yarn](https://classic.yarnpkg.com/en/docs/install). You -will also need to have [Docker](https://docs.docker.com/engine/install/) -installed to use some features like Software Templates and TechDocs. +(currently v12), [yarn](https://classic.yarnpkg.com/en/docs/install) and +[Python](https://www.python.org/downloads/) (although you likely have it +already). You will also need to have +[Docker](https://docs.docker.com/engine/install/) installed to use some features +like Software Templates and TechDocs. Using `npx` you can then run the following to create an app in a chosen subdirectory of your current working directory: diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md index 44de2a1310..7403f2c2dd 100644 --- a/docs/tutorials/quickstart-app-auth.md +++ b/docs/tutorials/quickstart-app-auth.md @@ -11,10 +11,11 @@ title: Monorepo App Setup With Authentication > own environment. It starts with a skeleton install and verifying of the > monorepo's functionality. Next, GitHub authentication is added and tested. > -> This document assumes you have NodeJS 12 active along with Yarn. Please note, -> that at the time of this writing, the current version is 0.1.1-alpha.21. This -> guide can still be used with future versions, just, verify as you go. If you -> run into issues, you can compare your setup with mine here > +> This document assumes you have NodeJS 12 active along with Yarn and Python. +> Please note, that at the time of this writing, the current version is +> 0.1.1-alpha.21. This guide can still be used with future versions, just, +> verify as you go. If you run into issues, you can compare your setup with mine +> here > > [simple-backstage-app](https://github.com/johnson-jesse/simple-backstage-app). # The Skeleton Application diff --git a/docs/tutorials/quickstart-app-plugin.md b/docs/tutorials/quickstart-app-plugin.md index 020c43a294..9f571b0c9a 100644 --- a/docs/tutorials/quickstart-app-plugin.md +++ b/docs/tutorials/quickstart-app-plugin.md @@ -20,10 +20,11 @@ title: Adding Custom Plugin to Existing Monorepo App > functionality, extend the Sidebar to make our life easy. Finally, we add > custom code to display GitHub repository information. > -> This document assumes you have NodeJS 12 active along with Yarn. Please note, -> that at the time of this writing, the current version is 0.1.1-alpha.21. This -> guide can still be used with future versions, just, verify as you go. If you -> run into issues, you can compare your setup with mine here > +> This document assumes you have NodeJS 12 active along with Yarn and Python. +> Please note, that at the time of this writing, the current version is +> 0.1.1-alpha.21. This guide can still be used with future versions, just, +> verify as you go. If you run into issues, you can compare your setup with mine +> here > > [simple-backstage-app-plugin](https://github.com/johnson-jesse/simple-backstage-app-plugin). # The Skeleton Plugin