Installation

This guide covers everything you need to install and configure the AT Protocol SDK in your development environment.

System requirements

Node.js

Version 18.7.0 or higherThe AT Protocol SDK requires Node.js 18.7.0+. Use nvm for easy version management.

Package manager

npm, yarn, or pnpmAny modern package manager works. The examples use npm, but commands are provided for all three.

The SDK is built with TypeScript and includes complete type definitions. While TypeScript is recommended, you can use the SDK with plain JavaScript.

Installing Node.js

If you don’t have Node.js installed, or need to upgrade:

Using nvm (recommended)
Direct download
Package managers

Install or update Node.js using nvm:

# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js 22 (latest LTS)
nvm install 22
nvm use 22

# Verify installation
node --version  # Should print v22.x.x

Download and install Node.js directly:

Visit nodejs.org
Download the LTS version (22.x or higher)
Run the installer
Verify installation:

node --version  # Should print v22.x.x or higher
npm --version   # Should print 10.x.x or higher

Install Node.js using your system’s package manager:

brew install node

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

sudo dnf install nodejs

choco install nodejs

Installing the SDK

Create or navigate to your project

If you’re starting a new project:

mkdir my-atproto-app
cd my-atproto-app
npm init -y

Or navigate to your existing project:

cd my-existing-project

Install @atproto/api

Install the main AT Protocol API client:

npm install @atproto/api

yarn add @atproto/api

pnpm add @atproto/api

This installs the @atproto/api package, which includes:

Agent and AtpAgent classes for API calls
CredentialSession for authentication
RichText for text processing
All TypeScript type definitions
Content moderation utilities

Verify installation

Create a test file to verify everything is working:

test.ts

import { Agent } from '@atproto/api'

console.log('AT Protocol SDK installed successfully!')
console.log('Agent class:', typeof Agent)

Run it:

npx ts-node test.ts

node test.js

You should see:

AT Protocol SDK installed successfully!
Agent class: function

Environment-specific setup

The AT Protocol SDK works in multiple JavaScript environments. Here’s how to set it up for each:

Node.js
Browser
React
Next.js

Node.js setup

Node.js (18.7.0+) has built-in support for everything the SDK needs:

import { Agent, CredentialSession } from '@atproto/api'

// Everything works out of the box in Node.js
const session = new CredentialSession(new URL('https://bsky.social'))
const agent = new Agent(session)

No polyfills or additional configuration needed!For TypeScript projects, add these to your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["ES2022"],
    "types": ["node"]
  }
}

Browser setup

The SDK works in modern browsers with native fetch support:

import { Agent, CredentialSession } from '@atproto/api'

// Works in all modern browsers
const session = new CredentialSession(new URL('https://bsky.social'))
const agent = new Agent(session)

Minimum browser requirements:

Chrome 90+
Firefox 88+
Safari 14.5+
Edge 90+

For older browsers, you may need polyfills:

npm install whatwg-fetch

// At the top of your entry point
import 'whatwg-fetch'
import { Agent, CredentialSession } from '@atproto/api'

Security note: When using the SDK in the browser, never expose app passwords or API keys in client-side code. Use OAuth authentication for browser-based applications.

React setup

Install the SDK in your React project:

npm install @atproto/api

Create a hook for session management:

hooks/useAgent.ts

import { useState, useEffect } from 'react'
import { Agent, CredentialSession } from '@atproto/api'

export function useAgent() {
  const [agent, setAgent] = useState<Agent | null>(null)

  useEffect(() => {
    // Initialize session from storage
    const session = new CredentialSession(
      new URL('https://bsky.social')
    )
    setAgent(new Agent(session))
  }, [])

  return agent
}

Use it in your components:

import { useAgent } from './hooks/useAgent'

function Timeline() {
  const agent = useAgent()
  const [posts, setPosts] = useState([])

  useEffect(() => {
    if (!agent) return
    agent.getTimeline({ limit: 20 })
      .then(res => setPosts(res.data.feed))
  }, [agent])

  // Render timeline...
}

Next.js setup

The SDK works in both Next.js App Router and Pages Router:

npm install @atproto/api

Server components (App Router):

app/timeline/page.tsx

import { Agent, CredentialSession } from '@atproto/api'

export default async function TimelinePage() {
  const session = new CredentialSession(
    new URL('https://bsky.social')
  )
  // Login handled securely on server
  const agent = new Agent(session)
  
  const timeline = await agent.getTimeline({ limit: 20 })

  return (
    <div>
      {timeline.data.feed.map(item => (
        <Post key={item.post.uri} post={item.post} />
      ))}
    </div>
  )
}

Client components:

components/CreatePost.tsx

'use client'

import { Agent } from '@atproto/api'
import { useState } from 'react'

export function CreatePost({ agent }: { agent: Agent }) {
  const [text, setText] = useState('')

  const handlePost = async () => {
    await agent.post({
      text,
      createdAt: new Date().toISOString()
    })
  }

  return (
    <form onSubmit={handlePost}>
      <textarea value={text} onChange={e => setText(e.target.value)} />
      <button type="submit">Post</button>
    </form>
  )
}

Additional packages

The AT Protocol SDK is split into multiple packages. Install additional packages as needed:

