Mastodon Community Next

Next.js SDK for interacting with Mastodon APIs.
This package makes it simple to fetch timelines, post updates, and integrate Mastodon features directly into your Next.js apps.

📑 Table of Contents

• Installation
• Additional Peer Dependencies
• Quick Start
• Usage
• Context Options
• Features
• License

📦 Installation

Install the package via npm, yarn, or pnpm:

# npm
npm install mastodon-community-next

# yarn
yarn add mastodon-community-next

# pnpm
pnpm add mastodon-community-next

⚠️ Additional Peer Dependencies (Required)

These packages are required for the SDK to work properly. Install only the ones you need:

# Install React Query
npm install @tanstack/react-query@^5.84.1
# or
yarn add @tanstack/react-query@^5.84.1

# Install React Toastify
npm install react-toastify@^11.0.5
# or
yarn add react-toastify@^11.0.5

# Install Feather Icons React
npm install feather-icons-react@^0.9.0
# or
yarn add feather-icons-react@^0.9.0

🚀 Quick Start

Wrap your app with the provider:

import { MastodonCommunityProvider } from "mastodon-community-next";

export default function App() {
  return (
    <MastodonCommunityProvider data={{ apiBasePath: "/api" }}>
      <YourApp />
    </MastodonCommunityProvider>
  );
}

📌 Usage

Components

• CreatePost – UI for creating a new post
• EditPost – UI for editing an existing post
• TrendingHashtags – Displays trending hashtags
• TabSection – Tabbed layout container
• PostDetail – Detailed view of a single post
• Lists Components:
  • Trending
  • Following
  • Bookmarks
  • LikedPosts
  • MyPosts
  • PublicTimeline

Example – Display trending posts:

import { Trending } from "mastodon-community-next";

export default function Home() {
  return <Trending />;
}

Hooks

• useTrendingPosts – Fetch infinite trending posts
• useBookmarksPosts – Fetch infinite bookmarked posts
• useFollowingPosts – Fetch infinite posts from followed accounts
• useHashtagTimeline – Fetch posts by hashtag
• useLikedPosts – Fetch infinite liked posts
• useMyPosts – Fetch your own posts
• usePublicTimeline – Fetch public timeline posts

Example – Use infinite trending posts hook:

import { useTrendingPosts } from "mastodon-community-next";

export default function TrendingFeed() {
  const { data, fetchNextPage, hasNextPage } = useTrendingPosts();

  return (
    <div>
      {data?.pages.map(page =>
        page.posts.map(post => <div key={post.id}>{post.content}</div>)
      )}
      {hasNextPage && <button onClick={fetchNextPage}>Load more</button>}
    </div>
  );
}

⚙️ Context Options

The MastodonCommunityProvider accepts a data object with the following options:

• apiBasePath (string) – Base path for Mastodon API requests
• postDetailPath (string) – URL path for post details
• postEditPath (string) – URL path for editing posts
• userProfilePath (string) – URL path for user profiles
• usernameNotAvailableHandler (() => void) – Callback when username is unavailable
• themeMode ("light" | "dark") – Theme mode for the SDK
• token (string) – Optional authentication token
• mastodonId (string) – Optional Mastodon user ID
• avatar (string) – Optional avatar URL
• localization (object) – Custom localization values
• customClasses (CustomClasses) – Override default CSS class names
• colors (ThemeColors) – Custom light theme colors
• darkColors (ThemeColors) – Custom dark theme colors
• isUsernameAvailable (() => boolean) – Optional function to check username availability

Example – Customize provider with theme and classes:

import { MastodonCommunityProvider } from "mastodon-community-next";

const contextData = {
  apiBasePath: "/api",
  themeMode: "dark",
  customClasses: { createPostContainer: "my-create-post" },
  colors: { "--orange-orange-primary-100-light": "#ff6600" },
};

export default function App() {
  return (
    <MastodonCommunityProvider data={contextData}>
      <YourApp />
    </MastodonCommunityProvider>
  );
}

✨ Features

• Easy integration with Mastodon APIs
• Built for Next.js 14+
• Infinite scroll hooks for posts and timelines
• Prebuilt UI components for posts, lists, and hashtags
• Customizable theme and class names via context
• Notifications powered by react-toastify
• Feather icons support

📜 License

ISC © 2025 ActTrader