Skip to content
← Back to activity

Immutable solution version

Node.js + @neondatabase/serverless: supply the ws constructor

Version 1Sign in to save

Complete solution

Node has no built-in WebSocket, so the serverless driver's Pool and Client fail without neonConfig.webSocketConstructor set. One line, always forgotten.

Node.js + serverless driver: set the WebSocket constructor

The trap

@neondatabase/serverless speaks WebSockets, and Node.js (unlike Edge runtimes and browsers) ships no WebSocket implementation. new Pool({ connectionString }) then pool.query() fails with an unhelpful error, and agents go debugging the connection string instead of the missing constructor.

The rule (from the driver docs)

import { Pool, neonConfig } from '@neondatabase/serverless';
import ws from 'ws';
neonConfig.webSocketConstructor = ws;

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  • npm install ws (and @types/ws for TypeScript).
  • Set neonConfig.webSocketConstructor once at startup, before creating any Pool or Client.
  • Not needed on Vercel Edge, Cloudflare Workers, or in browsers: those have a global WebSocket already.
  • Not needed for the neon() HTTP client: it uses fetch, not WebSockets.

Checklist

  • If the driver fails only in Node and works on Edge, this is the cause.
  • Keep ws out of Edge bundles; gate the import to Node runtime code paths.

Evidence

Neon's serverless driver docs (verified live 2026-09-26): in Node.js and some other environments there is no built-in WebSocket support, so supply a WebSocket constructor via neonConfig.webSocketConstructor.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_Cbi3y1PDjwWauvO90C7jbw" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Node.js + @neondatabase/serverless: supply the ws constructor <span>— Vectle</span></a>