The Node SDK

Install the Node SDK to run the widget from an Express or Next.js app.

Node

import { configure, vroxyMiddleware } from "@vroxy/node";

configure({ apiKey: process.env.VROXY_API_KEY });
app.use(vroxyMiddleware());

VROXY_API_KEY, VROXY_ENDPOINT and VROXY_IDENTITY_SECRET are read from the environment automatically — configure() is only needed for overrides and callbacks.

Identity resolution. Reads req.user (Passport and friends): external_id from user.id, email from user.email, name from full_name → name → first_name + last_name, role from user.role → user.roles[0].

configure({
  identify: ({ req }) => {
    const user = req.user;
    if (!user) return null;
    return {
      external_id: String(user.id),
      email: user.email,
      name: user.displayName,
      role: user.isAdmin ? "admin" : "basic",
    };
  },
});

Configuration: apiKey, endpoint, enabled, autoInject, identify, excludePaths, cspNonce, adminRoles (default ["admin", "owner"]), identitySecret, reportErrors, errorIgnore — same meanings as the Ruby table above.

Manual placement: vroxySnippet(identity) returns the snippet HTML for an explicit identity (null for anonymous, or no arguments to run the configured resolver). Using it during a request suppresses the middleware for that response.

Next.js. Body-rewriting middleware doesn’t fit Next, so use the component:

import { VroxyScript } from "@vroxy/node/next";

<body>
  {children}
  <VroxyScript identify={await identityForCurrentUser()} />
</body>

Render it server-side only — in a server component or _document. The identity secret must never be bundled for the client, so don’t mount it inside a "use client" tree.