Version: 0.4.0 Release Date: January 30, 2026

Good News: nChat v0.4.0 has NO BREAKING CHANGES. This release is fully backward compatible with v0.3.0.

All new features are:

• ✅ Additive only (no removals)
• ✅ Opt-in (disabled by default)
• ✅ Backward compatible (existing functionality unchanged)
• ✅ Zero downtime (can upgrade without stopping services)

All changes are additive:

• ✅ 8 new tables added (no tables removed)
• ✅ 2 tables modified with new columns (existing columns unchanged)
• ✅ All existing data preserved
• ✅ No data migrations required
• ✅ Existing queries continue to work

Before v0.4.0:

SELECT id, content, user_id, channel_id
FROM nchat_messages
WHERE channel_id = 'abc123';

After v0.4.0:

-- Same query still works
SELECT id, content, user_id, channel_id
FROM nchat_messages
WHERE channel_id = 'abc123';

-- New columns are optional
SELECT id, content, user_id, channel_id, is_encrypted, encrypted_payload
FROM nchat_messages
WHERE channel_id = 'abc123';

No existing endpoints removed or modified:

• ✅ All v0.3.0 endpoints continue to work
• ✅ GraphQL queries unchanged
• ✅ REST API endpoints unchanged
• ✅ WebSocket events unchanged

New endpoints added (opt-in):

• /api/e2ee/initialize - E2EE setup
• /api/e2ee/recover - E2EE recovery
• /api/e2ee/safety-number - Safety number generation
• /api/e2ee/keys/replenish - Prekey replenishment

All existing variables continue to work:

• ✅ No variables removed
• ✅ No variables renamed
• ✅ No default behavior changed

New variables are optional:

# These are NEW and OPTIONAL (not required)
NEXT_PUBLIC_FEATURE_E2EE=false  # Default: false (disabled)
NEXT_PUBLIC_FEATURE_VIDEO_CALLS_HD=false  # Default: false
NEXT_PUBLIC_MEDIA_SERVER_URL=http://localhost:3100  # Only needed if using video calls

Existing variables unchanged:

# These all continue to work exactly as before
NEXT_PUBLIC_GRAPHQL_URL=http://api.localhost/v1/graphql
NEXT_PUBLIC_AUTH_URL=http://auth.localhost/v1/auth
NEXT_PUBLIC_USE_DEV_AUTH=true

AppConfig is backward compatible:

• ✅ All existing config fields work as before
• ✅ New fields are optional with sensible defaults
• ✅ No validation changes to existing fields

Before v0.4.0:

interface AppConfig {
  features: {
    publicChannels: boolean
    privateChannels: boolean
    directMessages: boolean
    // ... other v0.3.0 features
  }
}

After v0.4.0:

interface AppConfig {
  features: {
    // All v0.3.0 features still here
    publicChannels: boolean
    privateChannels: boolean
    directMessages: boolean

    // New optional features (default: false)
    endToEndEncryption?: boolean
    videoCallsHD?: boolean
  }

  // New optional encryption config
  encryption?: {
    enabled: boolean
    // ... other E2EE settings
  }
}

All existing components work unchanged:

• ✅ <MessageList /> - works as before
• ✅ <MessageInput /> - works as before
• ✅ <ChannelList /> - works as before
• ✅ No prop changes to existing components
• ✅ No component removals

New components are separate:

• <E2EESetup /> - New, opt-in component
• <E2EEStatus /> - New, opt-in component
• <VideoCallModal /> - New, opt-in component

No type changes to existing interfaces:

• ✅ All v0.3.0 types unchanged
• ✅ New types are separate/optional
• ✅ No interface property removals

Example - Message type:

// Before v0.4.0
interface Message {
  id: string
  content: string
  userId: string
  channelId: string
  createdAt: string
}

// After v0.4.0 - SAME, with optional new fields
interface Message {
  id: string
  content: string
  userId: string
  channelId: string
  createdAt: string

  // New optional fields
  isEncrypted?: boolean
  encryptedPayload?: Uint8Array
  senderDeviceId?: string
}

Nothing deprecated in v0.4.0.

