diff --git a/.changeset/migrate-1713465986035.md b/.changeset/migrate-1713465986035.md new file mode 100644 index 0000000000..945d05a3d2 --- /dev/null +++ b/.changeset/migrate-1713465986035.md @@ -0,0 +1,8 @@ +--- +'@backstage/plugin-explore': patch +'@backstage/plugin-explore-backend': patch +'@backstage/plugin-explore-common': patch +'@backstage/plugin-explore-react': patch +--- + +These packages have been migrated to the [backstage/community-plugins](https://github.com/backstage/community-plugins) repository. diff --git a/plugins/explore-backend/README.md b/plugins/explore-backend/README.md index 6767749eab..88d606d396 100644 --- a/plugins/explore-backend/README.md +++ b/plugins/explore-backend/README.md @@ -1,222 +1,3 @@ -# explore-backend +# Deprecated -The `explore-backend` plugin provides a backend service for the Explore plugin. -This allows your organizations tools to be surfaced in the Explore plugin -through an API. It also provides a search collator to make it possible to search -for these tools. - -## Getting started - -### Adding the plugin to your `packages/backend` - -Install dependencies - -```bash -# From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-explore-backend -``` - -Add feature - -```ts title="packages/backend/src/index.ts" -backend.add(import('@backstage/plugin-explore-backend')); -``` - -Config: - -```yaml -explore: - tools: - - title: New Relic - description: new relic plugin - url: /newrelic - image: https://i.imgur.com/L37ikrX.jpg - tags: - - newrelic - - proxy - - nerdGraph -``` - -### Adding the plugin to your `packages/backend` (old) - -#### Tools as Config - -Install dependencies - -```bash -# From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-explore-backend -``` - -You'll need to add the plugin to the router in your `backend` package. You can -do this by creating a file called `packages/backend/src/plugins/explore.ts` with the following content: - -```ts title="packages/backend/src/plugins/explore.ts" -import { - createRouter, - StaticExploreToolProvider, -} from '@backstage/plugin-explore-backend'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - return await createRouter({ - logger: env.logger, - toolProvider: StaticExploreToolProvider.fromConfig(env.config), - }); -} -``` - -Config: - -```yaml -explore: - tools: - - title: New Relic - description: new relic plugin - url: /newrelic - image: https://i.imgur.com/L37ikrX.jpg - tags: - - newrelic - - proxy - - nerdGraph -``` - -#### Tools as Code - -Install dependencies - -```bash -# From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-explore-backend @backstage/plugin-explore-common -``` - -You'll need to add the plugin to the router in your `backend` package. You can -do this by creating a file called `packages/backend/src/plugins/explore.ts` with the following content: - -```ts -import { - createRouter, - StaticExploreToolProvider, -} from '@backstage/plugin-explore-backend'; -import { ExploreTool } from '@backstage/plugin-explore-common'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; - -// List of tools you want to surface in the Explore plugin "Tools" page. -const exploreTools: ExploreTool[] = [ - { - title: 'New Relic', - description: 'new relic plugin', - url: '/newrelic', - image: 'https://i.imgur.com/L37ikrX.jpg', - tags: ['newrelic', 'proxy', 'nerdGraph'], - }, -]; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - return await createRouter({ - logger: env.logger, - toolProvider: StaticExploreToolProvider.fromData(exploreTools), - }); -} -``` - -#### Register the plugin router - -With the `explore.ts` router setup in place, add the router to -`packages/backend/src/index.ts`: - -```diff -+import explore from './plugins/explore'; - -async function main() { - ... - const createEnv = makeCreateEnv(config); - - const catalogEnv = useHotMemoize(module, () => createEnv('catalog')); -+ const exploreEnv = useHotMemoize(module, () => createEnv('explore')); - - const apiRouter = Router(); -+ apiRouter.use('/explore', await explore(exploreEnv)); - ... - apiRouter.use(notFoundHandler()); -``` - -### Wire up Search Indexing - -To index explore tools you will need to register the search collator in the -`packages/backend/src/plugins/search.ts` file. - -```diff -+import { ToolDocumentCollatorFactory } from '@backstage/plugin-explore-backend'; - -... - -+ // collator gathers entities from explore. -+ indexBuilder.addCollator({ -+ schedule, -+ factory: ToolDocumentCollatorFactory.fromConfig(env.config, { -+ discovery: env.discovery, -+ logger: env.logger, -+ }), -+ }); - -... -``` - -### Wire up the Frontend - -See [the explore plugin README](../explore/README.md) for more information. - -## Explore Tool Customization - -The `explore-backend` uses the `ExploreToolProvider` interface to provide a list -of tools used in your organization and/or within your Backstage instance. This -can be customized to provide tools from any source. For example you could create -a `CustomExploreToolProvider` that queries an internal for tools in your -`packages/backend/src/plugins/explore.ts` file. - -```ts -import { - createRouter, - StaticExploreToolProvider, -} from '@backstage/plugin-explore-backend'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; - -class CustomExploreToolProvider implements ExploreToolProvider { - async getTools( - request: GetExploreToolsRequest, - ): Promise { - const externalTools = await queryExternalTools(request); - - const tools: ExploreTool[] = [ - ...externalTools, - // Backstage Tools - { - title: 'New Relic', - description: 'new relic plugin', - url: '/newrelic', - image: 'https://i.imgur.com/L37ikrX.jpg', - tags: ['newrelic', 'proxy', 'nerdGraph'], - }, - ]; - - return { tools }; - } -} - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - return await createRouter({ - logger: env.logger, - toolProvider: new CustomExploreToolProvider(), - }); -} -``` +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-explore-backend` instead. diff --git a/plugins/explore-backend/package.json b/plugins/explore-backend/package.json index 01caf18385..ca9a395286 100644 --- a/plugins/explore-backend/package.json +++ b/plugins/explore-backend/package.json @@ -2,7 +2,8 @@ "name": "@backstage/plugin-explore-backend", "version": "0.0.27", "backstage": { - "role": "backend-plugin" + "role": "backend-plugin", + "moved": "@backstage-community/plugin-explore-backend" }, "publishConfig": { "access": "public", @@ -51,5 +52,6 @@ "@types/supertest": "^2.0.8", "supertest": "^6.2.4" }, - "configSchema": "config.d.ts" + "configSchema": "config.d.ts", + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-explore-backend instead." } diff --git a/plugins/explore-common/README.md b/plugins/explore-common/README.md index 7e8c835660..371e41c72e 100644 --- a/plugins/explore-common/README.md +++ b/plugins/explore-common/README.md @@ -1,3 +1,3 @@ -# explore-common +# Deprecated -Shared types for the `explore` plugin. +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-explore-common` instead. diff --git a/plugins/explore-common/package.json b/plugins/explore-common/package.json index d9520a378e..8fe5afddad 100644 --- a/plugins/explore-common/package.json +++ b/plugins/explore-common/package.json @@ -3,7 +3,8 @@ "version": "0.0.2", "description": "Common functionalities for the explore plugin", "backstage": { - "role": "common-library" + "role": "common-library", + "moved": "@backstage-community/plugin-explore-common" }, "publishConfig": { "access": "public", @@ -36,5 +37,6 @@ }, "devDependencies": { "@backstage/cli": "workspace:^" - } + }, + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-explore-common instead." } diff --git a/plugins/explore-react/README.md b/plugins/explore-react/README.md index 4a881955df..2b3c0ae882 100644 --- a/plugins/explore-react/README.md +++ b/plugins/explore-react/README.md @@ -1,4 +1,3 @@ -# explore-react +# Deprecated -This package provides helpers to the `explore` plugin that can be imported by -any other plugin or app. +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-explore-react` instead. diff --git a/plugins/explore-react/package.json b/plugins/explore-react/package.json index 10efe3c972..606bb87c04 100644 --- a/plugins/explore-react/package.json +++ b/plugins/explore-react/package.json @@ -3,7 +3,8 @@ "version": "0.0.38", "description": "A frontend library for Backstage plugins that want to interact with the explore plugin", "backstage": { - "role": "web-library" + "role": "web-library", + "moved": "@backstage-community/plugin-explore-react" }, "publishConfig": { "access": "public", @@ -50,5 +51,6 @@ "react": "^16.13.1 || ^17.0.0 || ^18.0.0", "react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0", "react-router-dom": "6.0.0-beta.0 || ^6.3.0" - } + }, + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-explore-react instead." } diff --git a/plugins/explore/README.md b/plugins/explore/README.md index 24e6496cc3..d3ccc4a533 100644 --- a/plugins/explore/README.md +++ b/plugins/explore/README.md @@ -1,148 +1,3 @@ -# explore +# Deprecated -Welcome to the explore plugin! - -This plugin helps to visualize the top level entities like domains, groups and tools in your ecosystem. - -## Setup - -The following sections will help you get the Explore plugin setup and running. - -### Backend - -You need to setup the -[Explore backend plugin](https://github.com/backstage/backstage/tree/master/plugins/explore-backend) -before you move forward with any of these steps if you haven't already. - -### Installation - -Install this plugin: - -```bash -# From your Backstage root directory -yarn --cwd packages/app add @backstage/plugin-explore -``` - -### Add the plugin to your `packages/app` - -Add the root page that the playlist plugin provides to your app. You can choose -any path for the route, but we recommend the following: - -```diff -// packages/app/src/App.tsx -+ import { ExplorePage } from '@backstage/plugin-explore'; - -... - - - } /> - }> - {entityPage} - -+ } /> - ... - -``` - -You may also want to add a link to the playlist page to your application -sidebar: - -```diff -// packages/app/src/components/Root/Root.tsx -+import LayersIcon from '@material-ui/icons/Layers'; - -export const Root = ({ children }: PropsWithChildren<{}>) => ( - - -+ - ... - -``` - -### Use search result list item for Explore Tools - -When you have your `packages/app/src/components/search/SearchPage.tsx` file -ready to make modifications, add the following code snippet to add the -`ToolSearchResultListItem` when the type of the search results are -`tool`. - -```diff -+import { ToolSearchResultListItem } from '@backstage/plugin-explore'; -+import BuildIcon from '@material-ui/icons/Build'; - -const SearchPage = () => { - ... - - {({ results }) => ( - - {results.map(({ type, document, highlight, rank }) => { - switch (type) { - ... -+ case 'tools': -+ return ( -+ } -+ key={document.location} -+ result={document} -+ highlight={highlight} -+ rank={rank} -+ /> -+ ); - } - })} - - )} - ... - -... -``` - -## Customization - -Create a custom explore page in -`packages/app/src/components/explore/ExplorePage.tsx`. - -```tsx -import { - CatalogKindExploreContent, - ExploreLayout, -} from '@backstage/plugin-explore'; -import React from 'react'; -import { InnerSourceExploreContent } from './InnerSourceExploreContent'; - -export const ExplorePage = () => { - return ( - - - - - - - - - - - - ); -}; - -export const explorePage = ; -``` - -Now register the new explore page in `packages/app/src/App.tsx`. - -```diff -+import { explorePage } from './components/explore/ExplorePage'; - -const routes = ( - -- } /> -+ }> -+ {explorePage} -+ - -); -``` +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-explore` instead. diff --git a/plugins/explore/package.json b/plugins/explore/package.json index 25b45df023..1ffbbcccbd 100644 --- a/plugins/explore/package.json +++ b/plugins/explore/package.json @@ -3,7 +3,8 @@ "version": "0.4.20", "description": "A Backstage plugin for building an exploration page of your software ecosystem", "backstage": { - "role": "frontend-plugin" + "role": "frontend-plugin", + "moved": "@backstage-community/plugin-explore" }, "publishConfig": { "access": "public" @@ -81,5 +82,6 @@ "react": "^16.13.1 || ^17.0.0 || ^18.0.0", "react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0", "react-router-dom": "6.0.0-beta.0 || ^6.3.0" - } + }, + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-explore instead." }