nuxt-atproto

OAuth login and session management for Bluesky and AT Protocol in Nuxt.

Documentation

Documentation — getting started, guides, and API reference.

Run the docs site locally:

cd docs && pnpm install && pnpm dev

Open http://127.0.0.1:3456/ (use 127.0.0.1, not localhost, for the OAuth demo).

Features

• AT Protocol OAuth in the browser (@atproto/oauth-client-browser)
• Composables for session, auth, and cached @atproto/api agents
• Lifecycle hooks: atproto:sessionCreated, atproto:sessionRestored, atproto:sessionDeleted
• Typed $atproto plugin (client, session, status)
• Optional generation of public/client-metadata.json from module config

Quick start

pnpm add nuxt-atproto

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-atproto'],
  atproto: {
    oauth: {
      clientMetadata: {
        local: {
          client_id: 'https://your-app.example/client-metadata.json',
          client_name: 'My App',
          client_uri: 'https://your-app.example',
          redirect_uris: ['https://your-app.example'],
          // ... see docs for full metadata
        },
      },
    },
  },
})

<script setup lang="ts">
const { isLogged, session } = useAtprotoSession()
const { signIn, signInWithHandle, signOut } = useAtprotoAuth()
</script>

<template>
  <ClientOnly>
    <button v-if="!isLogged" type="button" @click="signIn()">Sign in</button>
    <template v-else>
      <p></p>
      <button type="button" @click="signOut()">Sign out</button>
    </template>
  </ClientOnly>
</template>

const agent = useAtprotoAgent('authenticated')
await agent.getTimeline()

Client-only OAuth. Wrap login UI in <ClientOnly> or disable SSR on auth routes. See the introduction in the docs.

Composables

Composable	Purpose
useAtprotoSession()	session, isLogged, status
useAtprotoAuth()	signIn, signInWithHandle, signOut, restore
useAtprotoAgent(scope)	Cached Agent / AtpAgent (authenticated, public, or custom URL)

useAtproto() and useAgent() are deprecated — see Migration.

License

Released under the MIT License.

This site is open source. Improve this page.