better-auth-bsky

0.1.9 verified Fri May 01 auth: no javascript

A better-auth plugin (v0.1.9) adding ATProto/Bluesky OAuth 2.1 authentication via @atcute/oauth-node-client. Supports DPoP, PAR, PKCE and runs as a public or confidential client. Requires better-auth >=1.5.0, Node.js >=20 or Bun >=1.1.0. Ships TypeScript types and reduces install footprint by bundling valibot. Differentiates from app-password flows by implementing the OAuth 2.1 standard, with optional keypair-based confidential mode for longer sessions (180 days vs 14 days for public mode).

Common errors

error Cannot find module 'better-auth-bsky' or its corresponding type declarations. ↓

cause Missing or incorrect installation of better-auth-bsky or its peer dependencies.

fix

Run 'bun add better-auth-bsky better-auth @atcute/oauth-node-client' (or npm/pnpm equivalent).

error Uncaught TypeError: client.signIn.atproto is not a function ↓

cause Client-side atprotoClient() plugin not added to createAuthClient.

fix

Ensure atprotoClient() is passed in the plugins array: createAuthClient({ plugins: [atprotoClient()] }).

error SyntaxError: The requested module 'better-auth-bsky' does not provide an export named 'default' ↓

cause Attempting to default-import a named-only export.

fix

Use named import: import { atproto, generateAtprotoKeypair } from 'better-auth-bsky'.

Warnings

breaking Peer dependency better-auth must be >=1.5.0; plugin will not work with older versions. ↓

fix Update better-auth to >=1.5.0.

breaking Node.js version must be >=20.0.0 (uses modern features). ↓

fix Upgrade Node.js to >=20.

deprecated valibot was bundled as a dependency in v0.1.7; shipped inline to reduce install size. ↓

fix No code change needed. Upgrade to v0.1.7+ to benefit from smaller install.

deprecated The tsdown build tool dropped support for the 'external' option; v0.1.8+ uses 'deps.neverBundle' / 'deps.onlyBundle'. ↓

fix Update tsdown config if building from source.

gotcha Public client sessions are limited to 14 days; confidential sessions last 180 days. ↓

fix Provide a keyset via generateAtprotoKeypair() to enable confidential mode.

gotcha Loopback (localhost) is only supported in confidential mode during development. ↓

fix Ensure keyset is provided for local development with loopback.

Install

npm install better-auth-bsky

yarn add better-auth-bsky

pnpm add better-auth-bsky

Imports

atproto

wrong

import atproto from 'better-auth-bsky'

correct

import { atproto } from 'better-auth-bsky'

Named export, not default.

atprotoClient

wrong

import { atprotoClient } from 'better-auth-bsky'

correct

import { atprotoClient } from 'better-auth-bsky/client'

Client plugin is in a separate subpath.

generateAtprotoKeypair

wrong

const generateAtprotoKeypair = require('better-auth-bsky')

correct

import { generateAtprotoKeypair } from 'better-auth-bsky'

ESM-only; require is unsupported.

Quickstart

Initializes server plugin with minimal config and demonstrates client-side sign-in flow.

import { betterAuth } from 'better-auth';
import { atproto } from 'better-auth-bsky';
import { createAuthClient } from 'better-auth/client';
import { atprotoClient } from 'better-auth-bsky/client';

export const auth = betterAuth({
  plugins: [
    atproto({
      clientName: 'My App',
      clientUri: 'https://myapp.com',
      keyset: [] // omit for public client
    })
  ]
});

// Client-side sign-in
export const client = createAuthClient({
  plugins: [atprotoClient()]
});

async function signIn() {
  const { data, error } = await client.signIn.atproto({
    handle: 'user.bsky.social',
    callbackURL: '/dashboard'
  });
  if (!error) window.location.href = data.url;
}