@vendure-io/docs-provider

Contract types and utilities for Vendure documentation packages. This package defines the shared interface between the docs application (apps/docs) and external documentation packages (@vendure/docs-core, @vendure/docs-plugins, @vendure/docs-enterprise).

Documentation

• Getting Started - Quick introduction and overview
• Creating a Docs Package - Step-by-step guide to building a documentation package
• Manifest Reference - Complete API documentation for manifest types and utilities
• Frontmatter Reference - All available MDX frontmatter options
• MDX Components Reference - Available MDX components for reference documentation
• Publishing - How to publish and integrate with vendure.io

Installation

npm install @vendure-io/docs-provider
# or
bun add @vendure-io/docs-provider

Usage

Defining a Documentation Package Manifest

Documentation packages export a manifest that describes their structure. Important: File paths must be absolute paths. Use a helper pattern to resolve paths relative to your package root.

Quick Start (Minimal Config)

import { resolveManifest, type DocsPackageManifestInput } from '@vendure-io/docs-provider'
import { dirname, join } from 'path'
import { fileURLToPath } from 'url'

const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
const file = (relativePath: string) => join(packageRoot, relativePath)

// Minimal: title/slug auto-derived from files
const manifestInput: DocsPackageManifestInput = {
  id: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',
  vendureVersion: 'v3',
  basePath: packageRoot,
  navigation: [
    { file: file('docs/getting-started.mdx') },
    { file: file('docs/installation.mdx') },
    { file: file('docs/configuration.mdx') },
  ],
}

export const manifest = resolveManifest(manifestInput)

Using Folder Discovery

import {
  createNavigationFromFolder,
  resolveManifest,
  type DocsPackageManifestInput,
} from '@vendure-io/docs-provider'
import { dirname, join } from 'path'
import { fileURLToPath } from 'url'

const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
const file = (relativePath: string) => join(packageRoot, relativePath)

const manifestInput: DocsPackageManifestInput = {
  id: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',
  vendureVersion: 'v3',
  basePath: packageRoot,
  navigation: [
    { file: file('docs/getting-started.mdx') },
    {
      title: 'Guides',
      slug: 'guides',
      children: createNavigationFromFolder(join(packageRoot, 'docs/guides')),
    },
  ],
}

export const manifest = resolveManifest(manifestInput)

Explicit Navigation (Full Control)

import type { DocsPackageManifest } from '@vendure-io/docs-provider'
import { dirname, join } from 'path'
import { fileURLToPath } from 'url'

// Resolve the package root directory at module load time
const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))

// Helper to resolve file paths to absolute paths
const file = (relativePath: string) => join(packageRoot, relativePath)

export const manifest: DocsPackageManifest = {
  id: 'core',
  name: 'Vendure Core',
  version: '3.0.0',
  vendureVersion: 'v3',
  navigation: [
    {
      title: 'Getting Started',
      slug: 'getting-started',
      children: [
        {
          title: 'Installation',
          slug: 'installation',
          file: file('docs/getting-started/installation.mdx'),
        },
        {
          title: 'Configuration',
          slug: 'configuration',
          file: file('docs/getting-started/configuration.mdx'),
        },
      ],
    },
  ],
  search: {
    indexFields: ['title', 'description', 'content', 'keywords'],
    boosts: { title: 2, keywords: 1.5 },
  },
  github: {
    repository: 'your-org/your-repo',
    branch: 'main',
    docsPath: 'libs/your-docs-package',
  },
}

Your package should export the manifest from a dedicated entry point. Add the following to your package.json:

{
  "exports": {
    "./manifest": {
      "import": "./dist/manifest.js",
      "types": "./dist/manifest.d.ts"
    }
  }
}

Validating Manifests

import { validateManifest, ManifestValidationError } from '@vendure-io/docs-provider'

try {
  const manifest = validateManifest(rawManifestData)
} catch (error) {
  if (error instanceof ManifestValidationError) {
    console.error('Validation issues:', error.issues)
  }
}

Navigation Utilities

import {
  findNavigationNode,
  flattenNavigation,
  buildBreadcrumbs,
  getLeafNodes,
  getPrevNextNodes,
} from '@vendure-io/docs-provider'

// Find a node by slug path
const node = findNavigationNode(manifest, 'getting-started/installation')

// Flatten navigation tree
const flatNodes = flattenNavigation(manifest)

// Build breadcrumb trail
const breadcrumbs = buildBreadcrumbs(manifest, 'getting-started/installation')
// [
//   { title: 'Getting Started', slug: 'getting-started', path: 'getting-started' },
//   { title: 'Installation', slug: 'installation', path: 'getting-started/installation' }
// ]

// Get all pages (nodes with files)
const pages = getLeafNodes(manifest)

// Get previous/next pages for navigation
const { prev, next } = getPrevNextNodes(manifest, 'getting-started/installation')

Hidden Pages

You can hide pages from the sidebar navigation while keeping them accessible via direct URL:

const manifest: DocsPackageManifest = {
  // ...
  navigation: [
    {
      title: 'Public Page',
      slug: 'public',
      file: file('docs/public.mdx'),
    },
    {
      title: 'Hidden Page',
      slug: 'hidden',
      file: file('docs/hidden.mdx'),
      hidden: true, // Won't appear in sidebar, but /docs/hidden still works
    },
  ],
}

