soundcloud-api-ts-next

TypeScript React hooks and Next.js API route handlers for the SoundCloud API. Works with App Router and Pages Router. OAuth PKCE authentication built in. Client secrets stay on the server.

API Docs · Built on soundcloud-api-ts — the TypeScript-first SoundCloud API client.

When to use this vs direct API calls: Use this package when you're building a Next.js app and want typed React hooks for SoundCloud data without exposing credentials to the browser. The hooks fetch through your Next.js API routes, keeping secrets server-side. Supports both App Router and Pages Router. For backend-only or non-React projects, use soundcloud-api-ts directly.

Install

npm install soundcloud-api-ts-next
Copy

Quick Start

1. Create API routes — secrets stay server-side:

// app/api/soundcloud/[...route]/route.ts
import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";

const sc = createSoundCloudRoutes({
  clientId: process.env.SOUNDCLOUD_CLIENT_ID!,
  clientSecret: process.env.SOUNDCLOUD_CLIENT_SECRET!,
  redirectUri: process.env.SOUNDCLOUD_REDIRECT_URI, // for OAuth
});

const handler = sc.handler();
export const GET = handler;
export const POST = handler;
export const DELETE = handler;
Copy

const sc = createSoundCloudRoutes({
  clientId: process.env.SC_CLIENT_ID!,
  clientSecret: process.env.SC_CLIENT_SECRET!,

  // Only expose these route prefixes (403 for anything else)
  routes: {
    allowlist: ["tracks", "search", "users", "playlists", "me", "auth", "resolve"],
  },

  // Cache-Control per route prefix (applied to GET responses only)
  cacheHeaders: {
    tracks: "public, max-age=60, stale-while-revalidate=300",
    me: "no-store",
    default: "public, max-age=30",
  },

  // CORS — restrict to your origin
  cors: {
    origin: process.env.NEXT_PUBLIC_BASE_URL!,
    methods: ["GET", "POST", "DELETE"],
  },

  // Block cross-origin state-changing requests
  csrfProtection: true,
});
Copy

{ "code": "NOT_FOUND", "message": "Not found", "status": 404, "requestId": "..." }
Copy

// pages/api/soundcloud/[...route].ts
import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";

const sc = createSoundCloudRoutes({
  clientId: process.env.SOUNDCLOUD_CLIENT_ID!,
  clientSecret: process.env.SOUNDCLOUD_CLIENT_SECRET!,
});

export default sc.pagesHandler();
Copy

import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";
import { getRedisClient } from "../lib/redis";

const sc = createSoundCloudRoutes({
  clientId: process.env.SOUNDCLOUD_CLIENT_ID!,
  clientSecret: process.env.SOUNDCLOUD_CLIENT_SECRET!,
  getToken: async () => {
    const redis = await getRedisClient();
    return redis.get("soundcloud:access_token");
  },
});

export default sc.pagesHandler();
Copy

2. Add the provider:

// app/layout.tsx
import { SoundCloudProvider } from "soundcloud-api-ts-next";

export default function Layout({ children }) {
  return (
    <SoundCloudProvider apiPrefix="/api/soundcloud">
      {children}
    </SoundCloudProvider>
  );
}
Copy

3. Use hooks:

import { useTrackSearch, usePlayer } from "soundcloud-api-ts-next";

function SearchPage() {
  const { data: tracks, loading } = useTrackSearch("lofi beats");

  if (loading) return <p>Searching...</p>;

  return tracks?.map((track) => (
    <div key={track.id}>
      <p>{track.title} — {track.user.username}</p>
    </div>
  ));
}
Copy

Hooks

All hooks return { data, loading, error }.

General

Tracks

Users

Playlists

Server Components (RSC)

Use createSoundCloudServerClient in React Server Components with optional next/cache revalidation:

// app/tracks/[id]/page.tsx
import { createSoundCloudServerClient } from "soundcloud-api-ts-next/server";

const sc = createSoundCloudServerClient({
  clientId: process.env.SC_CLIENT_ID!,
  clientSecret: process.env.SC_CLIENT_SECRET!,
});

export default async function TrackPage({ params }: { params: { id: string } }) {
  const track = await sc.tracks.getTrack(Number(params.id), {
    revalidate: 60,
    tags: [`track-${params.id}`],
  });

  return <h1>{track.title}</h1>;
}
Copy

Cache key helpers — use scCacheKeys (from /server) with revalidateTag for on-demand invalidation:

import { scCacheKeys, getTrack } from "soundcloud-api-ts-next/server";

