Getting started

imvu.js is a set of packages. Most applications only need @imvu/client; the others are its building blocks or work with IMVU's product files.

Package	Use it for
@imvu/client	The modeled API: users, the current account, wishlists, gifts, rooms and chat.
@imvu/bot	Chat bots: commands, permissions and rate limits across many rooms.
@imvu/verify	Proving someone owns an IMVU account (a code in their tagline).
@imvu/rest	Raw REST requests with IMVU authentication, when you want plain JSON.
@imvu/imq	The IMQ websocket service directly (realtime queues and mounts).
@imvu/xmlrpc	The classic client's XML-RPC gateway (e.g. current product revisions).
@imvu/chkn	Loading products: CFL/CHKN archives, index.xml, inherited assets.
@imvu/cal3d	The Cal3D model files inside products.

Requirements

• Node.js 22 or newer. The packages use web-standard APIs (fetch, WebSocket, TextDecoder, DecompressionStream) and have few or no dependencies.
• Browsers work for the file-format packages (@imvu/cal3d, @imvu/chkn). IMVU's API only allows requests from https://www.imvu.com, so calling it from a third-party web page needs a proxy, a browser extension, or a desktop shell such as Electron.

Install

npm install @imvu/client

Log in and make a request

import { Client } from '@imvu/client';

const client = new Client();
await client.login(process.env.IMVU_USERNAME!, process.env.IMVU_PASSWORD!);

const [user] = await client.users.search({ username: 'IMVU' });
console.log(user?.username, user?.id);

In Node, logging in stores the session cookies (in ./cookies.json by default; see the cookiePath and cookieStorage options of REST) and reuses them while they stay valid, so restarting your program does not log in again. IMVU rate-limits logins: keep one session and reuse it rather than logging in per run.

Examples

The repository's examples/ folder has runnable scripts. Here is the high-level client one:

/**
 * @imvu/client — the high-level modeled API (resource classes + managers)
 * layered on top of @imvu/rest.
 *
 *   node --env-file=.env examples/client-search.ts [username]
 */
import { Client } from '@imvu/client';

const username = process.env.IMVU_USERNAME;
const password = process.env.IMVU_PASSWORD ?? '';

if (!username) {
  console.error('Set IMVU_USERNAME (and IMVU_PASSWORD) — see examples/README.md');
  process.exit(1);
}

const client = new Client();
await client.login(username, password);
console.log(`Logged in as ${client.account.username}`);

const target = process.argv[2] ?? 'IMVU';
const [user] = await client.users.search({ username: target });

if (!user) {
  console.error(`No user found for "${target}"`);
  process.exit(1);
}

console.log(`Found ${user.username} (id ${user.id})`);

Next steps

• Learn the model. Core concepts covers resources, collections and paging, then Authentication, Realtime updates and Handling errors.
• Do something specific. The recipes cover users and profiles, your account, gifting, downloading products, Cal3D files and rendering with three.js.
• Look something up. The package pages describe each package, and the API reference lists every export.