Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VueAdvancedChat (as custom element registration)
✓ import 'vue-advanced-chat';
✗ import { VueAdvancedChat } from 'vue-advanced-chat';
This import primarily serves to register the `<vue-advanced-chat>` and `<emoji-picker>` custom elements globally in your application's entry point, rather than importing a specific JavaScript symbol. It's a side-effect import.
CSS Styles
✓ import 'vue-advanced-chat/dist/vue-advanced-chat.css';
This stylesheet is essential for the component's appearance and should be imported in your main application entry file (e.g., `main.js` or `App.vue`'s script setup) or a global stylesheet.
TypeScript Types
✓ import type { ChatMessage, Room, User } from 'vue-advanced-chat/dist/types';
✗ import { ChatMessage } from 'vue-advanced-chat';
For type safety in TypeScript projects, import specific interfaces and types like `ChatMessage`, `Room`, or `User` directly from the `/dist/types` path, as they are not typically exported from the main package entry.
This quickstart demonstrates how to set up `vue-advanced-chat` in a Vue 3 application using Vite. It covers the necessary `vite.config.ts` modifications to recognize custom elements, global CSS and component registration, and a basic `App.vue` component structure with example rooms, messages, and event handlers for sending and fetching messages.
/* vite.config.ts */
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
// Crucial for Vue to recognize vue-advanced-chat and emoji-picker as custom elements
isCustomElement: tagName => tagName === 'vue-advanced-chat' || tagName === 'emoji-picker'
}
}
})
]
});
/* main.ts or main.js */
import { createApp } from 'vue';
import App from './App.vue';
import 'vue-advanced-chat/dist/vue-advanced-chat.css'; // Essential styles
import 'vue-advanced-chat'; // Registers the custom Web Components
const app = createApp(App);
app.mount('#app');
/* App.vue */
<template>
<div id="app-container">
<vue-advanced-chat
height="100vh"
:current-user-id="currentUserId"
:rooms="JSON.stringify(rooms)"
:rooms-loaded="true"
:messages="JSON.stringify(messages)"
:messages-loaded="true"
@send-message="handleSendMessage"
@fetch-messages="handleFetchMessages"
/>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
// For type safety, if using TypeScript
// import type { ChatMessage, Room } from 'vue-advanced-chat/dist/types';
const currentUserId = 'user1';
const rooms = ref([
{
roomId: 'room1',
roomName: 'General Chat',
avatar: 'https://via.placeholder.com/150',
users: [
{ _id: 'user1', username: 'Alice' },
{ _id: 'user2', username: 'Bob' }
],
lastMessage: { content: 'Hello everyone!', senderId: 'user2', timestamp: Date.now() }
},
{
roomId: 'room2',
roomName: 'Private Discussion',
users: [
{ _id: 'user1', username: 'Alice' },
{ _id: 'user3', username: 'Charlie' }
],
lastMessage: { content: 'Meeting at 3 PM?', senderId: 'user3', timestamp: Date.now() }
}
]);
const messages = ref([
{
_id: 'msg1',
content: 'Hi there!',
senderId: 'user1',
timestamp: Date.now() - 60000
},
{
_id: 'msg2',
content: 'Hello Alice!',
senderId: 'user2',
timestamp: Date.now() - 30000
},
{
_id: 'msg3',
content: 'How are you two?',
senderId: 'user1',
timestamp: Date.now() - 10000
}
]);
const handleSendMessage = ({ detail }: any) => {
const { roomId, content, files, replyMessage } = detail; // 'detail' contains the event payload
console.log('New message:', { roomId, content, files, replyMessage });
messages.value.push({
_id: `msg${Date.now()}`,
content: content,
senderId: currentUserId,
timestamp: Date.now()
});
// In a real app, send this message to your backend
};
const handleFetchMessages = ({ detail }: any) => {
const { room, options } = detail;
console.log('Fetching messages for room:', room.roomId, options);
// Simulate async fetch for older messages
setTimeout(() => {
// Add logic to load historical messages based on 'options.reset' or 'options.direction'
}, 500);
};
</script>
<style>
body, html, #app {
margin: 0;
padding: 0;
height: 100%;
overflow: hidden; /* Important for full-height chat layout */
}
#app-container {
height: 100vh;
width: 100vw;
}
</style>
Errors
Common errors & fixes
[Vue warn]: Failed to resolve component: vue-advanced-chat
`vue-advanced-chat` is being used as a custom HTML element but is not registered as such in your Vue application's compiler options.
fixIn your Vue build configuration (e.g., `vite.config.js` for Vite or `vue.config.js` for Vue CLI), add `isCustomElement: tagName => tagName === 'vue-advanced-chat' || tagName === 'emoji-picker'` within your Vue plugin's `template.compilerOptions`.
(Component appears unstyled or with broken layout)
The core CSS stylesheet for `vue-advanced-chat` has not been imported into your application.
fixAdd `import 'vue-advanced-chat/dist/vue-advanced-chat.css';` to your main JavaScript/TypeScript entry file (e.g., `main.js`, `main.ts`) or a global style entry point.
TypeError: Converting circular structure to JSON
You are passing complex JavaScript objects directly to `rooms` or `messages` props, but the component expects these props to be pre-stringified JSON.
fixEnsure that the `rooms` and `messages` props are explicitly converted to JSON strings using `JSON.stringify()` before being passed to the component, e.g., `:rooms="JSON.stringify(myRoomsArray)"`.
Messages or rooms do not display, or sending messages does nothing.
The component is backend-agnostic and requires you to implement the logic for fetching and sending messages using its event API. It does not handle data persistence or real-time communication out-of-the-box.
fixImplement handlers for events like `@send-message` and `@fetch-messages` to interact with your chosen backend service. Update the component's `messages` and `rooms` props with data retrieved from your backend.
Audit
Dependencies
No dependency data recorded yet.