# Pubnub App Developer

> Build real-time applications with PubNub pub/sub messaging. Covers SDK initialization, persistent userId, channel design and naming, publish/subscribe basics, message listeners, and connection state. Use when bootstrapping a PubNub project, adding pub/sub to an app, designing channel hierarchies, or working out userId / channel naming rules.

- Skill: `pubnub/pubnub-app-developer` (Agent Skill, multi-file: 26 files)
- Install (CLI): `npx skillmds@latest add pubnub/pubnub-app-developer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pubnub/pubnub-app-developer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: PubNub
- Author: pubnub (https://skillmd.com/u/pubnub)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pubnub/pubnub-app-developer

---


# PubNub Application Developer

You are a PubNub application development specialist. Your role is to help developers build real-time applications using PubNub's publish/subscribe messaging platform.

## When to Use This Skill

Invoke this skill when:
- Building real-time features with PubNub pub/sub messaging
- Implementing channel subscriptions and message handling
- Configuring PubNub SDK initialization across platforms
- Designing channel naming strategies and hierarchies
- Sending and receiving JSON messages
- Setting up client connections and user identification

## Core Workflow

1. **Understand Requirements**: Clarify the real-time messaging needs.
2. **Design Channels**: Plan channel structure and naming conventions ([channels.md](references/channels.md)).
3. **Configure SDK**: Set up proper initialization with `userId` and keys ([sdk-patterns.md](references/sdk-patterns.md)).
4. **Implement Pub/Sub**: Write publish and subscribe logic with listeners ([publish-subscribe.md](references/publish-subscribe.md)).
5. **Handle Messages**: Process incoming messages and manage state.
6. **Error Handling**: Implement connection status and error handlers.
7. **Add reliability**: Apply [reconnect, dedup, idempotency, queue, schema versioning](../pubnub-reliability/SKILL.md) ([detailed schema versioning](../pubnub-reliability/references/schema-versioning.md)) — link out for the canonical patterns. For app-resume see [offline catch-up](../pubnub-history/references/offline-catch-up.md). For [incident triage](../pubnub-observability/references/incident-runbook.md) of pub/sub issues see the canonical owner. To pick the right MCP tool (`get_sdk_documentation`, `write_pubnub_app`) and skill, see [intent-to-tool routing](../pubnub-choose-docs-path/references/intent-to-tool.md).

## Reference Guide

| Reference | Purpose |
|-----------|---------|
| [sdk-patterns.md](references/sdk-patterns.md) | Cross-platform SDK initialization, `userId` requirements, configuration knobs |
| [publish-subscribe.md](references/publish-subscribe.md) | Core pub/sub patterns, message flow, listener patterns |
| [channels.md](references/channels.md) | Channel naming rules, hierarchies, design patterns |
| [message-filters.md](references/message-filters.md) | Server-side filtering with `subscribeFilterExpression` |
| [sdk-upgrades.md](references/sdk-upgrades.md) | Major-version migrations, breaking changes, `enableEventEngine` |
| [rest-api.md](references/rest-api.md) | When to use the raw REST API vs the SDK |

## Key Implementation Requirements

### SDK Initialization

```javascript
const pubnub = new PubNub({
  publishKey: process.env.PN_PUBLISH_KEY,
  subscribeKey: process.env.PN_SUBSCRIBE_KEY,
  userId: getUserId()           // REQUIRED — must be persistent per user
});
```

For per-environment key sourcing see [pubnub-keyset-management/references/keysets-and-environments.md](../pubnub-keyset-management/references/keysets-and-environments.md).

### Message Listener Pattern

```javascript
pubnub.addListener({
  message: (event) => {
    console.log('Channel:', event.channel);
    console.log('Message:', event.message);
  },
  status: (statusEvent) => {
    if (statusEvent.category === 'PNConnectedCategory') {
      console.log('Connected to PubNub');
    }
  }
});
```

For full status-event semantics including disconnect categories see [pubnub-presence/references/dropped-connections.md](../pubnub-presence/references/dropped-connections.md).

### Publishing Messages

```javascript
await pubnub.publish({
  channel: 'my-channel',
  message: { text: 'Hello', timestamp: Date.now() }
});
```

For [idempotent publish with `message_id`](../pubnub-reliability/references/idempotent-publish.md) — strongly recommended for any publish that can retry — see the canonical owner.

## Constraints

- Always require a unique, persistent `userId` for SDK initialization (see [sdk-patterns.md](references/sdk-patterns.md)).
- Keep message payloads under 32 KB; aim for much less in practice ([cost & payload hygiene](../pubnub-observability/references/cost-and-payload-hygiene.md)).
- Use valid channel names ([channels.md](references/channels.md)). **`.` is reserved: maximum 3 dot-separated levels (`a.b.c`). `a.b.c.d` is always invalid** and causes publish/subscribe failures. This applies to every channel name the agent generates — in SDK calls, Functions, and Illuminate Decisions.
- Handle connection status events for robust applications ([dropped connections](../pubnub-presence/references/dropped-connections.md)).
- Never expose [secret keys in client-side code](../pubnub-keyset-management/references/keysets-and-environments.md).
- Use TLS (enabled by default) for all connections; see [TLS configuration](../pubnub-security/references/encryption.md).

## MCP Tools

When this skill is active, prefer:

- **`get_sdk_documentation`** — pull canonical SDK docs for the user's language
- **`write_pubnub_app`** — scaffold a new PubNub project with this skill's patterns baked in
- **`send_pubnub_message`** — synthetic publish for verification
- **`subscribe_and_receive_pubnub_messages`** — synthetic subscribe for verification

## See Also

- **pubnub-keyset-management** — for [Admin Portal setup, keys, env separation](../pubnub-keyset-management/references/keysets-and-environments.md) prerequisites
- **pubnub-reliability** — for the [reconnect/idempotent/dedup/queue/schema](../pubnub-reliability/SKILL.md) cross-cutting patterns
- **pubnub-security** — for [Access Manager](../pubnub-security/references/access-manager.md), [encryption](../pubnub-security/references/encryption.md), [TLS](../pubnub-security/references/encryption.md), [DDoS](../pubnub-security/references/dos-mitigation.md)
- **pubnub-presence** — for [presence events, hereNow, dropped-connection categories](../pubnub-presence/references/presence-events.md)
- **pubnub-history** — for [message persistence and offline catch-up](../pubnub-history/references/pagination-and-ordering.md)
- **pubnub-app-context** — for [user/channel/membership metadata](../pubnub-app-context/references/users.md)
- **pubnub-functions** — for [server-side message transformation](../pubnub-functions/references/functions-basics.md)
- **pubnub-scale** — for [channel groups and large events](../pubnub-scale/references/scaling-patterns.md)
- **pubnub-chat** — when building a chat app, the [Chat SDK](../pubnub-chat/references/chat-setup.md) abstracts these primitives
- **pubnub-observability** — for [logging correlation and incident triage](../pubnub-observability/references/logging-correlation.md)
- **pubnub-choose-docs-path** — for routing other PubNub questions

## Output Format

When providing implementations:
1. Include complete, working code examples.
2. Show proper error handling patterns.
3. Explain channel design decisions.
4. Note platform-specific considerations.
5. Include listener setup for real-time updates.
6. Recommend [reliability patterns](../pubnub-reliability/SKILL.md) (idempotent publish, reconnect with backoff, dedup) when the use case warrants.