https://github.com/ryanhefner/use-bluesky
🦋 React hooks to interact with the Bluesky API
https://github.com/ryanhefner/use-bluesky
bluesky bluesky-api context-provider react react-hooks
Last synced: 5 days ago
JSON representation
🦋 React hooks to interact with the Bluesky API
- Host: GitHub
- URL: https://github.com/ryanhefner/use-bluesky
- Owner: ryanhefner
- License: mit
- Created: 2025-05-13T14:01:45.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-30T03:18:43.000Z (12 months ago)
- Last Synced: 2025-05-30T04:25:12.523Z (12 months ago)
- Topics: bluesky, bluesky-api, context-provider, react, react-hooks
- Language: TypeScript
- Homepage: https://www.pkgstats.com/pkg:use-bluesky
- Size: 21.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 🦋 use-bluesky
React hooks to interact with the Bluesky API.
[](https://www.pkgstats.com/pkg:use-bluesky)
[](LICENSE)
[](https://www.pkgstats.com/pkg:use-bluesky)
[](https://coveralls.io/github/ryanhefner/use-bluesky)
[](https://codecov.io/gh/ryanhefner/use-bluesky)
[](https://circleci.com/gh/ryanhefner/use-bluesky)
## Install
Via [npm](https://npmjs.com/package/use-bluesky)
```sh
npm install use-bluesky
```
Via [Yarn](https://yarn.pm/use-bluesky)
```sh
yarn add use-bluesky
```
## Requirements
This library requires the following peer dependencies to be installed in your project:
```sh
npm install @atproto/api@>=0.10 @atproto/oauth-client-node@>=0.2 @tanstack/react-query@>=5.0 react@>=16.8 react-dom@>=16.8
```
Or if you're using Yarn:
```sh
yarn add @atproto/api@>=0.10 @atproto/oauth-client-node@>=0.2 @tanstack/react-query@>=5.0 react@>=16.8 react-dom@>=16.8
```
## How to use
### Setup
#### App Router
First, wrap your app with the `BlueskyProvider` and configure it with your Bluesky credentials:
```tsx
// 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 (
{children}
)
}
```
Then, add the provider to your root layout:
```tsx
// app/layout.tsx
import { Providers } from './providers'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
{children}
)
}
```
#### Pages Router
For Next.js Pages Router, you can set up the providers in your `_app.tsx`:
```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 (
)
}
```
### Available Hooks
#### useProfile
Fetch a user's profile information:
```tsx
'use client'
import { useProfile } from 'use-bluesky'
export default function ProfilePage({ handle }: { handle: string }) {
const { data, isLoading, error } = useProfile({
actor: handle,
})
if (isLoading) return
Loading...
if (error) return Error loading profile
return (
{data.displayName}
{data.description}
)
}
```
#### useFollow
> _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 (`baseUrl` on `BlueskyProvider`) that applies the appropriate credentials to the request to the Bluesky API.
Follow or unfollow a user:
```tsx
'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 (
follow()} disabled={isPending}>
Follow
)
}
```
#### useFollowers
Get a user's followers:
```tsx
'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 (
{data?.pages.map((page, i) => (
{page.followers.map((follower) => (
{follower.displayName}
))}
))}
{hasNextPage && (
fetchNextPage()} disabled={isFetchingNextPage}>
Load More
)}
)
}
```
#### useSearchActors
Search for users:
```tsx
'use client'
import { useSearchActors } from 'use-bluesky'
export default function SearchPage() {
const [searchTerm, setSearchTerm] = useState('')
const { data, isLoading } = useSearchActors({
search: searchTerm,
limit: 20,
})
return (
setSearchTerm(e.target.value)}
placeholder="Search users..."
/>
{isLoading ? (
Loading...
) : (
{data?.actors.map((actor) => (
{actor.displayName}
))}
)}
)
}
```
### Additional Hooks
The library also provides these additional hooks:
- `useFollows`: Get users that a profile follows
- `useList`: Get a list of users
- `useStarterPack`: Get a starter pack
- `useActorStarterPacks`: Get starter packs for an actor
Each hook is fully typed and integrates with React Query for efficient data fetching and caching.
## License
[MIT](LICENSE) © [Ryan Hefner](https://www.ryanhefner.com)