diff --git a/README.md b/README.md index 1733bfbe95..2750d54e3c 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Our vision for Backstage is for it to become the trusted standard toolbox (read: The Backstage platform consists of a number of different components: -- **frontend** - Main web application that users interact with. It's built up by a number of different _Plugins_. +- **app** - Main web application that users interact with. It's built up by a number of different _Plugins_. This repo contains an example implementation of an app (located in `packages/example-app`) and you can easily get started with your own app by [creating one](docs/getting-started/create-an-app.md). - **plugins** - Each plugin is treated as a self-contained web app and can include almost any type of content. Plugins all use a common set of platform API's and reusable UI components. Plugins can fetch data either from the _backend_ or through any RESTful API exposed through the _proxy_. - **backend** \* - GraphQL aggregation service that holds the model of your software ecosystem, including organisational information and what team owns what software. The backend also has a Plugin model for extending its graph. - **proxy** \* - Terminates HTTPS and exposes any RESTful API to Plugins. @@ -53,7 +53,7 @@ _\* not yet released_ ## Getting started -To run the Backstage frontend, you will need to have the following installed: +To run a Backstage app, you will need to have the following installed: - [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12 @@ -75,9 +75,8 @@ For more complex development environment configuration, see the ## Documentation - [FAQs](docs/FAQ.md) -- [Create a Plugin](docs/getting-started/create-a-plugin.md) -- [Structure of a Plugin](docs/getting-started/structure-of-a-plugin.md) -- [Frontend architecture](docs/architecture-terminology.md) +- [Getting Started](docs/getting-started/README.md) +- [Architecture](docs/architecture-terminology.md) - [API references](docs/reference/README.md) - [Storybook - UI components](http://storybook.backstage.io) ([WIP](https://github.com/spotify/backstage/milestone/9)) - Using Backstage components (TODO) diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index 719e946a7e..163e52b950 100644 --- a/docs/getting-started/README.md +++ b/docs/getting-started/README.md @@ -3,6 +3,7 @@ Here is a collection of tutorials that will guide you through setting up and extending an instance of Backstage with your own plugins. - [Development Environment](development-environment.md) +- [Create a Backstage App](create-an-app.md) - [Create a Backstage plugin](create-a-plugin.md) - [Structure of a plugin](structure-of-a-plugin.md) - Using Backstage components (TODO) diff --git a/docs/getting-started/create-a-plugin.md b/docs/getting-started/create-a-plugin.md index be3be26abb..7b8a7cf29b 100644 --- a/docs/getting-started/create-a-plugin.md +++ b/docs/getting-started/create-a-plugin.md @@ -1,12 +1,18 @@ -# Create a plugin +# Backstage Plugins -To create a new plugin, make sure you've run `yarn` and installed dependencies, then run the following on your command line (invoking the `backstage-cli`). +A Backstage Plugin adds functionality to Backstage. + +## Create a plugin + +To create a new plugin, make sure you've run `yarn install` and installed dependencies, then run the following on your command line (invoking the `backstage-cli`). ```bash yarn create-plugin ``` -![](create-plugin_output.png) +

+ create plugin +

This will create a new Backstage Plugin based on the ID that was provided. It will be built and added to the Backstage App automatically. @@ -14,7 +20,9 @@ added to the Backstage App automatically. _If `yarn start` is already running you should be able to see the default page for your new plugin directly by navigating to `http://localhost:3000/my-plugin`._ -![](my-plugin_screenshot.png) +

+ my plugin +

[Next Step - Structure of a plugin](structure-of-a-plugin.md) diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md new file mode 100644 index 0000000000..703d1d59a5 --- /dev/null +++ b/docs/getting-started/create-an-app.md @@ -0,0 +1,76 @@ +# Backstage App + +To get set up quickly with your own Backstage project you can create a Backstage App. + +A Backstage App is a monorepo setup with `lerna` that includes everything you need to run Backstage in your own environment. + +## Create an app + +To create a Backstage app, you will need to have [NodeJS](https://nodejs.org/en/download/) Active LTS Release installed (currently v12). + +With `npx`: + +```bash +npx @backstage/cli create-app +``` + +This will create a new Backstage App inside the current folder. The name of the app-folder is the name that was provided when prompted. + +

+ create app +

+ +Inside that directory, it will generate all the files and folder structure needed for you to run your app. + +### Folder structure + +``` +app +├── README.md +├── lerna.json +├── package.json +├── prettier.config.js +├── tsconfig.json +├── packages +│ └── app +│ ├── package.json +│ ├── tsconfig.json +│ ├── public +│ │ └── ... +│ └── src +│ ├── App.test.tsx +│ ├── App.tsx +│ ├── index.tsx +│ ├── plugins.ts +│ └── setupTests.ts +└── plugins + └── welcome + ├── README.md + ├── package.json + ├── tsconfig.json + └── src + ├── index.ts + ├── plugin.test.ts + ├── plugin.ts + ├── setupTests.ts + └── components + ├── Timer + │ └── ... + └── WelcomePage + └── ... +``` + +## Run the app + +When the installation is complete you can open the app folder and start the app. + +```bash +cd my-backstage-app +yarn start +``` + +_When `yarn start` is ready it should open up a browser window displaying your app, if not you can navigate to `http://localhost:3000`._ + +[Next Step - Create a Backstage plugin](create-a-plugin.md) + +[Back to Docs](README.md) diff --git a/docs/getting-started/create-app_output.png b/docs/getting-started/create-app_output.png new file mode 100644 index 0000000000..52dcc13097 Binary files /dev/null and b/docs/getting-started/create-app_output.png differ