如何使用组合 API 全局注册 Vue 3 组件？

Question

I'm creating a component library with Vue 3 and the composition API. The component library will be loaded in a NuxtJS application as a plugin. What is the right way to globally register the components (written according to the composition API) in this plugin?

./stories/Panel.vue (very reduced version):

<template>
    <div class="panel">
        <div class="header" v-if="title">{{ title }}</div>
        {{ content }}
    </div>
</template>

<style>
.panel .header {
    background-color: #7f7f7f;
    color: #fff;
}
</style>

<script setup lang="ts">
interface Props {
    title?: string;
    content?: string;
}

const name = 'my-panel';
const props = defineProps<Props>();
</script>

components.ts (contains all components):

import Panel from './stories/Panel.vue';
// all other components are imported and exported as well

export {
    Panel
};

lib.ts :

import * as components from './components';
import { App } from '@vue/runtime-core';

const plugin = {
    install(Vue: App) {
        Object.values(components).forEach((component) => {
            // Is there a way to globally register a component in a way
            // that the name, defined in the composition API is used?
            Vue.component(component);
        });
    },
};

export default plugin;

Answer 1

Here is a general method, with some options. You can decide the specifics based on what works best for you.

Principle

Variables exported in a normal <script> block can be imported separately to the component itself, and anything defined in that script block is also available in the <script setup> block.

Method

Components

The components will need to have the metadata exported from a regular <script> block. You have two options here: export the name directly (less boilerplate), or export a metadata object (recommended if you are going to need more metadata than just the name).

With just a name:

Panel.vue

<script lang="ts">
export const name = "my-panel";
</script>

<script setup lang="ts">
console.log(name) // `name` is available here.
</script>

With a metadata object:

Panel.vue

<script lang="ts">
export const metadata = {
  name: "my-panel",
};
</script>

<script setup lang="ts">
console.log(metadata.name) // `metadata` is available here.
</script>

Index

Unfortunately, this part is quite verbose compared to the original.

Just a name

The names must be included in the export somehow. This will require using an export of a single value, as we are not just exporting an existing binding (such as a variable or the imported components). As it is just a name in this case, a simple object with computed property keys will work. If you want, you could also use one of the "top-level array" methods shown in the "Metadata object" section.

components.ts

// Import the metadata as well.
import Panel, { name as PanelName } from './stories/Panel.vue';

// The export can be default or named.
export default {
  [PanelName]: Panel,
}

Metadata object

If you only need the name, you can use the method from the previous section.

components.ts

// Import the metadata as well.
import Panel, { metadata as PanelMetadata } from './stories/Panel.vue';

// This works the same as in the previous section.
// As before, the export can be default or named.
export default {
  [PanelMetadata.name]: Panel,
}

However, with a metadata object, you probably want the whole object to be included in the export.

You have four options in total. For the top level, you can use an object keyed with the name from the metadata object, or you can use an array. For the values, you can use an object with the keys being the names from the metadata objects and the values being an object holding the component and metadata object, or you can use an array. These options can be mixed and matched.

Using arrays for the values requires them to be as const so that TypeScript can infer the correct type.

// Array + array
export default [
  [Panel, PanelMetadata] as const,
];

// Array + object
export default [
  { component: Panel, metadata: PanelMetadata },
]

// Object + array
export default {
  [PanelMetadata.name]: [Panel, PanelMetadata] as const,
};

// Object + object
export default {
  [PanelMetadata.name]: { component: Panel, metadata: PanelMetadata },
};

Plugin

What you use here depends on whether you are using a name or a metadata object and on the method you used for exporting the components.

For just a name and simple object:

lib.ts :

// Assuming a default export.
import components from './components';
import { App } from '@vue/runtime-core';

const plugin = {
    // This is the app instance created by `createApp`.
    install(app: App) {
        // Get the `(key, value)` pairs of the export 
        // and register a component for each of them.
        Object.entries(components).forEach(([name, component]) => {
            app.component(name, component);
        });
    },
};

export default plugin;

For one of the other export methods:

// Array + array
components.forEach(([component, metadata]) => {
    app.component(metadata.name, component);
});

// Array + object
components.forEach(({ component, metadata }) => {
    app.component(metadata.name, component);
});

// Object + array
Object.values(components).forEach(([component, metadata]) => {
    app.component(metadata.name, component);
});

// Object + object
Object.values(components).forEach(({ component, metadata }) => {
    app.component(metadata.name, component);
});

You can probably see the patterns in the iterating and the callback parameter.

You could also use Object.entries for top-level objects, but this is a bit less clean:

// For array values
Object.entries(components).forEach(([name, componentData]) => {
    app.component(name, componentData[1]);

// For object values
Object.entries(components).forEach(([name, componentData]) => {
    app.component(name, componentData.component);
});

Documentation

From the API docs for app.component() :

Registers a global component if passing both a name string and a component definition, or retrieves an already registered one if only the name is passed.

See the component registration docs for more info.