complete instructions on setting up custom homepage
Signed-off-by: Himanshu Mishra <himanshu@orkohunter.net>
This commit is contained in:
Himanshu Mishra
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
@@ -253,72 +253,3 @@ const LogoFull = () => {
|
||||
return <img src={MyCustomLogoFull} />;
|
||||
};
|
||||
```
|
||||
|
||||
## Custom Homepage
|
||||
|
||||
In addition to a custom theme, a custom logo, you can also customize the
|
||||
homepage of your app. To do that we need to go through a few steps.
|
||||
|
||||
### Setting up the Home Page
|
||||
|
||||
1. Create a Home Page Component that will be used for composition.
|
||||
|
||||
`packages/app/src/components/home/HomePage.tsx`
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
|
||||
export const HomePage = () => {
|
||||
return {
|
||||
/* TODO: Compose a Home Page here */
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
2. Add a route where the homepage will live, presumably `/`.
|
||||
|
||||
`packages/app/src/App.tsx`
|
||||
|
||||
```tsx
|
||||
import { HomepageCompositionRoot } from '@backstage/plugin-home';
|
||||
import { HomePage } from './components/home/HomePage';
|
||||
|
||||
// ...
|
||||
<Route path="/" element={<HomepageCompositionRoot />}>
|
||||
<HomePage />
|
||||
</Route>;
|
||||
// ...
|
||||
```
|
||||
|
||||
### Composing your Home Page
|
||||
|
||||
Composing a Home Page is no different from creating a regular React Component,
|
||||
i.e. the App Integrator is free to include whatever content they like. However,
|
||||
there are components developed with the Home Page in mind. If you are looking
|
||||
for components to use when composing your homepage, you can take a look at the
|
||||
[collection of Homepage components](https://backstage.io/?path=/story/plugins-home-components)
|
||||
in storybook. If you don't find a component that suits your needs but want to
|
||||
contribute, check the
|
||||
[Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing).
|
||||
|
||||
> If you want to use one of the available homepage templates you can find the
|
||||
> [templates](https://backstage.io/storybook/?path=/story/plugins-home-templates)
|
||||
> in the storybook under the "Home" plugin. And if you would like to contribute
|
||||
> a template, please see the
|
||||
> [Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing)
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import Grid from '@material-ui/core/Grid';
|
||||
import { HomePageCompanyLogo } from '@backstage/plugin-home';
|
||||
|
||||
export const HomePage = () => {
|
||||
return (
|
||||
<Grid container spacing={3}>
|
||||
<Grid item xs={12} md={4}>
|
||||
<HomePageCompanyLogo className={container} />
|
||||
</Grid>
|
||||
</Grid>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
id: homepage
|
||||
title: Backstage Home Page - Setup and Customization
|
||||
description: Documentation on setting up and customizing Backstage homepage
|
||||
---
|
||||
|
||||
## Home Page
|
||||
|
||||
Having a good Backstage home page can significantly improve the discoverability of the platform. You want your users to find all the things they need right from the home page and never have to remember direct URLs in Backstage. The [Home plugin](https://github.com/backstage/backstage/tree/master/plugins/home) introduces a system for composing a home page for Backstage in order to surface relevant info and provide convenient shortcuts for common tasks. It's designed with composability in mind with an open ecosystem that allows anyone to contribute with any component, to be included in any home page.
|
||||
|
||||
For App Integrators, the system is designed to be composable to give total freedom in designing a Home Page that suits the needs of the organization. From the perspective of a Component Developer who wishes to contribute with building blocks to be included in Home Pages, there's a convenient interface for bundling the different parts and exporting them with both error boundary and lazy loading handled under the surface.
|
||||
|
||||
Let's get started by installing the home plugin and creating a simple home page for your Backstage app.
|
||||
|
||||
### Setup home page
|
||||
|
||||
#### 1. Install the plugin
|
||||
|
||||
```
|
||||
# From the Backstage repository root
|
||||
cd packages/app
|
||||
yarn add @backstage/plugin-home
|
||||
```
|
||||
|
||||
#### 2. Create a new HomePage component
|
||||
|
||||
Inside your `packages/app`, create a new file where our new Home Page component is going to live. Create `packages/app/src/components/home/HomePage.tsx` with the following initial code
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
|
||||
export const HomePage = () => {
|
||||
/* We will shortly compose a pretty Home Page here. */
|
||||
return <h1>Welcome to Backstage!</h1>;
|
||||
};
|
||||
```
|
||||
|
||||
#### 3. Update router for the root `/` route
|
||||
|
||||
If you don't have a home page already, most likely you have a redirect setup to use the Catalog home page as a home page.
|
||||
|
||||
Inside your `packages/app/src/App.tsx`, look for
|
||||
|
||||
```tsx
|
||||
const routes = (
|
||||
<FlatRoutes>
|
||||
<Navigate key="/" to="catalog" />
|
||||
```
|
||||
|
||||
Let's replace the `<Navigate>` line and use the new component we created in the previous step as the new home page.
|
||||
|
||||
```diff
|
||||
// File: packages/app/src/App.tsx
|
||||
|
||||
+ import { HomepageCompositionRoot } from '@backstage/plugin-home';
|
||||
+ import { HomePage } from './components/home/HomePage';
|
||||
|
||||
// ...
|
||||
const routes = (
|
||||
<FlatRoutes>
|
||||
- <Navigate key="/" to="catalog" />
|
||||
+ <Route path="/" element={<HomepageCompositionRoot />}>
|
||||
+ <HomePage />
|
||||
+ </Route>
|
||||
// ...
|
||||
|
||||
)
|
||||
```
|
||||
|
||||
### 4. Update sidebar items
|
||||
|
||||
Let's update the route for "Home" in the Backstage sidebar to point to the new home page. We'll also add a Sidebar item to quickly open Catalog.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th><img data-zoomable src="../assets/getting-started/sidebar-without-catalog.png" alt="Sidebar without Catalog" /></td>
|
||||
<th><img data-zoomable src="../assets/getting-started/sidebar-with-catalog.png" alt="Sidebar with Catalog" /></td>
|
||||
</tr>
|
||||
<tr align="center">
|
||||
<td>Before</td>
|
||||
<td>After</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
The code for the Backstage sidebar is most likely inside your [`packages/app/src/components/Root/Root.tsx`](https://github.com/backstage/backstage/blob/master/packages/app/src/components/Root/Root.tsx).
|
||||
|
||||
Let's make the following changes
|
||||
|
||||
```diff
|
||||
// Other imports
|
||||
+ import CategoryIcon from '@material-ui/icons/Category';
|
||||
|
||||
export const Root = ({ children }: PropsWithChildren<{}>) => (
|
||||
<SidebarPage>
|
||||
<Sidebar>
|
||||
<SidebarLogo />
|
||||
# ...
|
||||
<SidebarGroup label="Menu" icon={<MenuIcon />}>
|
||||
{/* Global nav, not org-specific */}
|
||||
- <SidebarItem icon={HomeIcon} to="catalog" text="Home" />
|
||||
+ <SidebarItem icon={HomeIcon} to="/" text="Home" />
|
||||
+ <SidebarItem icon={CategoryIcon} to="catalog" text="Catalog" />
|
||||
<SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
|
||||
<SidebarItem icon={LibraryBooks} to="docs" text="Docs" />
|
||||
<SidebarItem icon={LayersIcon} to="explore" text="Explore" />
|
||||
<SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />
|
||||
{/* End global nav */}
|
||||
<SidebarDivider />
|
||||
```
|
||||
|
||||
That's it! You should now have _(although slightly boring)_ a home page!
|
||||
|
||||
<img data-zoomable src="../assets/getting-started/simple-homepage.png" alt="Screenshot of a blank homepage" />
|
||||
|
||||
In the next steps, we will make it interesting and useful! There is a default home page template ([storybook link](https://backstage.io/storybook/?path=/story/plugins-home-templates--default-template)) which we will use to set up our home page.
|
||||
|
||||
#### 2. Use the default template
|
||||
|
||||
### Composing your Home Page
|
||||
|
||||
Composing a Home Page is no different from creating a regular React Component,
|
||||
i.e. the App Integrator is free to include whatever content they like. However,
|
||||
there are components developed with the Home Page in mind. If you are looking
|
||||
for components to use when composing your homepage, you can take a look at the
|
||||
[collection of Homepage components](https://backstage.io/?path=/story/plugins-home-components)
|
||||
in storybook. If you don't find a component that suits your needs but want to
|
||||
contribute, check the
|
||||
[Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing).
|
||||
|
||||
> If you want to use one of the available homepage templates you can find the
|
||||
> [templates](https://backstage.io/storybook/?path=/story/plugins-home-templates)
|
||||
> in the storybook under the "Home" plugin. And if you would like to contribute
|
||||
> a template, please see the
|
||||
> [Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing)
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import Grid from '@material-ui/core/Grid';
|
||||
import { HomePageCompanyLogo } from '@backstage/plugin-home';
|
||||
|
||||
export const HomePage = () => {
|
||||
return (
|
||||
<Grid container spacing={3}>
|
||||
<Grid item xs={12} md={4}>
|
||||
<HomePageCompanyLogo className={container} />
|
||||
</Grid>
|
||||
</Grid>
|
||||
);
|
||||
};
|
||||
```
|
||||
@@ -33,7 +33,7 @@ _Example of the default homepage template in Backstage Storybook_
|
||||
|
||||
## How to get started
|
||||
|
||||
To get started, you first need to set up your homepage plugin in the app if you have not already, then you can move on to composing your homepage. You can find our step-by-step documentation of how to do this under the [App Configuration - Customize the look-and-feel of your App documentation](https://backstage.io/docs/getting-started/app-custom-theme#custom-homepage). You can also access the [Backstage UI Kit in Figma](https://www.figma.com/file/nUaAw56hTgC0RIOYkuLSrB/Backstage-Design-System?node-id=2185%3A2978) to duplicate your own version and play around with a fitting homepage for your own organization.
|
||||
To get started, you first need to set up your homepage plugin in the app if you have not already, then you can move on to composing your homepage. You can find our step-by-step documentation of how to do this under the [App Configuration - Customize the look-and-feel of your App documentation](https://backstage.io/docs/getting-started/homepage). You can also access the [Backstage UI Kit in Figma](https://www.figma.com/file/nUaAw56hTgC0RIOYkuLSrB/Backstage-Design-System?node-id=2185%3A2978) to duplicate your own version and play around with a fitting homepage for your own organization.
|
||||
|
||||
|
||||
_Example of the homepage components in the Backstage UI Kit in Figma_
|
||||
|
||||
@@ -22,7 +22,8 @@
|
||||
"label": "App configuration",
|
||||
"ids": [
|
||||
"getting-started/configure-app-with-plugins",
|
||||
"getting-started/app-custom-theme"
|
||||
"getting-started/app-custom-theme",
|
||||
"getting-started/homepage"
|
||||
]
|
||||
},
|
||||
"getting-started/keeping-backstage-updated",
|
||||
|
||||
Reference in New Issue
Block a user