fix(API): address issues with text API in monorepos

Author: wise-king-sullyman

README.mdx

@@ -33,6 +33,7 @@ Any static assets, like images, can be placed in the `public/` directory.
 
 To define the markdown schema this project uses a typescript based schema known as [Zod](https://zod.dev). Details of how this is integratred into Astro can be found in Astros documentation on [content creation using Zod](https://docs.astro.build/en/guides/content-collections/#defining-datatypes-with-zod).
 
+Note: When running in dev mode locally, API endpoints are not available on a clean repo until either a build has been done or a tab route has been hit.
 ### 🧞 Commands
 
 All commands are run from the root of the project, from a terminal:

src/__tests__/pages/api/__tests__/[version]/[section]/[page]/[tab].test.ts

@@ -86,7 +86,7 @@ jest.mock('../../../../../../../utils', () => ({
       .replace(/[\s_]+/g, '-')
       .toLowerCase()
   }),
-  getDefaultTab: jest.fn((filePath?: string) => {
+  getDefaultTabForApi: jest.fn((filePath?: string) => {
     if (!filePath) {
       return 'react'
     }

src/pages/api/[version]/[section]/[page]/[tab].ts

@@ -5,8 +5,8 @@ import { getCollection } from 'astro:content'
 import { content } from '../../../../../content'
 import {
   kebabCase,
-  getDefaultTab,
   addDemosOrDeprecated,
+  getDefaultTabForApi,
 } from '../../../../../utils'
 import { generateAndWriteApiIndex } from '../../../../../utils/apiIndex/generate'
 import { getApiIndex } from '../../../../../utils/apiIndex/get'
@@ -44,7 +44,15 @@ export const getStaticPaths: GetStaticPaths = async () => {
     }
   }
 
-  return paths
+  // This shouldn't happen since we have a fallback tab value, but if it somehow does we need to alert the user
+  paths.forEach((path) => {
+    if (!path.params.tab) {
+      console.warn(`[API Warning] Tab not found for path: ${path.params.version}/${path.params.section}/${path.params.page}`)
+    }
+  })
+
+  // Again, this shouldn't happen since we have a fallback tab value, but if it somehow does and we don't filter out tabless paths it will crash the build
+  return paths.filter((path) => !!path.params.tab)
 }
 
 export const GET: APIRoute = async ({ params }) => {
@@ -109,7 +117,7 @@ export const GET: APIRoute = async ({ params }) => {
     ...rest,
     data: {
       ...data,
-      tab: data.tab || data.source || getDefaultTab(filePath),
+      tab: data.tab || data.source || getDefaultTabForApi(filePath),
     },
   }))
 

src/utils/__tests__/packageUtils.test.ts

@@ -1,4 +1,4 @@
-import { getPackageName, getTabBase, getDefaultTab, addDemosOrDeprecated } from '../packageUtils'
+import { getPackageName, getTabBase, getDefaultTab, getDefaultTabForApi, addDemosOrDeprecated } from '../packageUtils'
 
 describe('getPackageName', () => {
   it('returns empty string for empty input', () => {
@@ -192,3 +192,70 @@ describe('getDefaultTab', () => {
     expect(getDefaultTab(filePath)).toBe('')
   })
 })
+
+describe('getDefaultTabForApi', () => {
+  it('returns base tab for regular patternfly package path', () => {
+    const filePath = '/path/to/node_modules/@patternfly/patternfly/dist/index.js'
+    expect(getDefaultTabForApi(filePath)).toBe('html')
+  })
+
+  it('returns base tab for regular react-core package path', () => {
+    const filePath = '/path/to/node_modules/@patternfly/react-core/dist/index.js'
+    expect(getDefaultTabForApi(filePath)).toBe('react')
+  })
+
+  it('returns demos tab for demos path with patternfly package', () => {
+    const filePath = '/path/to/node_modules/@patternfly/patternfly/demos/Button.js'
+    expect(getDefaultTabForApi(filePath)).toBe('html-demos')
+  })
+
+  it('returns demos tab for demos path with react-core package', () => {
+    const filePath = '/path/to/node_modules/@patternfly/react-core/demos/Button.js'
+    expect(getDefaultTabForApi(filePath)).toBe('react-demos')
+  })
+
+  it('returns deprecated tab for deprecated path with patternfly package', () => {
+    const filePath = '/path/to/node_modules/@patternfly/patternfly/deprecated/OldButton.js'
+    expect(getDefaultTabForApi(filePath)).toBe('html-deprecated')
+  })
+
+  it('returns deprecated tab for deprecated path with react-core package', () => {
+    const filePath = '/path/to/node_modules/@patternfly/react-core/deprecated/OldButton.js'
+    expect(getDefaultTabForApi(filePath)).toBe('react-deprecated')
+  })
+
+  it('adds both demos and deprecated when both are in path', () => {
+    const filePath = '/path/to/node_modules/@patternfly/react-core/demos/deprecated/Button.js'
+    expect(getDefaultTabForApi(filePath)).toBe('react-demos-deprecated')
+  })
+
+  it('returns "text" fallback for unknown package', () => {
+    const filePath = '/path/to/node_modules/unknown-package/dist/index.js'
+    expect(getDefaultTabForApi(filePath)).toBe('text')
+  })
+
+  it('returns "text" fallback for path without node_modules', () => {
+    const filePath = '/path/to/some/file.js'
+    expect(getDefaultTabForApi(filePath)).toBe('text')
+  })
+
+  it('returns "text" fallback for empty input', () => {
+    expect(getDefaultTabForApi('')).toBe('text')
+  })
+
+  it('returns "text" fallback for null/undefined input', () => {
+    expect(getDefaultTabForApi(null as any)).toBe('text')
+    expect(getDefaultTabForApi(undefined)).toBe('text')
+    expect(getDefaultTabForApi()).toBe('text')
+  })
+
+  it('returns "text" fallback for unknown package with demos path', () => {
+    const filePath = '/path/to/node_modules/unknown-package/demos/Button.js'
+    expect(getDefaultTabForApi(filePath)).toBe('text')
+  })
+
+  it('returns "text" fallback for unknown package with deprecated path', () => {
+    const filePath = '/path/to/node_modules/unknown-package/deprecated/Button.js'
+    expect(getDefaultTabForApi(filePath)).toBe('text')
+  })
+})

src/utils/apiIndex/generate.ts

@@ -4,7 +4,9 @@ import { writeFile } from 'fs/promises'
 import { getCollection } from 'astro:content'
 import type { CollectionKey } from 'astro:content'
 import { content } from '../../content'
-import { kebabCase, getDefaultTab, addDemosOrDeprecated } from '../index'
+import { kebabCase, addDemosOrDeprecated } from '../index'
+import { getDefaultTabForApi } from '../packageUtils'
+import { getOutputDir } from '../getOutputDir'
 
 const SOURCE_ORDER: Record<string, number> = {
   react: 1,
@@ -107,7 +109,7 @@ export async function generateApiIndex(): Promise<ApiIndex> {
 
       // Collect tab
       const entryTab =
-        entry.data.tab || entry.data.source || getDefaultTab(entry.filePath)
+        entry.data.tab || entry.data.source || getDefaultTabForApi(entry.filePath)
       const tab = addDemosOrDeprecated(entryTab, entry.id)
       if (!pageTabs[pageKey]) {
         pageTabs[pageKey] = new Set()
@@ -137,7 +139,8 @@ export async function generateApiIndex(): Promise<ApiIndex> {
  * @param index - The API index structure to write
  */
 export async function writeApiIndex(index: ApiIndex): Promise<void> {
-  const indexPath = join(process.cwd(), 'src', 'apiIndex.json')
+  const outputDir = await getOutputDir()
+  const indexPath = join(outputDir, 'apiIndex.json')
 
   try {
     await writeFile(indexPath, JSON.stringify(index, null, 2))

src/utils/apiIndex/get.ts

@@ -1,6 +1,7 @@
 import { join } from 'path'
 import { readFile } from 'fs/promises'
 import type { ApiIndex } from './generate'
+import { getOutputDir } from '../getOutputDir'
 
 /**
  * Reads and parses the API index file
@@ -10,7 +11,8 @@ import type { ApiIndex } from './generate'
  * @throws Error if index file is not found, contains invalid JSON, or has invalid structure
  */
 export async function getApiIndex(): Promise<ApiIndex> {
-  const indexPath = join(process.cwd(), 'src', 'apiIndex.json')
+  const outputDir = await getOutputDir()
+  const indexPath = join(outputDir, 'apiIndex.json')
 
   try {
     const content = await readFile(indexPath, 'utf-8')

src/utils/getOutputDir.ts

@@ -0,0 +1,19 @@
+import { join } from 'path'
+import { getConfig } from '../../cli/getConfig'
+
+export async function getOutputDir(): Promise<string> {
+  const config = await getConfig(join(process.cwd(), 'pf-docs.config.mjs'))
+  if (!config) {
+    throw new Error(
+      'No config found, please run the `setup` command or manually create a pf-docs.config.mjs file',
+    )
+  }
+
+  if (!config.outputDir) {
+    throw new Error(
+      'No outputDir found in config file, an output directory must be defined in your config file e.g. "dist"',
+    )
+  }
+
+  return config.outputDir
+}

src/utils/packageUtils.ts

@@ -61,7 +61,9 @@ export const getDefaultTab = (filePath?: string): string => {
   const packageName = getPackageName(filePath)
   const tabBase = getTabBase(packageName)
 
-  const tab = addDemosOrDeprecated(tabBase, filePath)
-
-  return tab
+  return addDemosOrDeprecated(tabBase, filePath)
 }
+
+// This function is specifically for API routes where we need a fallback tab name
+// to ensure content is always accessible even when the default tab logic doesn't apply
+export const getDefaultTabForApi = (filePath?: string): string => getDefaultTab(filePath) || 'text'