Vue Components as a separate package ?

[elkofy]

What would you like?

I'd like to be able to use the vue component outside of vitepress. It would be nice if we could acess all the documents separately.

Why is this needed?

I need it because i am working on making an api portal and it has a little bit of core bussiness demands that requires not using vite press but a more robust vue app. I think.

How could it be implemented?

This could be a simple npm package containing all the coomponents and composable, also it might need some documentation upgrade.

Other information

No response

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and agent prompts for this issue.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

🔗 Similar Issues

Related Issues

• enzonotario/vitepress-openapi#89
• enzonotario/vitepress-openapi#71
• enzonotario/vitepress-openapi#229
• enzonotario/vitepress-openapi#198
• enzonotario/vitepress-openapi#91

👤 Suggested Assignees

• ashercoren
• glennsc
• Tzyito
• JG-js
• marc-mueller

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

[coderabbitai]

Implementation Plan

Approach

Enable the Vue component library to be used in standalone Vue 3 applications outside of VitePress, packaging it as a reusable npm package for API portal development and other custom Vue applications.

Observations

The project is a VitePress-based OpenAPI documentation library with 80+ Vue 3 components organized by feature domain (Feature, Path, Parameter, Response, Schema, Playground, etc.). Components use Composition API and are already largely framework-agnostic, with minimal VitePress coupling limited to dark mode storage key, CSS variable references, and sidebar generation utilities. The package currently exports multiple entry points (client, theme, node) and has well-organized composables, utilities, and i18n support.

Assumptions

Assumption 1: How should VitePress CSS variables (--vp-c-*) be handled in standalone mode?

Options Considered:

• Replace VitePress variables with generic equivalents and provide CSS variable mapping layer
• Provide default fallback values in CSS and let users override via CSS custom properties
• Bundle two separate CSS builds (VitePress and standalone variants)

Chosen Option: Provide default fallback values in CSS and let users override via CSS custom properties

Rationale: Provide default fallback values in CSS using CSS custom property fallbacks (e.g., var(--vp-c-border, var(--oa-border))), then define generic --oa-* variables with sensible defaults. This maintains backward compatibility for VitePress users while enabling standalone usage with minimal configuration. Users can override variables via standard CSS injection in their Vue app, which is the most natural approach for Vue developers.

Assumption 2: Should the standalone package include VitePress-specific features like sidebar generation?

Options Considered:

• Include it but mark as deprecated/optional in standalone mode
• Exclude it entirely from standalone exports
• Abstract it to return generic navigation structures

Chosen Option: Include it but mark as deprecated/optional in standalone mode

Rationale: Include it in exports but document it as VitePress-specific. Some users might want to generate navigation structures even in custom apps, and excluding it creates confusion about "missing" composables. The minimal VitePress type dependency (DefaultTheme) can be abstracted to a generic interface, making the utility more flexible while preserving the existing API for VitePress users.

Assumption 3: How should dark mode detection work without VitePress's useDark integration?

Options Considered:

• Make storage key configurable via theme config
• Remove dark mode logic entirely and let users manage it
• Provide dark mode as an injectable dependency

Chosen Option: Make storage key configurable via theme config

Rationale: Make storage key configurable via theme initialization options with a default that works for both VitePress and standalone contexts. This preserves existing behavior for VitePress users while allowing standalone apps to specify their own dark mode strategy. The useTheme composable will accept an optional darkModeStorageKey parameter, defaulting to 'vitepress-theme-appearance' for backward compatibility.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Plan

Phase 1: Abstract VitePress Dependencies

Decouple the few VitePress-specific dependencies to make components truly framework-agnostic. This phase focuses on configuration-based abstraction rather than code removal.

Task 1: Make Dark Mode Storage Configurable

Enable custom dark mode storage keys for non-VitePress environments while maintaining backward compatibility.

• Update src/composables/useTheme.ts to accept optional darkModeStorageKey parameter in theme initialization
• Modify the useDark() call to use configurable storage key instead of hardcoded 'vitepress-theme-appearance'
• Add TypeScript interface for initialization options including darkModeStorageKey property
• Set default value to 'vitepress-theme-appearance' to preserve existing VitePress behavior

