### Alternative Setup with GNU Make
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/development/setup-dev-environment.md
If GNU Make is installed, these commands provide an alternative way to start the development server and watcher.
```bash
make serve_bg
make watch
```
--------------------------------
### Install Dependencies and Start Development Server
Source: https://github.com/conversejs/converse.js/blob/master/CONTRIBUTING.md
Run these commands to install project dependencies, start a background development server, and watch for file changes.
```bash
npm install
npm run serve &
npm run watch
```
--------------------------------
### Development Setup for @converse/log
Source: https://github.com/conversejs/converse.js/blob/master/src/log/README.md
Instructions for cloning the repository, navigating to the log directory, and installing dependencies for local development and testing.
```bash
git clone https://github.com/conversejs/converse.js.git
cd src/log
npm install
npm test
```
--------------------------------
### Install and Build Converse.js
Source: https://github.com/conversejs/converse.js/blob/master/README.md
Clone the repository, install dependencies, build the project, and start a local development server. Access the application via http://localhost:8008/dev.html.
```bash
git clone git@github.com:conversejs/converse.js.git
cd converse.js
git clone https://github.com/conversejs/media.git media; // To see images like sponsorship logos
npm install
npm run build
npm run serve -- -p 8008
```
--------------------------------
### Install Dependencies
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/documentation.md
Navigate to the docs directory and install project dependencies using npm.
```bash
cd docs
npm install
```
--------------------------------
### Install @converse/log
Source: https://github.com/conversejs/converse.js/blob/master/src/log/README.md
Install the package using npm. This is the first step before using the logging utility.
```bash
npm install @converse/log
```
--------------------------------
### Start Development Server with Live Reloading
Source: https://github.com/conversejs/converse.js/blob/master/CONTRIBUTING.md
Use this command to start a development server that provides live reloading when source files change.
```bash
make devserver
```
--------------------------------
### Run Development Server
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/documentation.md
Start a local development server with live-reloading to preview the documentation. Access it at http://localhost:4321.
```bash
npm run dev
```
--------------------------------
### Minimal Converse.js HTML Example
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/quickstart.md
A complete, minimal HTML file to get Converse.js running. Save this as `index.html` and open it in your browser to see the login screen.
```html
My Chat
```
--------------------------------
### Create Astro Project with Starlight Template
Source: https://github.com/conversejs/converse.js/blob/master/docs/README.md
Use this command to initialize a new Astro project with the Starlight template. Ensure you have Node.js installed.
```bash
npm create astro@latest -- --template starlight
```
--------------------------------
### Development Builds
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/development/builds.md
Commands for creating unminified development builds and starting the development server with live reloading.
```bash
npm run dev
```
```bash
npm run watch
```
```bash
npm run devserver
```
--------------------------------
### Development Server Command
Source: https://github.com/conversejs/converse.js/blob/master/AGENTS.md
Starts a development server with live reload functionality, typically on http://localhost:8080.
```bash
# Dev server with live reload
npm run devserver # Starts on http://localhost:8080
```
--------------------------------
### Initialize Converse with prebind authentication
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/configuration.md
This example shows how to initialize Converse using the 'prebind' authentication method, which attaches to an existing BOSH session. It requires `bosh_service_url`, `jid`, `prebind_url`, and `auto_login` to be set.
```javascript
converse.initialize({
bosh_service_url: 'https://bind.example.com',
jid: 'me@example.com',
authentication: 'prebind',
prebind_url: 'http://example.com/api/prebind',
auto_login: true,
allow_logout: false
});
```
--------------------------------
### Start Development Server with Live Reloading
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/development/setup-dev-environment.md
Use this command to start the RSPack development server, which includes live reloading for a more seamless development experience.
```bash
make devserver
```
```bash
npm run devserver
```
--------------------------------
### Alternative Command for Live Reloading
Source: https://github.com/conversejs/converse.js/blob/master/CONTRIBUTING.md
An alternative npm script to start the development server with live reloading capabilities.
```bash
npm run devserver
```
--------------------------------
### Initialize Converse.js with Full HTML Setup
Source: https://context7.com/conversejs/converse.js/llms.txt
This snippet shows the complete HTML structure required to load Converse.js and initialize it with a comprehensive set of configuration options. It includes CDN links for CSS and JS, and demonstrates settings for connection, authentication, display mode, behavior, message archiving, and localization.
```html
My Chat
```
--------------------------------
### Initialize Converse.js with Fullscreen View
Source: https://github.com/conversejs/converse.js/blob/master/fullscreen.html
Configure Converse.js for a fullscreen chat experience. Ensure JavaScript is enabled in the browser. This example sets a 'dracula' theme, uses 'login' authentication, and specifies the BOSH service URL for testing.
```javascript
converse.initialize({
theme: 'dracula',
authentication: 'login',
auto_away: 300,
auto_reconnect: true,
bosh_service_url: 'https://conversejs.org/http-bind/', // Please use this connection manager only for testing purposes
message_archiving: 'always',
view_mode: 'fullscreen',
show_background: true,
});
```
--------------------------------
### Anonymous Login for Converse.js
Source: https://context7.com/conversejs/converse.js/llms.txt
Configure Converse.js for anonymous login, allowing users to connect without an account. Ensure the XMPP server supports anonymous authentication. Combine with `auto_login: true` for immediate authentication on page load. This example also shows how to auto-join an embedded room for a read-only setup.
```javascript
converse.initialize({
bosh_service_url: 'https://conversejs.org/http-bind/',
authentication: 'anonymous',
jid: 'conversejs.org', // Server domain (not a full JID)
auto_login: true,
allow_logout: false,
// Auto-join an embedded room for a read-only or kiosk setup
auto_join_rooms: ['support@conference.example.com'],
view_mode: 'embedded',
singleton: true,
});
```
--------------------------------
### Initialize Converse.js with Options
Source: https://github.com/conversejs/converse.js/blob/master/dev.html
Demonstrates the initialization of Converse.js with a comprehensive set of configuration options. This includes language, theme, connection details, and plugin whitelisting. Ensure the BOSH service URL is appropriate for your environment.
```javascript
converse.initialize({
i18n: 'af',
theme: 'nordic',
dark_theme: 'dracula',
auto_away: 300,
loglevel: 'debug',
show_background: true,
message_archiving: 'always',
muc_show_logs_before_join: true,
notify_all_room_messages: ['discuss@conference.conversejs.org'],
fetch_url_headers: true,
whitelisted_plugins: ['converse-debug'],
bosh_service_url: 'https://conversejs.org/http-bind/',
// Please use this connection manager only for testing purposes
// view_mode: 'overlayed',
show_controlbox_by_default: true,
// websocket_url: 'wss://conversejs.org/xmpp-websocket',
// websocket_url: 'ws://chat.example.org:5380/xmpp-websocket',
// connection_options: {
// worker: '/dist/shared-connection-worker.js'
// }
});
```
--------------------------------
### Configure auto_join_private_chats
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/configuration.md
Automatically start private chats with specified JIDs upon login.
```javascript
[
'tom@example.org',
'dick@example.org',
'harry@example.org'
]
```
--------------------------------
### Basic Usage
Source: https://github.com/conversejs/converse.js/blob/master/src/log/README.md
Demonstrates how to import, configure, and use the logging methods provided by the utility.
```APIDOC
## Basic Usage
```javascript
import log from '@converse/log';
// Configure log level (default: 'info')
log.setLogLevel('debug');
// Log messages
log.debug('Detailed debug information');
log.info('System status update');
log.warn('Potential issue detected');
log.error('Operation failed');
log.fatal('Critical system failure');
// Pass multiple arguments like console
log.debug('User', username, 'logged in', { timestamp: Date.now() });
// Use %c for CSS styling in the browser console
log.debug('%c%s', 'color: darkgoldenrod', xmlStanza.outerHTML);
```
```
--------------------------------
### Build HTML Documentation
Source: https://github.com/conversejs/converse.js/blob/master/AGENTS.md
Use `make doc` to build the HTML documentation. For a development server with live reload, use `npm run docs:dev`. Production builds are created with `npm run docs:build`.
```bash
make doc # Build HTML documentation
npm run docs:dev # Start dev server with live reload
npm run docs:build # Build for production
```
--------------------------------
### Build Distribution Files
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/development/builds.md
Run this command to generate all CSS and JavaScript bundles for distribution. The output is placed in the `./dist` directory.
```bash
npm run build
```
--------------------------------
### Test Pattern with mock.initConverse
Source: https://github.com/conversejs/converse.js/blob/master/src/headless/AGENTS.md
Example of initializing Converse for testing using mock.initConverse. Use u.waitUntil() for asynchronous assertions.
```javascript
/* global converse */
import { mock, domain } from '../../tests/mock.js';
describe('My Plugin', function () {
it('does something',
mock.initConverse([], {}, async function (_converse) {
// _converse is the private instance
// Use u.waitUntil() for async assertions
const { u } = window.converse.env;
await u.waitUntil(() => _converse.state.chatboxes.length > 0);
})
);
});
```
--------------------------------
### Create CDN Build
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/development/builds.md
Run this command to create a build optimized for Content Delivery Network (CDN) deployment, featuring absolute paths.
```bash
npm run cdn
```
--------------------------------
### Restrict SASL Authentication Mechanisms
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/configuration.md
Pass a map of configuration options to the Strophe.Connection constructor to restrict supported SASL authentication mechanisms. This example restricts to SASLMD5.
```javascript
converse.initialize({
connection_options: {
'mechanisms': [
converse.env.Strophe.SASLMD5,
]
}
});
```
--------------------------------
### Nginx Reverse Proxy for Production WebSocket Setup
Source: https://context7.com/conversejs/converse.js/llms.txt
Configure Nginx to proxy WebSocket connections, enabling TLS termination and same-origin serving for production environments.
```nginx
server {
listen 80;
server_name converse.example.com;
location / {
proxy_pass http://localhost:8080;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
# WebSocket support
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
--------------------------------
### Production Build Commands
Source: https://github.com/conversejs/converse.js/blob/master/AGENTS.md
Creates minified production-ready bundles for various formats (ESM, CJS) and CSS. Use for deployment.
```bash
# Production build (minified)
npm run build # Full build: headless + ESM + CJS + CSS
npm run build:headless # Build headless package only
npm run build:esm # Build ESM bundle
npm run build:cjs # Build CommonJS bundle
npm run build:website-css # Build website CSS
npm run build:website-min-css # Build and minify website CSS
```
--------------------------------
### Defining a Lit Component in Converse.js
Source: https://github.com/conversejs/converse.js/blob/master/AGENTS.md
Provides an example of how to define a custom element using Lit, extending `CustomElement` and utilizing `properties` and `state` for component behavior and rendering.
```javascript
import { html } from 'lit';
import { CustomElement } from 'shared/components/element.js';
export default class MyComponent extends CustomElement {
static get properties() {
return {
model: { type: Object },
some_state: { state: true }, // Internal state
};
}
async initialize() {
await this.model.initialized;
// Listen to model changes to trigger re-render
this.listenTo(this.model, 'change', () => this.requestUpdate());
this.requestUpdate();
}
render() {
return html`
...
`;
}
}
customElements.define('my-component', MyComponent);
```
--------------------------------
### Initialize Converse.js with Credentials URL
Source: https://context7.com/conversejs/converse.js/llms.txt
Demonstrates how to initialize Converse.js and configure it to fetch login credentials from a specified URL, enabling auto-login.
```APIDOC
## Credentials URL — Auto-login with dynamic credentials
Fetches login credentials (JID + password or token) from a backend endpoint. Enables automatic login and re-authentication without storing credentials in the page source.
```javascript
converse.initialize({
websocket_url: 'wss://xmpp.example.com/ws',
authentication: 'login',
auto_login: true,
auto_reconnect: true,
// Server must return: {"jid": "alice@example.com/resource", "password": "token123"}
credentials_url: '/api/xmpp-credentials',
});
```
```
--------------------------------
### Get Chat Model(s)
Source: https://context7.com/conversejs/converse.js/llms.txt
Explains how to use `api.chats.get` to retrieve ChatBox models for one-on-one chats without necessarily opening them in the UI. It can fetch a specific chat or all open private chats.
```APIDOC
## `api.chats.get(jids)` — Get Chat Model(s)
Retrieves the ChatBox model(s) for one-on-one chats without opening them in the UI.
```javascript
converse.plugins.add('chat-getter-example', {
initialize() {
const { api } = this._converse;
api.listen.on('chatBoxesFetched', async () => {
// Get a specific chat model
const chat = await api.chats.get('alice@example.com');
if (chat) {
console.log('Chat type:', chat.get('type'));
console.log('Unread count:', chat.get('num_unread'));
}
// Get all open private chats
const allChats = await api.chats.get();
allChats.forEach(c => console.log(c.get('jid')));
});
}
});
```
```
--------------------------------
### Initialize Converse.js with BOSH or WebSocket URL
Source: https://github.com/conversejs/converse.js/blob/master/docs/src/content/docs/quickstart.md
Add this script before your closing `
` tag to initialize Converse.js. Replace the placeholder URL with your XMPP server's BOSH or WebSocket endpoint.
```html