docs: remove references to @backstage/core
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
@@ -99,7 +99,7 @@ async function main() {
|
||||
```typescript
|
||||
// packages/app/src/App.tsx from a create-app deployment
|
||||
|
||||
import { discoveryApiRef, useApi } from '@backstage/core';
|
||||
import { discoveryApiRef, useApi } from '@backstage/core-plugin-api';
|
||||
|
||||
// ...
|
||||
|
||||
|
||||
@@ -51,7 +51,7 @@ The Backstage App needs a SignInPage when authentication is required.
|
||||
When using ALB authentication Backstage will only be loaded once the user has successfully authenticated; we won't need to display a SignIn page, however we will need to create a dummy SignIn component that can refresh the token.
|
||||
|
||||
- edit `packages/app/src/App.tsx`
|
||||
- import the following two additional definitions from `@backstage/core`: `useApi`, `configApiRef`; these will be used to check whether Backstage is running locally or behind an ALB
|
||||
- import the following two additional definitions from `@backstage/core-plugin-api`: `useApi`, `configApiRef`; these will be used to check whether Backstage is running locally or behind an ALB
|
||||
- add the following definition just before the app is created (`const app = createApp`):
|
||||
|
||||
```ts
|
||||
|
||||
@@ -5,6 +5,7 @@ ExampleComponent.tsx reference
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { Typography, Grid } from '@material-ui/core';
|
||||
import { identityApiRef, useApi } from '@backstage/core-plugin-api';
|
||||
import {
|
||||
InfoCard,
|
||||
Header,
|
||||
@@ -13,9 +14,7 @@ import {
|
||||
ContentHeader,
|
||||
HeaderLabel,
|
||||
SupportButton,
|
||||
identityApiRef,
|
||||
useApi,
|
||||
} from '@backstage/core';
|
||||
} from '@backstage/core-components';
|
||||
import { ExampleFetchComponent } from '../ExampleFetchComponent';
|
||||
|
||||
export const ExampleComponent = () => {
|
||||
|
||||
@@ -6,13 +6,8 @@ ExampleFetchComponent.tsx reference
|
||||
import React from 'react';
|
||||
import { useAsync } from 'react-use';
|
||||
import Alert from '@material-ui/lab/Alert';
|
||||
import {
|
||||
Table,
|
||||
TableColumn,
|
||||
Progress,
|
||||
githubAuthApiRef,
|
||||
useApi,
|
||||
} from '@backstage/core';
|
||||
import { githubAuthApiRef, useApi } from '@backstage/core-plugin-api';
|
||||
import { Table, TableColumn, Progress } from '@backstage/core-components';
|
||||
import { graphql } from '@octokit/graphql';
|
||||
|
||||
const query = `{
|
||||
|
||||
+17
-16
@@ -23,18 +23,18 @@ during their entire life cycle.
|
||||
Each Utility API is tied to an `ApiRef` instance, which is a global singleton
|
||||
object without any additional state or functionality, its only purpose is to
|
||||
reference Utility APIs. `ApiRef`s are created using `createApiRef`, which is
|
||||
exported by `@backstage/core`. There are many
|
||||
exported by `@backstage/core-plugin-api`. There are many
|
||||
[predefined Utility APIs](../reference/utility-apis/README.md) defined in
|
||||
`@backstage/core`, and they're all exported with a name of the pattern
|
||||
`*ApiRef`, for example `errorApiRef`.
|
||||
`@backstage/core-plugin-api`, and they're all exported with a name of the
|
||||
pattern `*ApiRef`, for example `errorApiRef`.
|
||||
|
||||
To access one of the Utility APIs inside a React component, use the `useApi`
|
||||
hook exported by `@backstage/core`, or the `withApis` HOC if you prefer class
|
||||
components. For example, the `ErrorApi` can be accessed like this:
|
||||
hook exported by `@backstage/core-plugin-api`, or the `withApis` HOC if you
|
||||
prefer class components. For example, the `ErrorApi` can be accessed like this:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { useApi, errorApiRef } from '@backstage/core';
|
||||
import { useApi, errorApiRef } from '@backstage/core-plugin-api';
|
||||
|
||||
export const MyComponent = () => {
|
||||
const errorApi = useApi(errorApiRef);
|
||||
@@ -52,9 +52,9 @@ Note that there is no explicit type given for `ErrorApi`. This is because the
|
||||
`errorApiRef` has the type embedded, and `useApi` is able to infer the type.
|
||||
|
||||
Also note that consuming Utility APIs is not limited to plugins, it can be done
|
||||
from any component inside Backstage, including the ones in `@backstage/core`.
|
||||
The only requirement is that they are beneath the `AppProvider` in the react
|
||||
tree.
|
||||
from any component inside Backstage, including the ones in
|
||||
`@backstage/core-plugin-api`. The only requirement is that they are beneath the
|
||||
`AppProvider` in the react tree.
|
||||
|
||||
## Supplying APIs
|
||||
|
||||
@@ -101,13 +101,13 @@ app, and the app itself.
|
||||
### Core APIs
|
||||
|
||||
Starting with the Backstage core library, it provides implementations for all of
|
||||
the core APIs. The core APIs are the ones exported by `@backstage/core`, such as
|
||||
the `errorApiRef` and `configApiRef`. You can find a full list of them
|
||||
[here](../reference/utility-apis/README.md).
|
||||
the core APIs. The core APIs are the ones exported by
|
||||
`@backstage/core-plugin-api`, such as the `errorApiRef` and `configApiRef`. You
|
||||
can find a full list of them [here](../reference/utility-apis/README.md).
|
||||
|
||||
The core APIs are loaded for any app created with `createApp` from
|
||||
`@backstage/core`, which means that there is no step that needs to be taken to
|
||||
include these APIs in an app.
|
||||
`@backstage/core-plugin-api`, which means that there is no step that needs to be
|
||||
taken to include these APIs in an app.
|
||||
|
||||
### Plugin APIs
|
||||
|
||||
@@ -213,8 +213,9 @@ implement the `ErrorApi`, as it is checked by the type embedded in the
|
||||
|
||||
Plugins are free to define their own Utility APIs. Simply define the TypeScript
|
||||
interface for the API, and create an `ApiRef` using `createApiRef` exported from
|
||||
`@backstage/core`. Also be sure to provide at least one implementation of the
|
||||
API, and to declare a default factory for the API in `createPlugin`.
|
||||
`@backstage/core-plugin-api`. Also be sure to provide at least one
|
||||
implementation of the API, and to declare a default factory for the API in
|
||||
`createPlugin`.
|
||||
|
||||
Custom Utility APIs can be either public or private, which is up to the plugin
|
||||
to choose. Private APIs do not expose an external API surface, and it's
|
||||
|
||||
@@ -6,8 +6,8 @@ description: Architecture Decision Record (ADR) log on Module Export Structure
|
||||
|
||||
## Context
|
||||
|
||||
With a growing number of exports of packages like `@backstage/core`, it is
|
||||
becoming more and more difficult to answer questions such as
|
||||
With a growing number of exports of packages like `@backstage/core-components`,
|
||||
it is becoming more and more difficult to answer questions such as
|
||||
|
||||
> Is the export in this module also exported by the package?
|
||||
|
||||
@@ -86,7 +86,7 @@ import { helperFunc } from '../../lib/UtilityX/helper';
|
||||
## Consequences
|
||||
|
||||
We will actively work to rework the export structure in our codebase,
|
||||
prioritizing the library packages such as `@backstage/core` and
|
||||
prioritizing the library packages such as `@backstage/core-components` and
|
||||
`@backstage/backend-common`.
|
||||
|
||||
If possible, we will add tools, such as lint rules, to help enforce the export
|
||||
|
||||
+2
-1
@@ -66,7 +66,8 @@ built-in providers:
|
||||
|
||||
```diff
|
||||
# packages/app/src/App.tsx
|
||||
+ import { githubAuthApiRef, SignInProviderConfig, SignInPage } from '@backstage/core';
|
||||
+ import { githubAuthApiRef } from '@backstage/core-plugin-api';
|
||||
+ import { SignInProviderConfig, SignInPage } from '@backstage/core-components';
|
||||
|
||||
+ const githubProvider: SignInProviderConfig = {
|
||||
+ id: 'github-auth-provider',
|
||||
|
||||
+2
-2
@@ -38,7 +38,7 @@ choose an account to log in with, and accept or reject the request. If the user
|
||||
accepts the login request, a token is issued, and any holder of the token can
|
||||
use it to make authenticated requests towards the third party service.
|
||||
|
||||
## OAuth in @backstage/core-api and auth-backend
|
||||
## OAuth in @backstage/core-app-api and auth-backend
|
||||
|
||||
The default OAuth implementation in Backstage is based on an OAuth server-side
|
||||
offline access flow, which means that it uses the backend as a helper in order
|
||||
@@ -60,7 +60,7 @@ The following describes the OAuth flow implemented by the
|
||||
[auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend)
|
||||
and
|
||||
[DefaultAuthConnector](https://github.com/backstage/backstage/blob/master/packages/core-app-api/src/lib/AuthConnector/DefaultAuthConnector.ts)
|
||||
in `@backstage/core-api`.
|
||||
in `@backstage/core-app-api`.
|
||||
|
||||
Component and APIs can request Access or ID Tokens from any available Auth
|
||||
provider. If there already exists a cached fresh token that covers (at least)
|
||||
|
||||
@@ -45,8 +45,8 @@ pieces in place that can be used.
|
||||
#### Identity for Plugin Developers
|
||||
|
||||
As a plugin developer, there are two main touchpoints for identities: the
|
||||
`IdentityApi` exported by `@backstage/core` via the `identityApiRef`, and a not
|
||||
yet existing middleware exported by `@backstage/backend-common`.
|
||||
`IdentityApi` exported by `@backstage/core-plugin-api` via the `identityApiRef`,
|
||||
and a not yet existing middleware exported by `@backstage/backend-common`.
|
||||
|
||||
The `IdentityApi` gives access to the signed-in user's identity in the frontend.
|
||||
It provides access to the user's ID, lightweight profile information, and an ID
|
||||
@@ -61,8 +61,9 @@ https://github.com/backstage/backstage/issues/1435.
|
||||
|
||||
If you're setting up your own Backstage app, or want to add a new identity
|
||||
provider, there are three touchpoints: the frontend auth APIs in
|
||||
`@backstage/core-api`, the backend auth providers in `auth-backend`, and the
|
||||
`SignInPage` component configured in the Backstage app via `createApp`.
|
||||
`@backstage/core-app-api` and `@backstage/core-plugin-api`, the backend auth
|
||||
providers in `auth-backend`, and the `SignInPage` component configured in the
|
||||
Backstage app via `createApp`.
|
||||
|
||||
The frontend APIs and backend providers are tightly coupled together for each
|
||||
auth provider, and together they implement an e2e auth flow. Only some auth
|
||||
@@ -81,10 +82,10 @@ The final piece of the puzzle is the `SignInPage` component that can be
|
||||
configured as part of the app. Without a sign-in page, Backstage will fall back
|
||||
to a `guest` identity for all users, without any ID token. To enable sign-in, a
|
||||
`SignInPage` needs to be configured, which in turn has to supply a user to the
|
||||
app. The `@backstage/core` package provides a basic sign-in page that allows
|
||||
both the user and the app developer to choose between a couple of different
|
||||
sign-in methods, or to designate a single provider that may also be logged in to
|
||||
automatically.
|
||||
app. The `@backstage/core-components` package provides a basic sign-in page that
|
||||
allows both the user and the app developer to choose between a couple of
|
||||
different sign-in methods, or to designate a single provider that may also be
|
||||
logged in to automatically.
|
||||
|
||||
## Further Reading
|
||||
|
||||
|
||||
@@ -554,9 +554,7 @@ Options:
|
||||
Scope: `root`
|
||||
|
||||
Validate `@backstage` dependencies within the repo, making sure that there are
|
||||
no duplicates of packages that might lead to breakages. For example,
|
||||
`@backstage/core` must not be loaded in twice, so having two different versions
|
||||
of it installed will cause this command to exit with an error.
|
||||
no duplicates of packages that might lead to breakages.
|
||||
|
||||
By supplying the `--fix` flag the command will attempt to fix any conflict that
|
||||
can be resolved by editing `yarn.lock`, but will not attempt to search for
|
||||
|
||||
@@ -112,7 +112,7 @@ example `getString`. These will throw an error if there is no value available.
|
||||
|
||||
The [ConfigApi](../reference/utility-apis/Config.md) in the frontend is a
|
||||
[UtilityApi](../api/utility-apis.md). It's accessible as usual via the
|
||||
`configApiRef` exported from `@backstage/core`.
|
||||
`configApiRef` exported from `@backstage/core-plugin-api`.
|
||||
|
||||
Depending on the config api in another API is slightly different though, as the
|
||||
`ConfigApi` implementation is supplied via the App itself and not instantiated
|
||||
@@ -123,7 +123,7 @@ for an example of how this wiring is done.
|
||||
For standalone plugin setups in `dev/index.ts`, register a factory with a
|
||||
statically mocked implementation of the config API. Use the `ConfigReader` from
|
||||
`@backstage/config` to create an instance and register it for the `configApiRef`
|
||||
from `@backstage/core`.
|
||||
from `@backstage/core-plugin-api`.
|
||||
|
||||
## Accessing ConfigApi in Backend Plugins
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ component, which are then displayed both visually and with sample code to be
|
||||
copied.
|
||||
|
||||
When custom Backstage components are created, they are placed in the
|
||||
`@backstage/core` package and added to the Storybook.
|
||||
`@backstage/core-components` package and added to the Storybook.
|
||||
|
||||
There may be times where an existing Material-UI component (in
|
||||
`@material-ui/core`) is sufficient and doesn't need to be wrapped or duplicated.
|
||||
|
||||
@@ -29,7 +29,7 @@ Backstage app with the following contents:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { Content, Header, Page } from '@backstage/core';
|
||||
import { Content, Header, Page } from '@backstage/core-components';
|
||||
import { Grid, List, Card, CardContent } from '@material-ui/core';
|
||||
import {
|
||||
SearchBar,
|
||||
|
||||
@@ -56,7 +56,7 @@ For example, adding the theme that we created in the previous section can be
|
||||
done like this:
|
||||
|
||||
```ts
|
||||
import { createApp } from '@backstage/core';
|
||||
import { createApp } from '@backstage/core-app-api';
|
||||
|
||||
const app = createApp({
|
||||
apis: ...,
|
||||
|
||||
@@ -94,7 +94,7 @@ here are some useful ones:
|
||||
```python
|
||||
yarn start # Start serving the example app, use --check to include type checks and linting
|
||||
|
||||
yarn storybook # Start local storybook, useful for working on components in @backstage/core
|
||||
yarn storybook # Start local storybook, useful for working on components in @backstage/core-components
|
||||
|
||||
yarn workspace @backstage/plugin-welcome start # Serve welcome plugin only, also supports --check
|
||||
|
||||
|
||||
@@ -137,7 +137,7 @@ frontend with `yarn start` in one window, and the backend with
|
||||
|
||||
It can often be useful to try out changes to the packages in the main Backstage
|
||||
repo within your own app. For example if you want to make modifications to
|
||||
`@backstage/core` and try them out in your app.
|
||||
`@backstage/core-plugin-api` and try them out in your app.
|
||||
|
||||
To link in external packages, add them to your `package.json` and `lerna.json`
|
||||
workspace paths. These can be either relative or absolute paths with or without
|
||||
@@ -157,9 +157,10 @@ Then reinstall packages to make yarn set up symlinks:
|
||||
yarn install
|
||||
```
|
||||
|
||||
With this in place you can now modify the `@backstage/core` package within the
|
||||
main repo, and have those changes be reflected and tested in your app. Simply
|
||||
run your app using `yarn dev` (or `yarn start` for just frontend) as normal.
|
||||
With this in place you can now modify the `@backstage/core-plugin-api` package
|
||||
within the main repo, and have those changes be reflected and tested in your
|
||||
app. Simply run your app using `yarn dev` (or `yarn start` for just frontend) as
|
||||
normal.
|
||||
|
||||
Note that for backend packages you need to make sure that linked packages are
|
||||
not dependencies of any non-linked package. If you for example want to work on
|
||||
|
||||
@@ -184,8 +184,9 @@ Stability: `2`
|
||||
### `test-utils-core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/test-utils-core/)
|
||||
|
||||
Internal testing utilities that are separated out for usage in
|
||||
@backstage/core-api. All exports are re-exported by @backstage/test-utils. This
|
||||
package should not be depended on directly.
|
||||
@backstage/core-app-api and @backstage/core-plugin-api. All exports are
|
||||
re-exported by @backstage/test-utils. This package should not be depended on
|
||||
directly.
|
||||
|
||||
Stability: See @backstage/test-utils
|
||||
|
||||
@@ -208,9 +209,6 @@ Stability: `1`
|
||||
|
||||
## Plugins
|
||||
|
||||
Plugins are rarely marked as stable as the `@backstage/core` plugin API is under
|
||||
heavy development.
|
||||
|
||||
Many backend plugins are split into "REST API" and "TypeScript Interface"
|
||||
sections. The "TypeScript Interface" refers to the API used to integrate the
|
||||
plugin into the backend.
|
||||
|
||||
@@ -511,10 +511,11 @@ clarify intent. Refer to the following table to formulate the new name:
|
||||
## Porting Existing Apps
|
||||
|
||||
The first step of porting any app is to replace the root `Routes` component with
|
||||
`FlatRoutes` from `@backstage/core`. As opposed to the `Routes` component,
|
||||
`FlatRoutes` only considers the first level of `Route` components in its
|
||||
children, and provides any additional children to the outlet of the route. It
|
||||
also removes the need to append `"/*"` to paths, as it is added automatically.
|
||||
`FlatRoutes` from `@backstage/core-app-api`. As opposed to the `Routes`
|
||||
component, `FlatRoutes` only considers the first level of `Route` components in
|
||||
its children, and provides any additional children to the outlet of the route.
|
||||
It also removes the need to append `"/*"` to paths, as it is added
|
||||
automatically.
|
||||
|
||||
```diff
|
||||
const AppRoutes = () => (
|
||||
|
||||
@@ -36,7 +36,7 @@ to avoid import cycles, for example like this:
|
||||
|
||||
```tsx
|
||||
/* src/routes.ts */
|
||||
import { createRouteRef } from '@backstage/core';
|
||||
import { createRouteRef } from '@backstage/core-plugin-api';
|
||||
|
||||
// Note: This route ref is for internal use only, don't export it from the plugin
|
||||
export const rootRouteRef = createRouteRef({
|
||||
@@ -46,11 +46,11 @@ export const rootRouteRef = createRouteRef({
|
||||
|
||||
Now that we have a `RouteRef`, we import it into `src/plugin.ts`, create our
|
||||
plugin instance with `createPlugin`, as well as create and wrap our routable
|
||||
extension using `createRoutableExtension` from `@backstage/core`:
|
||||
extension using `createRoutableExtension` from `@backstage/core-plugin-api`:
|
||||
|
||||
```tsx
|
||||
/* src/plugin.ts */
|
||||
import { createPlugin, createRouteRef } from '@backstage/core';
|
||||
import { createPlugin, createRouteRef } from '@backstage/core-plugin-api';
|
||||
import ExampleComponent from './components/ExampleComponent';
|
||||
|
||||
// Create a plugin instance and export this from your plugin package
|
||||
|
||||
@@ -57,7 +57,10 @@ package.json to declare the plugin dependencies, metadata and scripts.
|
||||
In the `src` folder we get to the interesting bits. Check out the `plugin.ts`:
|
||||
|
||||
```jsx
|
||||
import { createPlugin, createRoutableExtension } from '@backstage/core';
|
||||
import {
|
||||
createPlugin,
|
||||
createRoutableExtension,
|
||||
} from '@backstage/core-plugin-api';
|
||||
|
||||
import { rootRouteRef } from './routes';
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ can use this to split out logic in your code for manual A/B testing, etc.
|
||||
Here's a code sample:
|
||||
|
||||
```typescript
|
||||
import { createPlugin } from '@backstage/core';
|
||||
import { createPlugin } from '@backstage/core-plugin-api';
|
||||
|
||||
export default createPlugin({
|
||||
id: 'plugin-name',
|
||||
@@ -29,7 +29,7 @@ To inspect the state of a feature flag inside your plugin, you can use the
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { Button } from '@material-ui/core';
|
||||
import { featureFlagsApiRef, useApi } from '@backstage/core';
|
||||
import { featureFlagsApiRef, useApi } from '@backstage/core-plugin-api';
|
||||
|
||||
const ExamplePage = () => {
|
||||
const featureFlags = useApi(featureFlagsApiRef);
|
||||
|
||||
@@ -30,7 +30,7 @@ type PluginHooks = {
|
||||
Showcasing adding a feature flag.
|
||||
|
||||
```jsx
|
||||
import { createPlugin } from '@backstage/core';
|
||||
import { createPlugin } from '@backstage/core-plugin-api';
|
||||
|
||||
export default createPlugin({
|
||||
id: 'new-plugin',
|
||||
|
||||
@@ -55,10 +55,10 @@ const spotifyAuthApiRef = createApiRef<OAuthApi>({
|
||||
Sam realizes that Spotify auth might be useful to others, and that it would be
|
||||
more convenient if it was a part of the Backstage Core. After submitting and
|
||||
merging a Pull Request with the additions to the
|
||||
`@backstage/plugin-auth-backend` and `@backstage/core` packages, Spotify auth is
|
||||
now available for everyone to use. Since the Backstage Core team also adds it to
|
||||
the public demo server, Sam can now get rid of it in the local setup and rely on
|
||||
the shared development auth providers instead.
|
||||
`@backstage/plugin-auth-backend` and `@backstage/core-plugin-api` packages,
|
||||
Spotify auth is now available for everyone to use. Since the Backstage Core team
|
||||
also adds it to the public demo server, Sam can now get rid of it in the local
|
||||
setup and rely on the shared development auth providers instead.
|
||||
|
||||
The only thing left now is making sure that users of the plugin provide Spotify
|
||||
auth in the app. Sam ensures this by adding `spotifyAuthApiRef` to the plugin's
|
||||
@@ -70,7 +70,7 @@ README.
|
||||
|
||||
This plugin requires the following APIs to function:
|
||||
|
||||
- `spotifyAuthApiRef` from `@backstage/core@^1.1.0`
|
||||
- `spotifyAuthApiRef` from `@@backstage/core-plugin-api@^1.1.0`
|
||||
```
|
||||
|
||||
# 3. The Catalog Awakens
|
||||
|
||||
@@ -72,7 +72,7 @@ Our first modification will be to extract information from the Identity API.
|
||||
|
||||
```tsx
|
||||
// Add identityApiRef to the list of imported from core
|
||||
import { identityApiRef, useApi } from '@backstage/core';
|
||||
import { identityApiRef, useApi } from '@backstage/core-plugin-api';
|
||||
```
|
||||
|
||||
3. Adjust the ExampleComponent from inline to block
|
||||
@@ -137,13 +137,8 @@ changes, let's start by wiping this component clean.
|
||||
import React from 'react';
|
||||
import { useAsync } from 'react-use';
|
||||
import Alert from '@material-ui/lab/Alert';
|
||||
import {
|
||||
Table,
|
||||
TableColumn,
|
||||
Progress,
|
||||
githubAuthApiRef,
|
||||
useApi,
|
||||
} from '@backstage/core';
|
||||
import { Table, TableColumn, Progress } from '@backstage/core-components';
|
||||
import { githubAuthApiRef, useApi } from '@backstage/core-plugin-api';
|
||||
import { graphql } from '@octokit/graphql';
|
||||
|
||||
export const ExampleFetchComponent = () => {
|
||||
|
||||
Reference in New Issue
Block a user