Task 2: Abstract Sidebar Types from VitePress

Remove direct VitePress type dependencies from sidebar generation utilities.

• Create generic SidebarItem interface in src/types.ts matching VitePress's DefaultTheme.SidebarItem structure
• Update src/composables/useSidebar.ts to use the generic interface instead of importing from VitePress
• Update src/lib/sidebar/cleanSidebarItems.ts to use generic types
• Ensure type compatibility so VitePress users can still pass items to VitePress theme config

Task 3: Create CSS Variable Fallback System

Establish fallback CSS variables for VitePress-specific styling tokens to enable standalone usage.

• Define --oa-* prefixed CSS variables in src/style.css with sensible default values (colors, spacing, borders)
• Update tailwind.config.js to reference VitePress variables with --oa-* fallbacks using CSS custom property cascade
• Modify src/json.css to use VitePress variables with --oa-* fallbacks for JSON viewer theming
• Add CSS variable documentation comments explaining the dual-variable system

🤖 Prompt for AI agents

Decouple VitePress-specific dependencies to make components framework-agnostic
through configuration-based abstraction.

Make dark mode storage configurable:
- Update useTheme.ts to accept optional darkModeStorageKey parameter in theme
initialization
- Replace hardcoded 'vitepress-theme-appearance' with configurable storage key
in useDark() call
- Add TypeScript interface for initialization options with darkModeStorageKey
property
- Default to 'vitepress-theme-appearance' for backward compatibility

Abstract sidebar types:
- Create generic SidebarItem interface in src/types.ts matching VitePress
DefaultTheme.SidebarItem structure
- Update useSidebar.ts and cleanSidebarItems.ts to use generic interface instead
of VitePress imports
- Maintain type compatibility with VitePress theme config

Create CSS variable fallback system:
- Define --oa-* prefixed CSS variables in src/style.css with default values
- Update tailwind.config.js to use VitePress variables with --oa-* fallbacks
- Modify src/json.css to use VitePress variables with --oa-* fallbacks
- Add documentation comments explaining dual-variable system

Phase 2: Create Standalone Entry Point and Initialization API

Provide a dedicated export path and initialization mechanism for Vue applications that don't use VitePress.

Task 1: Create Standalone Entry Point

Build a new entry point specifically for standalone Vue applications.

• Create src/standalone.ts that exports components, composables, and a createOpenAPIPlugin function
• Export all public components from src/components/index.ts through the standalone entry
• Export composables (useTheme, useOpenapi, usePlayground, useShiki, useMarkdown, usePaths) excluding VitePress-specific ones if any
• Export utility functions from src/lib/ that are useful for consumers (parseSpec, OpenApi, etc.)
• Export locale definitions for i18n from src/locales/

Task 2: Create Vue Plugin for Standalone Initialization

Develop a Vue plugin that handles theme configuration and i18n setup without VitePress.

• Implement createOpenAPIPlugin function in src/standalone.ts that accepts configuration options
• Plugin should initialize theme configuration via useTheme with provided options
• Plugin should set up i18n using @byjohann/vue-i18n with locale support
• Plugin should optionally register components globally based on configuration
• Accept options for: theme config, dark mode storage key, locale, global component registration flag

Task 3: Provide Styling Import Path

Expose CSS imports for standalone consumers to include in their builds.

• Create src/styles.ts that re-exports Tailwind, style.css, and json.css
• Document CSS variable customization approach for consumers
• Ensure CSS imports work with common Vue build tools (Vite, webpack, etc.)

🤖 Prompt for AI agents

Create a dedicated standalone entry point and initialization API for
non-VitePress Vue applications.

Create standalone entry point:
- Create src/standalone.ts exporting components, composables, and
createOpenAPIPlugin function
- Export all public components from src/components/index.ts
- Export composables (useTheme, useOpenapi, usePlayground, useShiki,
useMarkdown, usePaths)
- Export utility functions from src/lib/ (parseSpec, OpenApi, etc.)
- Export locale definitions from src/locales/