No features, APIs, or configurations are marked for deprecation.

When you upgrade to v0.4.0 without enabling new features, the application behaves identically to v0.3.0:

To get new features, you must explicitly enable them.

Because there are no breaking changes, you can upgrade with zero downtime:

# 1. Pull new code (application keeps running)
git pull origin main

# 2. Install dependencies (application keeps running)
pnpm install

# 3. Run database migrations (additive only, no locks)
cd .backend && nself db migrate up

# 4. Restart application (quick restart, no configuration changes needed)
pm2 restart nchat-frontend

No configuration changes required. Application works immediately.

No type errors introduced:

pnpm type-check
# ✅ 0 errors (same as v0.3.0)

All existing tests pass:

pnpm test
# ✅ All v0.3.0 tests pass unchanged

No linting errors:

pnpm lint
# ✅ 0 errors (same as v0.3.0)

If you just want security patches and improvements:

# 1. Backup database
cd .backend && docker exec -t nself-postgres pg_dump -U postgres nchat > backup.sql

# 2. Update code
git pull origin main

# 3. Install dependencies
pnpm install

# 4. Run migrations
cd .backend && nself db migrate up

# 5. Restart
pnpm build && pm2 restart nchat-frontend

That's it. No configuration changes needed.

If you want E2EE and video calling:

# After upgrade, add to .env.local:
NEXT_PUBLIC_FEATURE_E2EE=true
NEXT_PUBLIC_FEATURE_VIDEO_CALLS_HD=true
NEXT_PUBLIC_MEDIA_SERVER_URL=http://localhost:3100

# Setup media server (for video calls)
cd .backend
./scripts/setup-media-server.sh

# Restart with new config
pnpm dev

There are no known compatibility issues with:

• ✅ v0.3.0 databases
• ✅ v0.3.0 configurations
• ✅ v0.3.0 client applications
• ✅ v0.3.0 API consumers
• ✅ v0.3.0 deployments (Docker, K8s, etc.)

• ✅ Supported - v0.3.0 will receive critical security patches
• ✅ Upgrade Recommended - v0.4.0 includes security improvements
• ⏰ End of Life - June 30, 2026 (6 months)

Recommended: Upgrade within 30 days Required: Upgrade before June 30, 2026

A: No. All existing data (messages, users, channels) remains unchanged and fully compatible.

A: No. Client applications built for v0.3.0 will continue to work with v0.4.0 servers.

A: No. All v0.3.0 environment variables work unchanged. New variables are optional.

A: No. Deployment scripts for v0.3.0 work unchanged for v0.4.0.

A: Yes. Rollback is fully supported. See Upgrade Guide.

A: No. All v0.3.0 integrations continue to work unchanged.

A: No (unless you enable new features). The UI is identical for disabled features.

A: Just don't enable them. The features are opt-in and disabled by default.

• ✅ Zero breaking changes
• ✅ Fully backward compatible
• ✅ Additive only

• ⚠️ 1 breaking change: Environment variable rename (NEXT_PUBLIC_API_URL → NEXT_PUBLIC_GRAPHQL_URL)
• ⚠️ Database migration required (additive)

• ⚠️ 2 breaking changes: Node.js 20+ required, pnpm 9+ required
• ⚠️ Configuration format changed

Conclusion: v0.4.0 is the smoothest upgrade yet.

nChat v0.4.0 has NO breaking changes.

This is a drop-in replacement for v0.3.0 with:

• ✅ Full backward compatibility
• ✅ Zero configuration changes required
• ✅ All existing functionality preserved
• ✅ New features are opt-in only
• ✅ Zero downtime upgrade supported

Recommendation: Upgrade with confidence. No breaking changes to worry about.

• v0.4.0 Release Notes
• v0.4.0 Upgrade Guide
• v0.4.0 Migration Guide
• E2EE Documentation
• Video Calling Documentation

Questions about breaking changes or upgrade compatibility?

• GitHub Issues: github.com/nself-org/nchat/issues
• Discord: discord.gg/nself
• Email: [email protected]

Summary: Upgrade to v0.4.0 worry-free. There are no breaking changes. 🎉