← Back to Blog

Lightweight AI Chat Widget on npm: One-Line Install

Yes — you can add a lightweight AI chat widget to your app straight from npm, in about one line, with no iframe bloat and no five-day setup. Total Chat ships as an SDK-first package: run npm install @totalchat/sdk, drop in a single component, and you’ve got a screen-aware chat widget that already knows which page your user is sitting on. It stays light because it hooks into your app’s router and component tree directly, instead of loading a heavy third-party overlay on top of everything else you shipped.

That last part is the shift most people don’t realize is available yet. For years the only way to add chat was a script tag that injected a big, self-contained bundle — its own framework, its own styles, its own idea of your UI. A newer approach turns that inside out. The widget becomes part of your build, so it can read your router, your auth state, and the component the user is looking at. Once a chat widget can see the actual screen, everything about what it can do changes.

What “lightweight” really means here

Lightweight isn’t only about kilobytes, though that matters. A script-tag chat tool loads a whole second app into the browser and knows nothing about yours. An SDK-first widget imports only what it needs and reads context from the host app you already built. You’re not paying the bundle cost of a duplicate rendering layer, and you’re not shipping a second copy of React just to show a chat bubble.

It also means less to wire up. You don’t need a separate lead-capture tool, a separate product-tour builder, and a separate bug tracker glued together with webhooks. One install covers in-app support, user onboarding, and lead capture. Fewer moving parts, fewer dependencies to keep patched, a smaller surface area to break — that’s a real weight savings even before you count bytes.

If you want the deeper reasoning on package size and integration style, our best chat widget SDK 2026 comparison breaks down bundle weight across the common options.

The one-line install

Setup looks about like this: install the package, mount the component with your key, and you’re live.

npm install @totalchat/sdk

import { TotalChat } from '@totalchat/sdk';

<TotalChat appKey={process.env.TOTALCHAT_KEY} />

That’s the whole starting point. There’s no knowledge base to build by hand before it answers anything — the assistant does a codebase scan and reads your existing help center content, then starts responding. Most people struggle with chat tools because setup means weeks of writing articles and mapping workflows first; that’s why so many rollouts stall before launch. Here the walkthrough takes minutes, not a sprint. Our chat SDK one line install guide has the copy-paste version for React, Vue, and plain JS.

Screen-aware is the part that pays off

Because the widget is part of your app, it can answer questions about the exact page, modal, or form in front of the user — not a generic guess. Ask “how do I export this report?” and it already knows you’re on the reports page, so the answer fits what you’re actually looking at instead of reciting the manual.

It can also run the steps for the user. The assistant clicks buttons, moves between pages, and puts a marker on the field you’re stuck on while you watch — an auto-navigation walkthrough instead of a wall of instructions. That’s the difference between “here are nine steps” and “watch, I’ll do it with you.” For onboarding, it’s the closest thing to sitting a new user next to someone who knows the product.

When the assistant can’t finish something, escalation tiers decide the hand-off, so a person gets pulled in at the right moment instead of the chat looping until the user gives up. And when something’s actually broken, the bug goes to your developers with full context attached: the page, the user’s actions, the console errors. No more “it doesn’t work” tickets that lose every useful detail by the time a developer reads them.

More than support, from the same package

The same widget works before login, too. On your marketing site it does lead capture and visitor enrichment — digital fingerprinting plus UTM attribution — so a prospect who chats at 2 a.m. still turns into a qualified lead with a name attached. Enrichment runs on IP de-identification and email matching built in, so you’re not bolting on a third-party data vendor to figure out who showed up. After login the same component switches to full-power in-app support. One tool, two modes, no second integration.

The knowledge base writes itself over time. When a real conversation surfaces a gap, the assistant drafts a help article from it and sends it to you for approval — a help center that keeps up with the product instead of rotting in a wiki nobody opens. You could keep hand-editing docs forever, or let the questions people actually ask write them for you.

Why not just use the heavy option?

If you’re tired of billing shock, here’s the honest pitch. Intercom’s Product Tours are pre-scripted and locked behind an $85-per-seat Advanced plan, and its per-resolution billing turns a busy month into an overpriced surprise. Zendesk bolts a bot onto a ticket-first system and charges per agent. Enterprise-only tools like Ada start north of $30k a year with pricing nobody will quote you up front. Flat, predictable pricing — no per-seat, no per-resolution math — is a big reason teams switch away from those.

You can read the full setup and API reference in the docs before you commit a single line to your build.

Frequently Asked Questions

Is a screen-aware chat widget heavier than a normal script-tag chatbot?

Usually the opposite. A script-tag chatbot loads a full second application — its own framework and styles — into every page. The SDK imports only what it needs and reads context from the app you already built, so you skip the duplicate rendering layer. In practice that means a smaller footprint and fewer dependencies to keep patched, not more of them to manage.

Do I need to build a knowledge base before it works?

No. The assistant does a codebase scan and reads whatever help content you already have, then starts answering right away. As real conversations come in, it drafts new help articles from the gaps and sends them to you for approval. So your knowledge base grows out of actual questions instead of a guessing session held before launch day.

Which frameworks does the npm package support?

The SDK is built for modern JavaScript apps — React, Vue, and plain JS — with deep access to your router, auth state, and component tree. That host-app access is exactly what makes screen awareness and auto-navigation walkthroughs possible in the first place. For a framework-by-framework rundown, the JavaScript chat widget npm package post covers each install path in detail.

How is pricing structured?

Flat and predictable — no per-seat charges and no per-resolution charges. That’s a deliberate answer to the billing shock teams get from per-resolution tools, where one busy support month becomes a bill you never planned for. You get in-app support, lead capture, and the self-writing knowledge base in a single package instead of paying for three separate tools.

---