diff --git a/contrib/docs/tutorials/authenticate-api-requests.md b/contrib/docs/tutorials/authenticate-api-requests.md index bc26a8c89a..6fc39811b5 100644 --- a/contrib/docs/tutorials/authenticate-api-requests.md +++ b/contrib/docs/tutorials/authenticate-api-requests.md @@ -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'; // ... diff --git a/contrib/docs/tutorials/aws-alb-aad-oidc-auth.md b/contrib/docs/tutorials/aws-alb-aad-oidc-auth.md index 0567a6bbb6..b121bab25f 100644 --- a/contrib/docs/tutorials/aws-alb-aad-oidc-auth.md +++ b/contrib/docs/tutorials/aws-alb-aad-oidc-auth.md @@ -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 diff --git a/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md b/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md index 18734682d5..fe56adddd8 100644 --- a/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md +++ b/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md @@ -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 = () => { diff --git a/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md b/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md index 262330119e..086175a0ce 100644 --- a/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md +++ b/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md @@ -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 = `{ diff --git a/docs/api/utility-apis.md b/docs/api/utility-apis.md index 56dd46794a..f04202b79b 100644 --- a/docs/api/utility-apis.md +++ b/docs/api/utility-apis.md @@ -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 diff --git a/docs/architecture-decisions/adr004-module-export-structure.md b/docs/architecture-decisions/adr004-module-export-structure.md index 846ca8feae..e6e378da9d 100644 --- a/docs/architecture-decisions/adr004-module-export-structure.md +++ b/docs/architecture-decisions/adr004-module-export-structure.md @@ -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 diff --git a/docs/auth/index.md b/docs/auth/index.md index 000c57a50c..76cd79b0fd 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -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', diff --git a/docs/auth/oauth.md b/docs/auth/oauth.md index bbab943dd1..fbd87d653b 100644 --- a/docs/auth/oauth.md +++ b/docs/auth/oauth.md @@ -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) diff --git a/docs/auth/using-auth.md b/docs/auth/using-auth.md index fbc6017272..e4f87a12f9 100644 --- a/docs/auth/using-auth.md +++ b/docs/auth/using-auth.md @@ -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 diff --git a/docs/cli/commands.md b/docs/cli/commands.md index a99d4cd9d0..ff61e51c75 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -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 diff --git a/docs/conf/reading.md b/docs/conf/reading.md index 6d4b61224d..6ac10a8c8b 100644 --- a/docs/conf/reading.md +++ b/docs/conf/reading.md @@ -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 diff --git a/docs/dls/contributing-to-storybook.md b/docs/dls/contributing-to-storybook.md index fff9e51e18..84282289f8 100644 --- a/docs/dls/contributing-to-storybook.md +++ b/docs/dls/contributing-to-storybook.md @@ -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. diff --git a/docs/features/search/getting-started.md b/docs/features/search/getting-started.md index 7408d69193..c412701499 100644 --- a/docs/features/search/getting-started.md +++ b/docs/features/search/getting-started.md @@ -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, diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md index 4dbc6bfa48..aa3851463f 100644 --- a/docs/getting-started/app-custom-theme.md +++ b/docs/getting-started/app-custom-theme.md @@ -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: ..., diff --git a/docs/getting-started/contributors.md b/docs/getting-started/contributors.md index e33d7a8479..e12c0c5f17 100644 --- a/docs/getting-started/contributors.md +++ b/docs/getting-started/contributors.md @@ -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 diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index fed8d101e0..ac78685a82 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -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 diff --git a/docs/overview/stability-index.md b/docs/overview/stability-index.md index a05be0e1eb..1cdde89a78 100644 --- a/docs/overview/stability-index.md +++ b/docs/overview/stability-index.md @@ -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. diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md index 52d8b69f7b..44c180fc5e 100644 --- a/docs/plugins/composability.md +++ b/docs/plugins/composability.md @@ -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 = () => ( diff --git a/docs/plugins/plugin-development.md b/docs/plugins/plugin-development.md index bfeed58c8f..f61fae0968 100644 --- a/docs/plugins/plugin-development.md +++ b/docs/plugins/plugin-development.md @@ -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 diff --git a/docs/plugins/structure-of-a-plugin.md b/docs/plugins/structure-of-a-plugin.md index f81e3794e5..beffcdb313 100644 --- a/docs/plugins/structure-of-a-plugin.md +++ b/docs/plugins/structure-of-a-plugin.md @@ -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'; diff --git a/docs/reference/createPlugin-feature-flags.md b/docs/reference/createPlugin-feature-flags.md index 5bfb4fe096..d550ba10a9 100644 --- a/docs/reference/createPlugin-feature-flags.md +++ b/docs/reference/createPlugin-feature-flags.md @@ -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); diff --git a/docs/reference/createPlugin.md b/docs/reference/createPlugin.md index e3df66fa12..6602b0b2cc 100644 --- a/docs/reference/createPlugin.md +++ b/docs/reference/createPlugin.md @@ -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', diff --git a/docs/tutorials/journey.md b/docs/tutorials/journey.md index adefdfa73f..249507ddf0 100644 --- a/docs/tutorials/journey.md +++ b/docs/tutorials/journey.md @@ -55,10 +55,10 @@ const spotifyAuthApiRef = createApiRef({ 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 diff --git a/docs/tutorials/quickstart-app-plugin.md b/docs/tutorials/quickstart-app-plugin.md index 99ba55c19d..e123410fe0 100644 --- a/docs/tutorials/quickstart-app-plugin.md +++ b/docs/tutorials/quickstart-app-plugin.md @@ -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 = () => {