Advanced Chat Components: two install paths, one chat UI, and the data layer you write yourself

Two package names, two branches, and V3 is not a drop-in replacement

V3 and V2 of this library are separate npm packages with different names, and the README is direct about what that means for existing users: V3 is not a drop-in replacement for V2. A project that moves from one to the other is doing a migration, not a version bump.

V3 is published under `@advanced-chat/components` on the npm `next` tag, at version 3.0.0-rc.3, with that release candidate dated 2026-08-09. V2 goes by a different name entirely: `[email protected]`, last updated on 2025-12-19. Source branching follows the package split: V2 source and documentation stay on the `v2` branch, while V3 source occupies the default branch.

The file `rewrite/issue-triage.md` in the repository maps which V2 issues V3 addresses. That document is a rough guide, not a promise of parity. An existing v2 application cannot look at the issue map and skip a careful test of the migration.

Anyone starting a new project can choose either line. V2 is the stable one with a fixed public API. V3 is the active development track, with the last repository push on 2026-09-10, but its 3.0.0-rc.3 status means the interface has not been frozen for a final release. A production deployment built on a release candidate inherits that uncertainty.

Installing V3 from the npm next tag requires Vue 3.5 as a peer dependency

V3 arrives from a single install command, and the tag suffix is required to reach the correct package:

npm install @advanced-chat/components@next

Without `@next`, npm resolves to the most recent stable version in the default registry, which is the V2 line under the `vue-advanced-chat` package name, and the install lands somewhere unexpected. The `@next` tag routes the command to 3.0.0-rc.3 specifically.

Vue 3.5 or newer is a declared peer dependency. The package is marked `"type": "module"` in its package.json, making it ESM-only for Node module resolution. For CDN use, a UMD build is available through paths set in the package.json metadata: `"unpkg"` and `"jsdelivr"` both point to `dist/components.umd.js`. That path does not ship through the npm install, so a bundler project does not get it by default.

V2 installs from a different command:

npm install vue-advanced-chat

V2 documentation and source are on the `v2` branch, and the two install commands are not interchangeable because the library includes no compatibility shim between versions.

Registering the Vue plugin and wiring the AdvancedChat component props

After installing V3, two steps precede a working component: a plugin call in the application entry point, and a stylesheet import.

// main.ts
import { createApp } from 'vue'
import App from './App.vue'

import { AdvancedChatPlugin } from '@advanced-chat/components'
import '@advanced-chat/components/styles'

createApp(App).use(AdvancedChatPlugin()).mount('#app')

The plugin registers the component globally, so individual files do not need to import `AdvancedChat` directly. Inside a Vue SFC, the component accepts typed props: `current-user`, `chats`, `chat`, `messages`, `messages-loaded`, `chats-loaded`, `height`, and `theme`. The quick example in the README uses `theme="auto"`, and both `messages-loaded` and `chats-loaded` are required bool props that control whether loading indicators appear.

The types export from the same path as the component:

<script setup lang="ts">
import {
  AdvancedChat,
  type ChatModel,
  type MessageModel,
  type User,
} from '@advanced-chat/components'

const currentUser: User = { id: 'me', name: 'Alice', status: { state: 'online' } }
</script>

The package contains 28 typed Vue 3 single-file components in total, and TypeScript definitions for props, events and slots are published to `dist/index.d.ts`, which is the contract for TypeScript consumers. The documentation site at advanced-chat.github.io carries per-component prop, event and slot tables for the full detail beyond what the types alone communicate.

The web-component entrypoint uses DOM property assignment, not HTML attributes

A second entrypoint, `@advanced-chat/components/web-component`, serves non-Vue applications. Importing it auto-registers a custom element named `<advanced-chat-components>` and bundles the Vue runtime into that module. The element renders in light DOM, not shadow DOM.

<advanced-chat-components id="chat"></advanced-chat-components>
<script type="module">
  import '@advanced-chat/components/web-component'
  import '@advanced-chat/components/web-component/styles'

  const chat = document.querySelector('#chat')
  chat.currentUser = { id: 'me', name: 'Alice', status: { state: 'online' } }
  chat.chats = [{ id: 'general', name: 'General', users: [] }]
  chat.chat = chat.chats[0]
  chat.messages = []
  chat.chatsLoaded = true
  chat.messagesLoaded = true
</script>

Every assignment is a DOM property write, not an HTML attribute, because a framework that serializes props as HTML attribute strings will not work here and objects must be handed to the element as live JavaScript values.

The package ships a `custom-elements.json` manifest for IDE completion and custom-element-aware tooling. This file is listed under the `"customElements"` field in package.json and is included in the published npm artifact. The documentation site carries working examples for Angular, React, Svelte and vanilla JavaScript on its Web Components page.

Events carry typed payloads, mention tokens and attachment URL ownership rules

