diff --git a/.changeset/sour-eggs-kick.md b/.changeset/sour-eggs-kick.md new file mode 100644 index 0000000000..6e814415ab --- /dev/null +++ b/.changeset/sour-eggs-kick.md @@ -0,0 +1,9 @@ +--- +'@backstage/plugin-catalog': patch +'@backstage/plugin-catalog-react': patch +--- + +Added the following deprecations to the `catalog-react` package: + +- **DEPRECATION**: `useEntity` will now warn if the entity has not yet been loaded. This hook is now designed only to be used inside of an `EntityPage` where the `entity` prop is guaranteed to be defined. If you would like to use it outside, please use `useAsyncEntity` instead. +- **DEPRECATION**: the `loading`, `error` and `refresh` properties that are returned from `useEntity` have been deprecated, and are available on `useAsyncEntity` instead. diff --git a/plugins/catalog-react/api-report.md b/plugins/catalog-react/api-report.md index e78ec75daa..0103ac2f0e 100644 --- a/plugins/catalog-react/api-report.md +++ b/plugins/catalog-react/api-report.md @@ -524,12 +524,24 @@ export type UnregisterEntityDialogProps = { }; // @public -export function useEntity(): { - entity: T; +export function useAsyncEntity< + T extends Entity = Entity, +>(): UseAsyncEntityResponse; + +// @public +export interface UseAsyncEntityResponse { + // (undocumented) + entity?: T; + // (undocumented) + error?: Error; + // (undocumented) loading: boolean; - error: Error | undefined; - refresh: VoidFunction | undefined; -}; + // (undocumented) + refresh?: VoidFunction; +} + +// @public +export function useEntity(): UseEntityResponse; // @public @deprecated export const useEntityCompoundName: () => { @@ -571,6 +583,18 @@ export function useEntityPermission(permission: Permission): { error?: Error; }; +// @public +export interface UseEntityResponse { + // (undocumented) + entity: T; + // @deprecated (undocumented) + error?: Error; + // @deprecated (undocumented) + loading: boolean; + // @deprecated (undocumented) + refresh?: VoidFunction; +} + // @public export function useEntityTypeFilter(): { loading: boolean; diff --git a/plugins/catalog-react/src/hooks/useEntity.tsx b/plugins/catalog-react/src/hooks/useEntity.tsx index 1db14adc22..9becedfee8 100644 --- a/plugins/catalog-react/src/hooks/useEntity.tsx +++ b/plugins/catalog-react/src/hooks/useEntity.tsx @@ -128,16 +128,27 @@ export const useEntityFromUrl = (): EntityLoadingStatus => { return { entity, loading, error, refresh }; }; + +/** + * @public + * + * The response shape for {@link useEntity} + */ export interface UseEntityResponse { entity: T; - /** @deprecated use useAsyncEntity instead */ + /** @deprecated use {@link useAsyncEntity} instead */ loading: boolean; - /** @deprecated use useAsyncEntity instead */ + /** @deprecated use {@link useAsyncEntity} instead */ error?: Error; - /** @deprecated use useAsyncEntity instead */ + /** @deprecated use {@link useAsyncEntity} instead */ refresh?: VoidFunction; } +/** + * @public + * + * The response shape for {@link useAsyncEntity} + */ export interface UseAsyncEntityResponse { entity?: T; loading: boolean; @@ -165,7 +176,14 @@ export function useEntity(): UseEntityResponse { } if (!value.entity) { - throw new Error('Entity has not been loaded yet'); + // Once we have removed the additional fields from being returned we can drop this deprecation + // and move to the error instead. + // throw new Error('useEntity hook is being called outside of an EntityPage where the entity has not been loaded. If this is intentional, please use useAsyncEntity instead.'); + + // eslint-disable-next-line no-console + console.warn( + 'DEPRECATION: useEntity hook is being called outside of an EntityPage where the entity has not been loaded. If this is intentional, please use useAsyncEntity instead. This warning will be replaced with an error in future releases.', + ); } const { entity, loading, error, refresh } = value;