Merge pull request #457 from spotify/eide/docs-create-app

Add documentation for how to create an app

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)

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)

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)
+<p align='center'>
+    <img src='https://github.com/spotify/backstage/raw/master/docs/getting-started/create-plugin_output.png' width='600' alt='create plugin'>
+</p>
 
 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)
+<p align='center'>
+    <img src='https://github.com/spotify/backstage/raw/master/docs/getting-started/my-plugin_screenshot.png' width='600' alt='my plugin'>
+</p>
 
 [Next Step - Structure of a plugin](structure-of-a-plugin.md)
 

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.
+
+<p align='center'>
+    <img src='https://github.com/spotify/backstage/raw/master/docs/getting-started/create-app_output.png' width='600' alt='create app'>
+</p>
+
+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)