diff --git a/README.md b/README.md index 2145e62fa8..990389181f 100644 --- a/README.md +++ b/README.md @@ -75,8 +75,7 @@ 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) +- [Getting Started](docs/getting-started/README.md) - [Frontend architecture](docs/architecture-terminology.md) - [API references](docs/reference/README.md) - 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..b0b042ed86 100644 --- a/docs/getting-started/create-a-plugin.md +++ b/docs/getting-started/create-a-plugin.md @@ -1,4 +1,8 @@ -# Create a plugin +# Backstage Plugins + +A Backstage Plugin adds functionality to Backstage. + +## Create a plugin 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`). @@ -6,7 +10,9 @@ To create a new plugin, make sure you've run `yarn` and installed dependencies, 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..1d46e81026 --- /dev/null +++ b/docs/getting-started/create-an-app.md @@ -0,0 +1,81 @@ +# Backstage App + +If you want to get setup 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 + +If you have [`npx`](https://github.com/npm/npx) installed simply run: + +```bash +npx @backstage/cli create-app +``` + +Or with `yarn`: + +```bash +yarn add --dev @backstage/cli +yarn run 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