VuePress plugin that automatically registers Vue components globally within a VuePress site. It supports both directory-based component discovery through glob patterns and explicit component registration via configuration, with customizable component naming strategies.
npm install @vuepress/plugin-register-components or yarn add @vuepress/plugin-register-components// For use in VuePress config
const registerComponentsPlugin = require('@vuepress/plugin-register-components');For TypeScript projects:
import registerComponentsPlugin from '@vuepress/plugin-register-components';// In .vuepress/config.js
module.exports = {
plugins: [
// Basic usage - scan default components directory
'@vuepress/register-components',
// With configuration
[
'@vuepress/register-components',
{
componentsDir: './src/components',
components: [
{
name: 'MyCustomComponent',
path: './src/components/Custom.vue'
}
]
}
]
]
}The plugin operates during VuePress build time to generate dynamic JavaScript modules that register Vue components:
.vue files in specified directoriesCreates a VuePress plugin instance with component registration functionality.
/**
* VuePress plugin factory for registering components
* @param {PluginOptions} options - Configuration options for component registration
* @param {Context} context - VuePress context object
* @returns {PluginEntry} VuePress plugin object with component registration capabilities
*/
function registerComponentsPlugin(options, context): PluginEntry;
interface PluginOptions {
/** Directory or directories containing Vue components to register globally */
componentsDir?: string | string[];
/** Array of components to register explicitly by name and path */
components?: ComponentDefinition[];
/** Function to customize component names for files under componentsDir */
getComponentName?: (file: string) => string;
}
interface ComponentDefinition {
/** Component name for Vue.component registration */
name: string;
/** Absolute or relative path to the .vue component file */
path: string;
}
interface PluginEntry {
/** Allows plugin to be used multiple times */
multiple: true;
/** Generates component registration code during build */
enhanceAppFiles(): Promise<FileDescriptor[]>;
}
interface FileDescriptor {
/** Generated filename for the component registration module */
name: string;
/** JavaScript code that registers Vue components */
content: string;
}Usage Examples:
// Directory-based registration
module.exports = {
plugins: [
[
'@vuepress/register-components',
{
componentsDir: [
'./src/components',
'./docs/.vuepress/components'
]
}
]
]
}
// Explicit component registration
module.exports = {
plugins: [
[
'@vuepress/register-components',
{
components: [
{
name: 'MyButton',
path: './src/components/Button.vue'
},
{
name: 'MyCard',
path: './src/components/Card.vue'
}
]
}
]
]
}
// Custom naming function
module.exports = {
plugins: [
[
'@vuepress/register-components',
{
componentsDir: './components',
getComponentName: (file) => {
// Convert path/to/component.vue to PathToComponent
return file
.split('/')
.map(part => part.charAt(0).toUpperCase() + part.slice(1))
.join('');
}
}
]
]
}Automatically discovers Vue components in specified directories.
/**
* Scans a directory for Vue component files
* @param {string} componentDir - Directory path to scan for .vue files
* @returns {Promise<string[] | undefined>} Array of component file names without .vue extension
*/
async function resolveComponents(componentDir: string): Promise<string[] | undefined>;Converts file paths to component names for registration.
/**
* Default function to convert file paths to component names
* @param {string} file - File path relative to component directory
* @returns {string} Component name with slashes replaced by dashes
*/
function fileToComponentName(file: string): string;Usage Example:
fileToComponentName('forms/UserForm') // Returns: 'forms-UserForm'
fileToComponentName('ui/buttons/PrimaryButton') // Returns: 'ui-buttons-PrimaryButton'The plugin generates JavaScript modules that register components with Vue during runtime:
// Example generated content
import Vue from 'vue'
Vue.component("MyComponent", () => import("/path/to/MyComponent.vue"))
Vue.component("forms-UserForm", () => import("/path/to/forms/UserForm.vue"))string | string[][]All .vue files in specified directories will be automatically registered as global components. Component names are generated using the getComponentName function.
ComponentDefinition[][]Allows precise control over component registration with custom names and paths.
(file: string) => stringfile => file.replace(/\/|\\/g, '-')componentsDirThe function receives the file path (without .vue extension) relative to the component directory and should return the desired component name for Vue registration.