Create Vue plugin:
- Implement createOpenAPIPlugin function accepting configuration options
- Initialize theme configuration via useTheme with provided options
- Set up i18n using @byjohann/vue-i18n with locale support
- Optionally register components globally based on configuration
- Accept options: theme config, dark mode storage key, locale, global component
registration flag

Provide styling import path:
- Create src/styles.ts re-exporting Tailwind, style.css, and json.css
- Ensure compatibility with common Vue build tools (Vite, webpack)

Phase 3: Update Build Configuration and Package Exports

Configure the build system to generate proper bundles for standalone usage and update package.json exports.

Task 1: Add Standalone Build Target

Extend Vite build configuration to generate standalone bundle.

• Add new entry point in vite.config.ts for standalone: standalone: resolve(__dirname, 'src/standalone.ts')
• Configure build to externalize Vue and common dependencies (don't bundle Vue, @vueuse/core, etc.)
• Ensure TypeScript declarations are generated for standalone entry
• Configure rollup to preserve ES modules for tree-shaking

Task 2: Update Package.json Exports

Add conditional exports for standalone usage path.

• Add "./standalone" export pointing to standalone build output
• Add "./styles" export pointing to CSS files or styles entry point
• Ensure "." (default) export maintains backward compatibility with current behavior
• Update exports field to include both standalone and client paths with proper conditions

Task 3: Update Dependencies Configuration

Review and adjust dependency declarations for standalone usage.

• Keep VitePress as peerDependency but mark as optional for standalone users
• Ensure Vue 3 and other core dependencies are correctly marked as peerDependencies
• Document minimum version requirements for Vue and other peer dependencies
• Add package.json metadata indicating framework compatibility

🤖 Prompt for AI agents

Configure build system to generate standalone bundles and update package
exports.

Add standalone build target:
- Add entry point in vite.config.ts: standalone: resolve(__dirname,
'src/standalone.ts')
- Externalize Vue and common dependencies (@vueuse/core, etc.)
- Generate TypeScript declarations for standalone entry
- Configure rollup to preserve ES modules for tree-shaking

Update package.json exports:
- Add "./standalone" export pointing to standalone build output
- Add "./styles" export pointing to CSS files or styles entry point
- Ensure "." (default) export maintains backward compatibility
- Update exports field with proper conditions for standalone and client paths

Update dependencies:
- Mark VitePress as optional peerDependency for standalone users
- Ensure Vue 3 and core dependencies are peerDependencies
- Document minimum version requirements
- Add framework compatibility metadata to package.json

Phase 4: Documentation and Examples

Provide comprehensive documentation and working examples for standalone usage.

Task 1: Create Standalone Usage Guide

Document how to install and use the package in regular Vue applications.

• Create new documentation page (e.g., docs/standalone-usage.md) covering installation
• Document plugin initialization with createOpenAPIPlugin and configuration options
• Explain CSS import requirements and customization through CSS variables
• Provide examples of manual component imports vs. global registration

Task 2: Create Example Vue Application

Build a working example demonstrating standalone usage.

• Create example directory with minimal Vue 3 + Vite application
• Show plugin initialization in main.ts with theme configuration
• Demonstrate component usage with OpenAPI spec loading
• Include examples of both global and local component registration patterns
• Show CSS variable customization examples

Task 3: Update Main Documentation

Enhance existing documentation to cover both VitePress and standalone modes.

• Update README.md to mention standalone usage alongside VitePress integration
• Add "Installation" section covering both usage modes
• Document differences between VitePress theme mode and standalone component mode
• Add migration guide for users wanting to switch between modes
• Update API documentation to clarify which features are VitePress-specific

🤖 Prompt for AI agents

Create comprehensive documentation and working examples for standalone usage.

Create standalone usage guide:
- Create docs/standalone-usage.md covering installation
- Document createOpenAPIPlugin initialization and configuration options
- Explain CSS import requirements and CSS variable customization
- Provide examples of manual component imports vs. global registration

Create example Vue application:
- Create example directory with minimal Vue 3 + Vite app
- Show plugin initialization in main.ts with theme configuration
- Demonstrate component usage with OpenAPI spec loading
- Include global and local component registration patterns
- Show CSS variable customization examples

Update main documentation:
- Update README.md to mention standalone usage alongside VitePress
- Add Installation section covering both usage modes
- Document differences between VitePress theme mode and standalone component
mode
- Add migration guide for switching between modes
- Update API documentation to clarify VitePress-specific features

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Decouple VitePress-specific dependencies to make components framework-agnostic
through configuration-based abstraction.

Make dark mode storage configurable:
- Update useTheme.ts to accept optional darkModeStorageKey parameter in theme
initialization
- Replace hardcoded 'vitepress-theme-appearance' with configurable storage key
in useDark() call
- Add TypeScript interface for initialization options with darkModeStorageKey
property
- Default to 'vitepress-theme-appearance' for backward compatibility

Abstract sidebar types:
- Create generic SidebarItem interface in src/types.ts matching VitePress
DefaultTheme.SidebarItem structure
- Update useSidebar.ts and cleanSidebarItems.ts to use generic interface instead
of VitePress imports
- Maintain type compatibility with VitePress theme config

Create CSS variable fallback system:
- Define --oa-* prefixed CSS variables in src/style.css with default values
- Update tailwind.config.js to use VitePress variables with --oa-* fallbacks
- Modify src/json.css to use VitePress variables with --oa-* fallbacks
- Add documentation comments explaining dual-variable system
===============================================================================

Task: 2

Create a dedicated standalone entry point and initialization API for
non-VitePress Vue applications.

Create standalone entry point:
- Create src/standalone.ts exporting components, composables, and
createOpenAPIPlugin function
- Export all public components from src/components/index.ts
- Export composables (useTheme, useOpenapi, usePlayground, useShiki,
useMarkdown, usePaths)
- Export utility functions from src/lib/ (parseSpec, OpenApi, etc.)
- Export locale definitions from src/locales/

Create Vue plugin:
- Implement createOpenAPIPlugin function accepting configuration options
- Initialize theme configuration via useTheme with provided options
- Set up i18n using @byjohann/vue-i18n with locale support
- Optionally register components globally based on configuration
- Accept options: theme config, dark mode storage key, locale, global component
registration flag

Provide styling import path:
- Create src/styles.ts re-exporting Tailwind, style.css, and json.css
- Ensure compatibility with common Vue build tools (Vite, webpack)
===============================================================================

Task: 3

Configure build system to generate standalone bundles and update package
exports.

Add standalone build target:
- Add entry point in vite.config.ts: standalone: resolve(__dirname,
'src/standalone.ts')
- Externalize Vue and common dependencies (@vueuse/core, etc.)
- Generate TypeScript declarations for standalone entry
- Configure rollup to preserve ES modules for tree-shaking

Update package.json exports:
- Add "./standalone" export pointing to standalone build output
- Add "./styles" export pointing to CSS files or styles entry point
- Ensure "." (default) export maintains backward compatibility
- Update exports field with proper conditions for standalone and client paths

Update dependencies:
- Mark VitePress as optional peerDependency for standalone users
- Ensure Vue 3 and core dependencies are peerDependencies
- Document minimum version requirements
- Add framework compatibility metadata to package.json
===============================================================================

Task: 4

Create comprehensive documentation and working examples for standalone usage.

Create standalone usage guide:
- Create docs/standalone-usage.md covering installation
- Document createOpenAPIPlugin initialization and configuration options
- Explain CSS import requirements and CSS variable customization
- Provide examples of manual component imports vs. global registration

Create example Vue application:
- Create example directory with minimal Vue 3 + Vite app
- Show plugin initialization in main.ts with theme configuration
- Demonstrate component usage with OpenAPI spec loading
- Include global and local component registration patterns
- Show CSS variable customization examples

Update main documentation:
- Update README.md to mention standalone usage alongside VitePress
- Add Installation section covering both usage modes
- Document differences between VitePress theme mode and standalone component
mode
- Add migration guide for switching between modes
- Update API documentation to clarify VitePress-specific features

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.