@atproto/oauth-client-* (OAuth authentication)

For production applications, use OAuth instead of app passwords:Browser applications:

npm install @atproto/oauth-client-browser

Node.js applications:

npm install @atproto/oauth-client-node

General/custom environments:

npm install @atproto/oauth-client

See the OAuth authentication guide for usage details.

@atproto/identity (DID and handle resolution)

For advanced identity operations:

npm install @atproto/identity

import { resolveHandle, resolveDid } from '@atproto/identity'

const did = await resolveHandle('alice.bsky.social')
const doc = await resolveDid(did)

@atproto/crypto (Cryptographic operations)

For signing and key management:

npm install @atproto/crypto

import { Secp256k1Keypair } from '@atproto/crypto'

const keypair = await Secp256k1Keypair.create()

@atproto/repo (Repository management)

For advanced repository operations:

npm install @atproto/repo

import { Repo } from '@atproto/repo'

// Low-level repository operations

@atproto/lexicon (Schema validation)

For working with Lexicon schemas:

npm install @atproto/lexicon

import { Lexicons } from '@atproto/lexicon'

const lexicons = new Lexicons(schemas)

TypeScript configuration

For the best TypeScript experience, configure your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["ES2022", "DOM"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "types": ["node"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

The SDK provides complete TypeScript types out of the box. Enable strict mode to catch potential errors early.

Custom fetch implementation

If you need to provide a custom fetch implementation (for logging, proxying, etc.):

import { Agent, CredentialSession } from '@atproto/api'

const customFetch: typeof fetch = async (input, init) => {
  console.log('Request:', input)
  const response = await fetch(input, init)
  console.log('Response:', response.status)
  return response
}

const session = new CredentialSession(
  new URL('https://bsky.social'),
  customFetch  // Pass custom fetch here
)

const agent = new Agent(session)

Verification

After installation, verify everything is working:

verify.ts

import { Agent, CredentialSession, RichText } from '@atproto/api'

async function verify() {
  console.log('✓ Imports successful')

  // Test basic functionality
  const rt = new RichText({ text: 'Hello world!' })
  console.log('✓ RichText works:', rt.text)

  // Test session creation (doesn't require authentication)
  const session = new CredentialSession(new URL('https://bsky.social'))
  const agent = new Agent(session)
  console.log('✓ Agent created successfully')

  console.log('\n✅ All checks passed! SDK is ready to use.')
}

verify().catch(console.error)

Run with:

npx ts-node verify.ts

Troubleshooting

Module not found errors

If you see “Cannot find module ‘@atproto/api’”:

Make sure you ran npm install
Check that @atproto/api is in your package.json dependencies

Delete node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

If using TypeScript, ensure moduleResolution is set to "node" in tsconfig.json

Node.js version errors

If you see errors about Node.js version:

Check your current version: node --version
Upgrade to Node.js 18.7.0 or higher
Use nvm to manage versions: nvm install 22 && nvm use 22
Add an .nvmrc file to your project:
22

Fetch is not defined

If you see “fetch is not defined” in older Node.js versions:

Upgrade to Node.js 18.7.0+ (has native fetch)
Or install a polyfill: npm install node-fetch

For environments without fetch, provide a custom fetch implementation:

import fetch from 'node-fetch'
import { CredentialSession } from '@atproto/api'

const session = new CredentialSession(
  new URL('https://bsky.social'),
  fetch as any
)

TypeScript errors

If you’re getting TypeScript errors:

Make sure you have TypeScript installed: npm install -D typescript
Check your tsconfig.json has correct settings (see above)
Try setting "skipLibCheck": true in tsconfig.json
Update your TypeScript version: npm install -D typescript@latest

ESM/CommonJS issues

If you have module system issues:For ESM (recommended):

Add "type": "module" to your package.json
Use .mjs extension or set "type": "module"
Use import statements

For CommonJS:

Use require() statements

You may need to use dynamic imports:

const { Agent } = await import('@atproto/api')

Next steps

Now that you have the SDK installed:

Quickstart guide

Make your first API call and create a post

Authentication

Learn about authentication options and session management

API reference

Explore the complete API documentation

OAuth setup

Set up OAuth for production applications

Need help? Join the AT Protocol discussion forum or check the GitHub repository.

Get Started

Core Concepts

Guides

System requirements

Node.js

Package manager

Installing Node.js

Installing the SDK

Environment-specific setup

Node.js setup

Browser setup

React setup

Next.js setup

Additional packages

TypeScript configuration

Custom fetch implementation

Verification

Troubleshooting

Next steps

Quickstart guide

Authentication

API reference

OAuth setup

​System requirements

Node.js

Package manager

​Installing Node.js

​Installing the SDK

​Environment-specific setup

​Node.js setup

​Browser setup

​React setup

​Next.js setup

​Additional packages

​TypeScript configuration

​Custom fetch implementation

​Verification

​Troubleshooting

​Next steps

Quickstart guide

Authentication

API reference

OAuth setup

System requirements

Installing Node.js

Installing the SDK

Environment-specific setup

Node.js setup

Browser setup

React setup

Next.js setup

Additional packages

TypeScript configuration

Custom fetch implementation

Verification

Troubleshooting

Next steps