React hooks to interact with the Bluesky API.
Via npm
npm install use-blueskyVia Yarn
yarn add use-blueskyThis library requires the following peer dependencies to be installed in your project:
npm install @atproto/api@>=0.10 @atproto/oauth-client-node@>=0.2 @tanstack/react-query@>=5.0 react@>=16.8 react-dom@>=16.8Or if you're using Yarn:
yarn add @atproto/api@>=0.10 @atproto/oauth-client-node@>=0.2 @tanstack/react-query@>=5.0 react@>=16.8 react-dom@>=16.8First, wrap your app with the BlueskyProvider and configure it with your Bluesky credentials:
// app/providers.tsx
'use client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { BlueskyProvider } from 'use-bluesky'
// Create a client
const queryClient = new QueryClient()
export function Providers({ children }: { children: React.ReactNode }) {
return (
<QueryClientProvider client={queryClient}>
<BlueskyProvider
baseUrl="https://public.api.bsky.app" // Optional: defaults to this URL
token="your-bluesky-token" // Optional: for authenticated requests
queryClient={queryClient} // Optional: pass your own QueryClient instance
>
{children}
</BlueskyProvider>
</QueryClintProvider>
)
}Then, add the provider to your root layout:
// app/layout.tsx
import { Providers } from './providers'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>
<Providers>{children}</Providers>
</body>
</html>
)
}For Next.js Pages Router, you can set up the providers in your _app.tsx:
// pages/_app.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import type { AppProps } from 'next/app'
import { BlueskyProvider } from 'use-bluesky'
// Create a client
const queryClient = new QueryClient()
export default function App({ Component, pageProps }: AppProps) {
return (
<QueryClientProvider client={queryClient}>
<BlueskyProvider
baseUrl="https://public.api.bsky.app" // Optional: defaults to this URL
queryClient={queryClient} // Optional: pass your own QueryClient instance
token="your-bluesky-token" // Optional: for authenticated requests
>
<Component {...pageProps} />
</BlueskyProvider>
</QueryClientProvider>
)
}Fetch a user's profile information:
'use client'
import { useProfile } from 'use-bluesky'
export default function ProfilePage({ handle }: { handle: string }) {
const { data, isLoading, error } = useProfile({
actor: handle,
})
if (isLoading) return <div>Loading...</div>
if (error) return <div>Error loading profile</div>
return (
<div>
<h1>{data.displayName}</h1>
<p>{data.description}</p>
</div>
)
}Note: In order to use this hook you need to have an authenticated Bluesky account that triggers the action. In order to support that, you need to proxy the request through your own API (
baseUrlonBlueskyProvider) that applies the appropriate credentials to the request to the Bluesky API.
Follow or unfollow a user:
'use client'
import { useFollow } from 'use-bluesky'
export default function FollowButton({
did,
followUri,
}: {
did: string
followUri: string
}) {
const { follow, unfollow, isPending } = useFollow({
did,
followUri,
onSuccess: () => {
// Handle successful follow/unfollow
},
})
return (
<button onClick={() => follow()} disabled={isPending}>
Follow
</button>
)
}Get a user's followers:
'use client'
import { useFollowers } from 'use-bluesky'
export default function FollowersList({ handle }: { handle: string }) {
const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useFollowers(
{
actor: handle,
limit: 50,
},
)
return (
<div>
{data?.pages.map((page, i) => (
<div key={i}>
{page.followers.map((follower) => (
<div key={follower.did}>{follower.displayName}</div>
))}
</div>
))}
{hasNextPage && (
<button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
Load More
</button>
)}
</div>
)
}Search for users:
'use client'
import { useSearchActors } from 'use-bluesky'
export default function SearchPage() {
const [searchTerm, setSearchTerm] = useState('')
const { data, isLoading } = useSearchActors({
search: searchTerm,
limit: 20,
})
return (
<div>
<input
type="text"
value={searchTerm}
onChange={(e) => setSearchTerm(e.target.value)}
placeholder="Search users..."
/>
{isLoading ? (
<div>Loading...</div>
) : (
<div>
{data?.actors.map((actor) => (
<div key={actor.did}>{actor.displayName}</div>
))}
</div>
)}
</div>
)
}The library also provides these additional hooks:
useFollows: Get users that a profile followsuseList: Get a list of usersuseStarterPack: Get a starter packuseActorStarterPacks: Get starter packs for an actor
Each hook is fully typed and integrates with React Query for efficient data fetching and caching.