Building a Custom Sharetribe Flex Marketplace with Next.js

Sharetribe Flex is one of the most powerful marketplace platforms available today. Its headless API-first architecture means you're not locked into a default template — you can build exactly the frontend your business needs while relying on Sharetribe's proven transaction engine, listing management, and search infrastructure under the hood.

Why Go Headless with Sharetribe Flex?

The default Sharetribe Web Template (FTW) is a solid starting point, but most production marketplaces outgrow it quickly. Custom UX flows, advanced search, SSR for SEO, and brand-specific design all become bottlenecks when working within the template's constraints. Decoupling your frontend gives you complete control over performance, UX, and technical architecture — and Next.js is the natural choice for a React-based marketplace frontend.

Project Structure

A production Sharetribe + Next.js project separates concerns clearly. The SDK is initialised in a shared server-side module, auth tokens live in HTTP-only cookies managed by Route Handlers, and all Sharetribe API calls happen in React Server Components — never in client components where tokens would be exposed.

app/
  (marketplace)/
    listings/
      page.js            ← SSR listing search
      [id]/page.js       ← SSR listing detail
    transactions/
      [id]/page.js
  api/
    auth/
      login/route.js
      logout/route.js
lib/
  sharetribe.js          ← SDK singleton
  auth.js                ← cookie helpers

Setting Up the Sharetribe Flex SDK

The core of the integration is the Sharetribe Flex JavaScript SDK. Install it in your Next.js project and initialise it with your client ID. For server-side requests, pass the user's auth token directly — the SDK handles token refresh automatically when the access token expires.

// lib/sharetribe.js
import { createInstance } from 'sharetribe-flex-sdk';

export function getSdk(token) {
  return createInstance({
    clientId: process.env.SHARETRIBE_CLIENT_ID,
    tokenStore: token
      ? { getToken: () => token }
      : undefined,
  });
}

Server-Side Rendering for Listing Pages

Listing pages are your most critical SEO surface. In Next.js App Router, async Server Components fetch listing data at request time — meaning every listing page is fully rendered HTML when Googlebot arrives. The listing title, description, price, and location are all in the initial HTML response. For a marketplace with thousands of listings, this is the difference between ranking on Google and being invisible to search engines.

// app/(marketplace)/listings/[id]/page.js
import { getSdk } from '@/lib/sharetribe';

export async function generateMetadata({ params }) {
  const sdk = getSdk();
  const { data } = await sdk.listings.show({ id: params.id });
  return {
    title: data.data.attributes.title,
    description: data.data.attributes.description,
  };
}

export default async function ListingPage({ params }) {
  const sdk = getSdk();
  const { data } = await sdk.listings.show({
    id: params.id,
    include: ['author', 'images'],
  });
  return <ListingDetail listing={data.data} included={data.included} />;
}

Authentication Flow

Authentication in a custom Sharetribe frontend uses the SDK's built-in auth methods. On login, call sdk.login() with email and password — this returns an access token and refresh token. Store these in HTTP-only cookies from a Next.js Route Handler, never in localStorage or client state. On subsequent requests, read the cookie server-side and pass the token to getSdk().

// app/api/auth/login/route.js
import { getSdk } from '@/lib/sharetribe';
import { cookies } from 'next/headers';

export async function POST(req) {
  const { email, password } = await req.json();
  const sdk = getSdk();
  const response = await sdk.login({ username: email, password });
  const cookieStore = await cookies();
  cookieStore.set('st_token', JSON.stringify(response.data), {
    httpOnly: true,
    secure: true,
    sameSite: 'lax',
    maxAge: 60 * 60 * 24 * 30,
  });
  return Response.json({ ok: true });
}

Stripe Connect for Marketplace Payments

Sharetribe Flex handles the transaction state machine but payments run through Stripe Connect. Each seller needs a connected Stripe account. The onboarding flow uses Stripe's hosted Connect OAuth — redirect the seller to Stripe, they authorise, and Stripe returns an authorisation code you exchange for an account ID via your backend. Store this on the Sharetribe user's extended data so the transaction process can reference it during payment.

Customising the Transaction Process

The Sharetribe transaction process is one of the platform's most powerful features. You define a state machine in the Sharetribe Console — states like enquiry, pending-payment, accepted, delivered, reviewed — and configure which transitions are customer-facing versus privileged (server-only). A privileged transition calls your backend before executing, letting you run custom business logic: dynamic pricing, availability checks, fraud detection, or external API calls.

Real-Time Messaging with Socket.io

Sharetribe has a built-in messaging API within transactions, but for a live chat experience layer Socket.io on top of your Node.js backend. Subscribe to Sharetribe webhook events for new messages and broadcast them to connected clients — this gives buyers and sellers sub-second message delivery without polling. Store messages in your own database for custom features like read receipts, file attachments, and push notifications.

Search, Filtering, and Geolocation

Sharetribe Flex's marketplace data API supports keyword search, category filtering, price range filtering, and radius-based geolocation search out of the box. For more advanced requirements — typo tolerance, synonym mapping, faceted filtering with real-time counts — mirror listings to Algolia or Elasticsearch and use Sharetribe as the source of truth. The search UI lives entirely in your Next.js components.

Availability and Booking Calendar

For rental or service marketplaces, Sharetribe Flex manages availability through an availability plan per listing. Sellers set their weekly schedule and block specific dates as exceptions. When a buyer initiates a booking, the SDK checks availability in real time. Your frontend renders this as a calendar UI — I typically use a custom React component built on top of the availability data to match the brand precisely.

Deployment

Deploy the Next.js frontend to Vercel for optimal integration — automatic edge caching, image optimisation via next/image, and zero-config deployments from git. For the Node.js backend handling Stripe webhooks, Socket.io, and privileged transitions, Railway or Render work well. Keep all Sharetribe API calls behind Next.js Route Handlers — never call the SDK directly from the browser.

Common Pitfalls to Avoid

Three mistakes I see most often: (1) fetching listing data client-side instead of server-side — Googlebot won't wait for JavaScript to hydrate, so listings become invisible to search; (2) mishandling Sharetribe's opaque pagination cursors, which leads to duplicate results in infinite scroll implementations; and (3) building a separate database for data that belongs in Sharetribe's extended data, which creates sync complexity with no benefit.