// Fetch with tag
const track = await getTrack(trackId, config, { tags: scCacheKeys.track(trackId) });

// Later, invalidate from a Server Action or route handler
import { revalidateTag } from "next/cache";
revalidateTag(scCacheKeys.track(trackId)[0]);
Copy

scCacheKeys produces stable string arrays: track(id), user(id), playlist(id), searchTracks(q), me().

See docs/rsc-guide.md for the full guide, including streaming patterns and mixing RSC with client hooks.

TanStack Query / SWR

Use scFetchers and scKeys for integration with TanStack Query or SWR:

import { useQuery } from "@tanstack/react-query";
import { scFetchers, scKeys } from "soundcloud-api-ts-next";

function TrackCard({ id }: { id: number }) {
  const { data } = useQuery({
    queryKey: scKeys.track(id),
    queryFn: () => scFetchers.track(id),
  });
  return <h1>{data?.title}</h1>;
}
Copy

// SWR
import useSWR from "swr";
import { scFetchers, scKeys } from "soundcloud-api-ts-next";

function TrackCard({ id }: { id: number }) {
  const { data } = useSWR(scKeys.track(id), () => scFetchers.track(id));
  return <h1>{data?.title}</h1>;
}
Copy

scKeys produces stable array keys (["sc", "track", "123"]) for cache invalidation across queries. scFetchers are plain async functions — no React dependency.

See docs/tanstack-query.md for RSC prefetch patterns, authenticated queries, and SWR examples.

Infinite Scroll

Cursor-based pagination with loadMore() and reset(). All return InfiniteResult<T>:

{ data: T[], loading, error, hasMore, loadMore, reset }
Copy

import { useInfiniteTrackSearch } from "soundcloud-api-ts-next";

function Feed() {
  const { data, loading, hasMore, loadMore } = useInfiniteTrackSearch("dubstep");

  return (
    <>
      {data.map((track) => <TrackCard key={track.id} track={track} />)}
      {hasMore && <button onClick={loadMore} disabled={loading}>Load More</button>}
    </>
  );
}
Copy

Authentication

Full OAuth 2.1 with PKCE via secure.soundcloud.com. No secrets on the client.

Login

import { useSCAuth } from "soundcloud-api-ts-next";

function LoginButton() {
  const { isAuthenticated, user, login, logout } = useSCAuth();

  if (isAuthenticated) {
    return (
      <div>
        <p>Welcome, {user?.username}</p>
        <button onClick={logout}>Logout</button>
      </div>
    );
  }

  return <button onClick={login}>Login with SoundCloud</button>;
}
Copy

Callback Page

// app/callback/page.tsx
"use client";
import { useEffect } from "react";
import { useSearchParams, useRouter } from "next/navigation";
import { useSCAuth } from "soundcloud-api-ts-next";

export default function Callback() {
  const params = useSearchParams();
  const router = useRouter();
  const { handleCallback } = useSCAuth();

  useEffect(() => {
    const code = params.get("code");
    const state = params.get("state");
    if (code && state) {
      handleCallback(code, state).then(() => router.push("/"));
    }
  }, [params]);

  return <p>Authenticating...</p>;
}
Copy

Authenticated Hooks

Available after login. Automatically pass the user's access token.

Actions

Mutation hooks for authenticated users.

import { useLike, useFollow } from "soundcloud-api-ts-next";

function TrackActions({ trackId, artistId }) {
  const { likeTrack } = useLike();
  const { follow } = useFollow();

  return (
    <>
      <button onClick={() => likeTrack(trackId)}>❤️ Like</button>
      <button onClick={() => follow(artistId)}>➕ Follow</button>
    </>
  );
}
Copy

Server-Side Auth Manager

For apps that need custom logic after token exchange — NextAuth JWT minting, database user creation, account linking — use SCAuthManager directly instead of the HTTP auth routes.

// lib/sc-auth.ts — one module-level instance, shared across all routes
import { createSCAuthManager } from "soundcloud-api-ts-next/server";

export const scAuth = createSCAuthManager({
  clientId: process.env.SC_CLIENT_ID!,
  clientSecret: process.env.SC_CLIENT_SECRET!,
  redirectUri: process.env.SC_REDIRECT_URI!,
});
Copy

initLogin() — generate PKCE URL + CSRF state

// app/api/auth/sc-login/route.ts
import { NextResponse } from "next/server";
import { scAuth } from "@/lib/sc-auth";

export async function GET() {
  const { url, state } = await scAuth.initLogin();

  // Persist state in a short-lived httpOnly cookie for CSRF verification
  const res = NextResponse.redirect(url);
  res.cookies.set("sc-state", state, { httpOnly: true, maxAge: 600, sameSite: "lax" });
  return res;
}
Copy

