Address review feedback from PR #33140

- Keep explicit error when API context provider exists but v1 is not
  available, only return empty holder when there is no provider at all
- Update tests in core-app-api to expect the new error message when
  rendering outside a provider
- Add @backstage/core-plugin-api to changeset since it re-exports
  useApiHolder

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/use-api-holder-no-throw.md

@@ -1,5 +1,6 @@
 ---
 '@backstage/frontend-plugin-api': patch
+'@backstage/core-plugin-api': patch
 ---
 
 Changed `useApiHolder` to return an empty `ApiHolder` instead of throwing when used outside of an API context.

packages/core-app-api/src/apis/system/ApiProvider.test.tsx

@@ -114,12 +114,16 @@ describe('ApiProvider', () => {
       withLogCollector(['error'], () => {
         expect(() => {
           render(<MyHookConsumer />);
-        }).toThrow(/^API context is not available/);
+        }).toThrow('No implementation available for apiRef{x}');
       }).error,
     ).toEqual([
-      expect.stringContaining('Error: API context is not available'),
+      expect.stringContaining(
+        'Error: No implementation available for apiRef{x}',
+      ),
       expect.objectContaining({ type: 'unhandled-exception' }),
-      expect.stringContaining('Error: API context is not available'),
+      expect.stringContaining(
+        'Error: No implementation available for apiRef{x}',
+      ),
       expect.objectContaining({ type: 'unhandled-exception' }),
       expect.stringContaining(
         'The above error occurred in the <MyHookConsumer> component',
@@ -130,12 +134,16 @@ describe('ApiProvider', () => {
       withLogCollector(['error'], () => {
         expect(() => {
           render(<MyHocConsumer />);
-        }).toThrow(/^API context is not available/);
+        }).toThrow('No implementation available for apiRef{x}');
       }).error,
     ).toEqual([
-      expect.stringContaining('Error: API context is not available'),
+      expect.stringContaining(
+        'Error: No implementation available for apiRef{x}',
+      ),
       expect.objectContaining({ type: 'unhandled-exception' }),
-      expect.stringContaining('Error: API context is not available'),
+      expect.stringContaining(
+        'Error: No implementation available for apiRef{x}',
+      ),
       expect.objectContaining({ type: 'unhandled-exception' }),
       expect.stringContaining(
         'The above error occurred in the <withApis(Component)> component',

packages/frontend-plugin-api/src/apis/system/useApi.tsx

@@ -32,7 +32,11 @@ export function useApiHolder(): ApiHolder {
     return emptyApiHolder;
   }
 
-  return versionedHolder.atVersion(1) ?? emptyApiHolder;
+  const apiHolder = versionedHolder.atVersion(1);
+  if (!apiHolder) {
+    throw new NotImplementedError('ApiContext v1 not available');
+  }
+  return apiHolder;
 }
 
 /**