JavaScript Environment Setup

This guide helps you set up a modern JavaScript environment for PubNub development. It covers package managers, Node.js versions, TypeScript configuration, and build tool recommendations.

Node.js version

PubNub's JavaScript SDK requires Node.js 22 or later for server-side applications.

To check your Node.js version:

node --version

If you need to install or update Node.js:

• Direct download: nodejs.org
• Version manager (recommended): Use nvm (macOS/Linux) or nvm-windows to manage multiple Node.js versions

# Install Node.js using nvm
nvm install 22
nvm use 22

LTS versions

We recommend using the current LTS (Long Term Support) version of Node.js for production applications.

Package managers

You can install PubNub SDKs using any of the following package managers. Choose the one that fits your project or team preferences.

npm (default)

npm comes bundled with Node.js and is the most widely used package manager.

npm install pubnub

yarn

Yarn offers faster installs and a lockfile for reproducible builds.

yarn add pubnub

pnpm

pnpm is a fast, disk-space efficient package manager that uses hard links and symlinks.

pnpm add pubnub

bun

Bun is an all-in-one JavaScript runtime and package manager with fast install times.

bun add pubnub

Lockfiles

Each package manager creates its own lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb). Commit your lockfile to version control to ensure consistent installs across environments.

Comparison

Feature	npm	yarn	pnpm	bun
Bundled with Node.js	Yes	No	No	No
Install speed	Moderate	Fast	Very fast	Very fast
Disk space efficiency	Moderate	Moderate	Very efficient	Efficient
Workspaces support	Yes	Yes	Yes	Yes
Monorepo support	Basic	Good	Excellent	Good

TypeScript

The PubNub JavaScript SDK includes TypeScript type definitions. No additional @types package is required.

Setup

1. Install TypeScript as a dev dependency:

npm install --save-dev typescript

1. Create a tsconfig.json file:

npx tsc --init

1. Import PubNub with types:

import PubNub from 'pubnub';


const pubnub = new PubNub({
    publishKey: 'your-publish-key',
    subscribeKey: 'your-subscribe-key',
    userId: 'your-user-id'
});

Recommended TypeScript configuration

For PubNub projects, we recommend these tsconfig.json settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Build tools and frameworks

Vite (recommended for new projects)

Vite is a fast build tool with excellent developer experience.

# Create a new Vite project
npm create vite@latest my-pubnub-app


# With React
npm create vite@latest my-pubnub-app -- --template react


# With React and TypeScript
npm create vite@latest my-pubnub-app -- --template react-ts


# With Vue
npm create vite@latest my-pubnub-app -- --template vue


# With Vue and TypeScript
npm create vite@latest my-pubnub-app -- --template vue-ts

Next.js

Next.js is a React framework for production with server-side rendering and API routes.

npx create-next-app@latest my-pubnub-app

Remix

Remix is a full-stack React framework focused on web standards.

npx create-remix@latest my-pubnub-app

Angular

For Angular projects, use the Angular CLI:

npx @angular/cli new my-pubnub-app
cd my-pubnub-app
npm install pubnub

Browser without a bundler

For simple browser applications, you can load PubNub directly from the CDN:

<script src="https://cdn.pubnub.com/sdk/javascript/pubnub.13.0.3.js"></script>

Version pinning

When using the CDN, pin to a specific version (e.g., pubnub.13.0.3.js) rather than using latest to avoid unexpected breaking changes.

ES Modules vs CommonJS

The PubNub SDKs support both ES Modules (ESM) and CommonJS imports.

ES Modules

import PubNub from 'pubnub';

The Chat SDK (@pubnub/chat) has native ESM support. The core JavaScript SDK (pubnub) works with ESM through Node.js interop and modern bundlers like Vite, webpack, and esbuild.

CommonJS

const PubNub = require('pubnub');

Node.js and ESM

To use ES Modules in Node.js, either:

• Use .mjs file extension
• Add "type": "module" to your package.json
• Use a bundler like Vite or esbuild

React Native

For React Native projects:

# Using Expo (recommended for new projects)
npx create-expo-app my-pubnub-app
cd my-pubnub-app
npm install pubnub


# Using React Native CLI
npx react-native init my-pubnub-app
cd my-pubnub-app
npm install pubnub

URL polyfill required

As of SDK v12.0.0, react-native-url-polyfill is no longer bundled with the SDK. You must install it explicitly in your React Native project:

npm install react-native-url-polyfill

Once installed, the SDK applies the polyfill automatically. No additional import or setup step is required.