initLogin() generates a PKCE code_verifier + code_challenge (S256) and a random CSRF state token, stores the verifier server-side, and returns the SoundCloud authorize URL. The PKCE verifier lives in-memory — no cookie or database needed.

exchangeCode(code, state) — verify CSRF + exchange tokens

// app/api/auth/sc-callback/route.ts
import { NextRequest, NextResponse } from "next/server";
import { scAuth } from "@/lib/sc-auth";

export async function GET(req: NextRequest) {
  const code = req.nextUrl.searchParams.get("code")!;
  const state = req.nextUrl.searchParams.get("state")!;

  // Verify CSRF state matches cookie
  const cookieState = req.cookies.get("sc-state")?.value;
  if (!cookieState || cookieState !== state) {
    return NextResponse.json({ error: "Invalid state" }, { status: 400 });
  }

  // Exchange code + PKCE verifier for tokens
  const tokens = await scAuth.exchangeCode(code, state);
  // tokens: { access_token, refresh_token, expires_in, ... }

  // Your app-specific logic here: create user, mint session, etc.
  return NextResponse.json({ ok: true });
}
Copy

exchangeCode verifies state against the stored PKCE entry (CSRF check), then calls SoundCloud's token endpoint with the code_verifier. The entry is deleted after use (one-time).

refreshToken(refreshToken) — refresh an expired token

const newTokens = await scAuth.refreshToken(expiredRefreshToken);
Copy

API Reference

import { createSCAuthManager, type SCAuthManagerConfig, type SCLoginResult, type SoundCloudToken } from "soundcloud-api-ts-next/server";

const scAuth = createSCAuthManager({
  clientId: string,
  clientSecret: string,
  redirectUri: string,
});

scAuth.initLogin(): Promise<SCLoginResult>        // { url, state }
scAuth.exchangeCode(code, state): Promise<SoundCloudToken>
scAuth.refreshToken(token): Promise<SoundCloudToken>
scAuth.pendingLogins: number                       // active PKCE entries (for observability)
Copy

vs HTTP routes: The /auth/login and /auth/callback HTTP routes still work and are the right choice for simple client-side flows where you just need tokens returned as JSON. SCAuthManager is for when you need to run server-side code between "got tokens" and "user is logged in".

Distributed deployments: In serverless or edge environments (Vercel, Cloudflare Workers) where in-memory state doesn't persist across invocations, replace the default in-memory PKCE store with CookiePkceStore. See docs/auth-distributed.md for setup and cookie security options.

Server Routes

The catch-all handler exposes these routes automatically:

Routes marked (auth) require Authorization: Bearer <token> header.

Route Telemetry

Add observability to your API routes with onRouteComplete:

import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";

const sc = createSoundCloudRoutes({
  clientId: process.env.SC_CLIENT_ID!,
  clientSecret: process.env.SC_CLIENT_SECRET!,
  onRouteComplete: (t) => {
    console.log(`[Route] ${t.method} ${t.route} ${t.status} ${t.durationMs}ms`);
  },
});
Copy

The SCRouteTelemetry object:

For per-request SC API telemetry (individual scFetch calls), use SCRequestTelemetry via the soundcloud-api-ts SoundCloudClient class directly.

Types

Re-exported from soundcloud-api-ts:

import type {
  SoundCloudTrack,
  SoundCloudUser,
  SoundCloudPlaylist,
  SoundCloudComment,
  SoundCloudStreams,
  SoundCloudToken,
} from "soundcloud-api-ts-next";
Copy

Requirements

• Next.js 13+ (App Router or Pages Router)
• React 18+
• soundcloud-api-ts installed automatically as a dependency

License

MIT

Related

This package is part of the twin-paws SoundCloud ecosystem:

Common pattern — combine all three in a Next.js app:

// 1. Fetch track data server-side (soundcloud-api-ts-next)
import { getTrack } from "soundcloud-api-ts-next/server";
const track = await getTrack(trackId, config, { revalidate: 60 });

// 2. Render an embeddable player (soundcloud-widget-react)
import { SoundCloudWidget } from "soundcloud-widget-react";
<SoundCloudWidget url={track.permalinkUrl} onPlay={() => trackPlay(track.id)} />

// 3. React hooks for dynamic data (soundcloud-api-ts-next)
import { useTrack } from "soundcloud-api-ts-next";
const { data } = useTrack(trackId); // client-side, post-interaction
Copy