Browser Entry Point

For client-side React components (with 'use client'), use the /browser entry point to avoid bundling Node.js modules:

// In client components
import { filterVisibleNavigation, type NavigationNode } from '@vendure-io/docs-provider/browser'

// Filter hidden pages before rendering sidebar
const visibleNavigation = filterVisibleNavigation(manifest.navigation)

The main entry point includes Node.js-only utilities (resolveManifest, createNavigationFromFolder) that require fs access and cannot be used in browser contexts.

Parsing MDX Frontmatter

import { parseFrontmatter, hasFrontmatter } from '@vendure-io/docs-provider'

const mdxContent = `---
title: Installation Guide
description: Learn how to install Vendure
keywords:
  - install
  - setup
---

# Installation

Follow these steps to install Vendure...
`

if (hasFrontmatter(mdxContent)) {
  const { meta, content } = parseFrontmatter(mdxContent)
  console.log(meta.title) // "Installation Guide"
  console.log(content) // "# Installation\n\nFollow these steps..."
}

API Reference

Types

| Type | Description | | -------------------------- | ------------------------------------------------------ | | DocsPackageManifest | Main manifest describing a documentation package | | DocsPackageManifestInput | Manifest input with optional title/slug in navigation | | NavigationNode | A node in the navigation tree | | NavigationNodeInput | Navigation node input with optional title/slug | | DocPage | A loaded documentation page with metadata and content | | DocPageMeta | Frontmatter metadata for a page | | ParsedFrontmatter | Result of parsing frontmatter (meta + content) | | SearchConfig | Search indexing configuration | | VendureVersion | Supported Vendure versions ('v1' \| 'v2' \| 'v3') | | FlatNavigationNode | Flattened navigation node with path info | | BreadcrumbItem | Breadcrumb navigation item | | LoadedDocsPackage | Result of loading a docs package | | GitHubConfig | GitHub repository configuration for edit links | | FileInfo | Information about a discovered file (for folder utils) |

MDX Component Props

| Type | Description | | -------------------------- | --------------------------------------- | | GenerationInfoProps | Props for GenerationInfo component | | MemberInfoProps | Props for MemberInfo component | | MemberDescriptionProps | Props for MemberDescription component | | CustomFieldPropertyProps | Props for CustomFieldProperty component | | StackblitzProps | Props for Stackblitz component | | DocsLinkProps | Props for DocsLink component | | MdxComponentProps | Union type of all MDX component props |

Schemas (Zod)

All types have corresponding Zod schemas for runtime validation:

• DocsPackageManifestSchema
• DocsPackageManifestInputSchema
• NavigationNodeSchema
• NavigationNodeInputSchema
• DocPageSchema
• DocPageMetaSchema
• SearchConfigSchema
• GitHubConfigSchema
• VendureVersionSchema
• FlatNavigationNodeSchema
• BreadcrumbItemSchema
• LoadedDocsPackageSchema

Functions

Manifest Utilities

| Function | Description | | ---------------------------------------- | ----------------------------------------- | | validateManifest(data) | Validate raw data against manifest schema | | resolveManifest(input, options?) | Resolve manifest input to full manifest | | manifestNeedsResolution(input) | Check if manifest input needs resolution | | findNavigationNode(manifest, slugPath) | Find a node by slug path | | flattenNavigation(manifest) | Flatten navigation tree to array | | buildBreadcrumbs(manifest, slugPath) | Build breadcrumb trail | | getLeafNodes(manifest) | Get all nodes with files | | getPrevNextNodes(manifest, slugPath) | Get adjacent pages | | isNodeActive(node, currentPath) | Check if node matches path | | getNodesAtDepth(manifest, depth) | Get nodes at specific depth |

Navigation Utilities

| Function | Description | | ----------------------------------------------- | --------------------------------------- | | getAllFilePaths(manifest) | Get all file paths from manifest | | filterVisibleNavigation(nodes) | Filter out hidden nodes from navigation | | createNavigationFromFolder(path, options?) | Create navigation from folder contents | | createNestedNavigationFromFolder(path, opts?) | Create nested navigation from folders |

Slug Utilities

| Function | Description | | ------------------------- | ------------------------------- | | toSlug(text) | Convert text to kebab-case slug | | slugFromFilename(file) | Extract slug from filename | | titleFromFilename(file) | Generate title from filename |

Frontmatter Utilities

| Function | Description | | -------------------------------------- | ------------------------------------- | | parseFrontmatter(content, filePath?) | Parse and validate frontmatter | | validateFrontmatter(data, filePath?) | Validate frontmatter data | | hasFrontmatter(content) | Check if content has frontmatter | | extractFrontmatterData(content) | Extract raw frontmatter (unvalidated) |

Error Classes

| Class | Description | | ------------------------- | ------------------------------------- | | ManifestValidationError | Thrown when manifest validation fails | | ManifestResolutionError | Thrown when manifest resolution fails | | FrontmatterParseError | Thrown when frontmatter parsing fails |

Development

# Install dependencies
bun install

# Build the package
bun run build

# Run tests
bun run test

# Run tests in watch mode
bun run test:watch

# Type check
bun run type-check

# Lint
bun run lint

License

MIT