Public events on the web component are standard DOM events. They bubble and cross shadow boundaries, so one listener on a container element above the component is enough; there is no need to listen directly on `<advanced-chat-components>`.

The `send-message` event shows the payload structure. Its `CustomEvent.detail` carries `content`, `files` and `mentionedUsers`. When the user @-mentions someone, the mention is serialized as a stable `<@id>` token inside `content`, and the full user object appears in `mentionedUsers`. There is no need to parse display names out of the message text; the token and the user arrive together in the same event. The `edit-message` event follows the same payload structure, exposing `content`, `files` and `mentionedUsers` in the same way.

Attachment handling has a specific ownership handoff. The library owns the object URLs for pending attachments until the host's send or edit handler fires. Ownership of the emitted `localUrl` values then transfers to the host, which must revoke them when they are no longer needed. Missing that step leaves dangling object URLs in memory until the page is closed or reloaded.

Event payloads are exposed as `CustomEvent.detail` rather than wrapped in a Vue argument array, so any non-Vue framework reads the data the same way.

Transport, persistence, realtime delivery and authorization are not in the library

The README is explicit: transport, persistence, authorization, upload, realtime delivery and retry policy remain the host application's responsibility. Nothing in the feature list moves any of that closer to the component.

What this means in practice: the library does not open a WebSocket, does not call an API endpoint, does not manage authentication tokens, and does not handle message delivery failures or optimistic updates. It renders the props it receives and emits events when the user acts.

For Firebase, the repository topics list `firestore`, and the documentation site carries a cookbook section on backend integration. The README does not include any Firestore code; the cookbook is where that content lives, and the integration itself is the developer's work.

A team adding this component to a fresh backend should plan for a real-time subscription layer, a message queue, delivery receipts and a retry mechanism before the chat UI connects to real users. Nothing in the package provides a default for any of those pieces, and the cookbook section is the only guidance on how they connect.

registerAdvancedChat handles custom tag names and server-side rendering guards

The auto-registration side effect in `@advanced-chat/components/web-component` runs immediately on import. Applications that cannot allow that, such as a server-side rendered page where `window` does not exist, import the side-effect-free core path instead:

import {
  registerAdvancedChat,
  type AdvancedChatHTMLElement,
} from '@advanced-chat/components/web-component/core'
import '@advanced-chat/components/web-component/styles'

if (typeof window !== 'undefined') {
  registerAdvancedChat({ tagName: 'acme-chat' })
}

`registerAdvancedChat` accepts three options: `tagName`, `strings` and `localization`. Passing a `tagName` registers the element under a custom name, which matters when the page already uses the default name for an unrelated element.

Calling `registerAdvancedChat` for the default managed tag after auto-registration updates options only for elements mounted after that call. Already-mounted elements keep the localization they were initialized with. Options are never silently applied to a tag registered by an unrelated constructor, a boundary the README documents explicitly rather than leaving it to inference.

The `AdvancedChatHTMLElement` type export, along with `AdvancedChatEventMap` and `AdvancedChatElementConstructor`, makes DOM properties and event details typed for TypeScript consumers of the web component.

Node 22.14.0, the verify script gates and what the package puts in dist

Development requires Node 22.14.0 or newer, pinned in the `.nvmrc` file at the repository root. Two Vite config files separate the component build from the web-component build: `vite.config.ts` for the main library and `vite.web-component.config.ts` for the custom element path. Three TypeScript configs handle the root, the library and the Node environment separately.

The verify script chains the full release gate:

npm run verify

The README names what that chains: format, types, lint, tests, build, pack and storybook. Named sub-scripts accessible through `npm run` include `format`, `format:check`, `lint`, `type-check`, `test`, `test:unit`, `test:storybook`, `test:coverage`, `build`, `build-storybook`, `verify:pack` and `verify:web-component`. A contributor running `verify` before a pull request runs the same check the CI pipeline runs.

For local development, `npm run storybook` starts the Storybook server, which also builds the documentation site. A documentation change and a code change go through the same build step.

The `package.json` lists two contributors: Antoine Dupont and Aaron Nwabuoku. The MIT license applies to the package, and `THIRD_PARTY_LICENSES.md` is the file that ships inside the npm artifact to cover the third-party dependencies bundled into the distribution.

Editorial conclusion

Use Advanced Chat Components when you need a typed chat UI for a Vue 3 application or a framework-neutral page, and when you are ready to build the transport, realtime subscription and persistence layer yourself. Skip it if your application still runs on V2, since V3 is not a drop-in replacement and switching packages requires a migration. Do not adopt V3 if you need a stable release today: 3.0.0-rc.3 is a release candidate, and the public interface can still change. Before committing, read the cookbook's backend integration section, because the library emits send-message events but sends nothing on the wire.

Frequently asked questions

Official sources

1. advanced-chat/advanced-chat-components on GitHub
2. License: MIT
3. Project website
4. README
5. Releases