Getting Started

Quickstart

Get end-to-end encrypted chat working in your app in under 5 minutes.

Prerequisites

Node.js 18 or later

A React app (Next.js, Vite, CRA) or plain Node.js project

An Encra API key (free — see step 1)

1. Get an API key

After signing in, go to Dashboard → Create key. Copy the full JWT token when it appears — it's only shown once.

⚠ Save your key

The full token is only shown once at creation time. Copy it to your password manager or.env immediately.

2. Install

terminalbash

# React projects
npm install @encra/react

# Node.js, Svelte, Vue, vanilla JS
npm install @encra/client

# Low-level crypto primitives only
npm install @encra/core

# Or use the setup wizard (auto-detects your framework)
npx encra init

3. Add to your React app

Add your API key to your environment variables:

.env.localenv

NEXT_PUBLIC_ENCRA_API_KEY=your_api_key_here

Then use the hook in your component:

components/Chat.tsxtsx

import { useE2EChat } from '@encra/react'

export default function Chat({ currentUserId, recipientId }) {
  const { messages, isReady, sendMessage, error } = useE2EChat({
    apiKey: process.env.NEXT_PUBLIC_ENCRA_API_KEY!,
    userId: currentUserId,
    // serverUrl is optional — defaults to Encra managed server
  })

  if (error) return <p>Connection error: {error.message}</p>

  return (
    <div>
      <div className="messages">
        {messages.map((msg, i) => (
          <div key={i} className={msg.from === currentUserId ? 'sent' : 'received'}>
            <strong>{msg.from}</strong>: {msg.text}
          </div>
        ))}
      </div>

      <button
        disabled={!isReady}
        onClick={() => sendMessage(recipientId, 'Hello!')}
      >
        {isReady ? 'Send' : 'Connecting...'}
      </button>
    </div>
  )
}

💡 What happens under the hood

When the hook mounts, it generates an X25519 key pair, registers the public key with the Encra server, and opens a WebSocket connection. All of this happens automatically.

3b. Node.js / plain JS / other frameworks

For non-React projects — Node.js, Svelte, Vue, vanilla JS — use @encra/client. It has the same features as @encra/react but with an event-emitter API instead of hooks.

terminalbash

npm install @encra/client

chat.tstypescript

import { EncraClient } from '@encra/client'

const client = new EncraClient({
  apiKey: process.env.ENCRA_API_KEY!,
  userId: 'alice',
})

client.on('ready',   ()    => console.log('connected'))
client.on('message', (msg) => console.log(msg.from, msg.text))
client.on('error',   (err) => console.error(err))

await client.connect()

// Send an encrypted message
await client.sendMessage('bob', 'Hello Bob!')

// Clean up
client.disconnect()

💡 Full API

See the @encra/client reference for file encryption, form field encryption, and all events.

4. Test it

Open your app in two browser tabs. In tab 1, copy the user ID shown after connecting. In tab 2, paste it as the recipient and send a message. You should see the message arrive in tab 1 — and if you open DevTools → Network, you'll see the server only receives encrypted blobs.

💡 Try the live playground

Not ready to integrate yet? Try the encryption playground or the live chat demo in your dashboard.

Next steps

How it works

Deep dive into X25519 and Double Ratchet

@encra/react reference

Full hook API and options

@encra/core reference

All crypto primitives

Self-hosting

Run your own key server

Introduction

Installation