diff --git a/.changeset/brave-windows-crash.md b/.changeset/brave-windows-crash.md new file mode 100644 index 000000000..0d2861e8e --- /dev/null +++ b/.changeset/brave-windows-crash.md @@ -0,0 +1,5 @@ +--- +'@hashicorp/react-docs-page': minor +--- + +Create and export new `getStaticGenerationFunctions` types diff --git a/packages/docs-page/server/index.ts b/packages/docs-page/server/index.ts index d81ed5c11..f98a81746 100644 --- a/packages/docs-page/server/index.ts +++ b/packages/docs-page/server/index.ts @@ -1,7 +1,9 @@ import { GetStaticPaths, GetStaticProps, GetStaticPathsResult } from 'next' import { ContentApiError } from '../content-api' -import FileSystemLoader from './loaders/file-system' -import RemoteContentLoader from './loaders/remote-content' +import FileSystemLoader, { FileSystemLoaderOpts } from './loaders/file-system' +import RemoteContentLoader, { + RemoteContentLoaderOpts, +} from './loaders/remote-content' import { DataLoader } from './loaders/types' // We currently export most utilities individually, @@ -14,32 +16,61 @@ export { getPathsFromNavData } from './get-paths-from-nav-data' export { validateNavData } from './validate-nav-data' export { default as validateFilePaths } from '@hashicorp/react-docs-sidenav/utils/validate-file-paths' -interface BaseOpts { +/** + * Shared config fields for both the `remote` and `fs` strategies. + * - See {@link RemoteOptions} & {@link FsOptions} for more details. + */ +export interface BaseOpts { fallback?: GetStaticPathsResult['fallback'] - revalidate?: number + revalidate?: number | boolean product: string scope?: Record } -export function getStaticGenerationFunctions( - opts: - | ({ - basePath: string - strategy: 'remote' - } & BaseOpts & - Partial[0]>) - | ({ - localContentDir: string - navDataFile: string - strategy: 'fs' - /** Optional location of the partials directory - * relative to process.cwd(). - * Passed to our resolveIncludes plugin. - * Defaults to "content/partials". */ - localPartialsDir?: string - } & BaseOpts & - Partial[0]>) -): { +/** + * Config object that is passed to {@link getStaticGenerationFunctions} + * when using the `remote` strategy + */ +export type RemoteOptions = { + basePath: string + strategy: 'remote' +} & BaseOpts & + Partial + +/** + * Config object that is passed to {@link getStaticGenerationFunctions} + * when using the `fs` strategy + */ +export type FsOptions = { + localContentDir: string + navDataFile: string + strategy: 'fs' + /** Optional location of the partials directory + * relative to process.cwd(). + * Passed to our resolveIncludes plugin. + * Defaults to "content/partials". */ + localPartialsDir?: string +} & BaseOpts & + Partial + +/** + * + * @usage + * + * ```typescript + * declare const remoteOpts: RemoteOptions + * declare const fsOpts: FsOptions + * + * declare const useFs: boolean + * + * const { getStaticPaths, getStaticProps } = getStaticGenerationFunctions( + * useFs ? fsOpts : remoteOpts + * ) + * + * export { getStaticPaths, getStaticProps } + * ``` + */ +export function getStaticGenerationFunctions(opts: RemoteOptions | FsOptions): { getStaticPaths: GetStaticPaths getStaticProps: GetStaticProps } { diff --git a/packages/docs-page/server/loaders/file-system.ts b/packages/docs-page/server/loaders/file-system.ts index 023edcac1..e9e6db727 100644 --- a/packages/docs-page/server/loaders/file-system.ts +++ b/packages/docs-page/server/loaders/file-system.ts @@ -16,7 +16,10 @@ import { getNodeFromPath } from '../get-node-from-path' import { DataLoader, DataLoaderOpts } from './types' -interface FileSystemLoaderOpts extends DataLoaderOpts { +/** + * Constructor object for {@link FileSystemLoader} + */ +export interface FileSystemLoaderOpts extends DataLoaderOpts { navDataFile: string localContentDir: string mainBranch?: string // = 'main', diff --git a/packages/docs-page/server/loaders/remote-content.ts b/packages/docs-page/server/loaders/remote-content.ts index b440be1da..1da9f769b 100644 --- a/packages/docs-page/server/loaders/remote-content.ts +++ b/packages/docs-page/server/loaders/remote-content.ts @@ -16,7 +16,10 @@ import { DEFAULT_PARAM_ID } from '../consts' import { DataLoader, DataLoaderOpts } from './types' import { getPathsFromNavData } from '../get-paths-from-nav-data' -interface RemoteContentLoaderOpts extends DataLoaderOpts { +/** + * Constructor object for {@link RemoteContentLoader} + */ +export interface RemoteContentLoaderOpts extends DataLoaderOpts { basePath: string /** * In most cases, `basePath` should suffice when resolving nav-data, because