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/nuxt-atproto/ (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>{{ session?.sub }}</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.