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

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;

Production hardening — allowlist, cache headers, CORS, CSRF

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,
});

All error responses use a consistent envelope:

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

See examples/app-router/route.ts for the full example.

Pages Router setup

// 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();

Custom token provider (e.g. Redis, database)

If your app stores OAuth tokens externally instead of using client credentials:

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();

When getToken is set, it's called for every public route instead of the built-in client credentials flow. Auth routes (/me/*, actions) still use the Authorization: Bearer header from the request.

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>
  );
}

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>
  ));
}

Hooks

All hooks return { data, loading, error }.

General

Hook	Description
`useResolve(url)`	Resolve a SoundCloud URL to a track, user, or playlist

Tracks

Hook	Description
`useTrack(id)`	Single track
`useTrackSearch(query)`	Search tracks
`useTrackComments(id)`	Track comments
`useTrackLikes(id)`	Users who liked a track
`useRelatedTracks(id)`	Related tracks
`usePlayer(trackId)`	Audio player — `{ playing, progress, duration, play, pause, toggle, seek }`

Users

Hook	Description
`useUser(id)`	Single user
`useUserSearch(query)`	Search users
`useUserTracks(id)`	User's tracks
`useUserPlaylists(id)`	User's playlists
`useUserLikes(id)`	User's liked tracks
`useUserFollowers(id)`	User's followers
`useUserFollowings(id)`	User's followings

Playlists

Hook	Description
`usePlaylist(id)`	Single playlist
`usePlaylistSearch(query)`	Search playlists
`usePlaylistTracks(id)`	Playlist tracks

Server Components (RSC)

Use the server helpers (getTrack, searchTracks, getUser, getPlaylist, getMe) in React Server Components with optional next/cache revalidation:

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

const config = {
  clientId: process.env.SC_CLIENT_ID!,
  clientSecret: process.env.SC_CLIENT_SECRET!,
};

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

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

For full API access, createSoundCloudServerClient is async and returns { client, userToken, token() } — call methods on .client:

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

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

const tokenResult = await sc.client.auth.getClientToken();
const track = await sc.client.tracks.getTrack(trackId, { token: tokenResult.access_token });

See docs/rsc-guide.md for full patterns.

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]);

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>;
}

// 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>;
}

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 }

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>}
    </>
  );
}

Hook	Description
`useInfiniteTrackSearch(query)`	Paginated track search
`useInfiniteUserSearch(query)`	Paginated user search
`useInfinitePlaylistSearch(query)`	Paginated playlist search
`useInfiniteUserTracks(id)`	User's tracks
`useInfiniteUserPlaylists(id)`	User's playlists
`useInfiniteUserLikes(id)`	User's liked tracks
`useInfiniteUserFollowers(id)`	User's followers
`useInfiniteUserFollowings(id)`	User's followings
`useInfiniteTrackComments(id)`	Track comments
`useInfinitePlaylistTracks(id)`	Playlist tracks

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>;
}

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>;
}

Authenticated Hooks

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

Hook	Description
`useMe()`	Current user profile
`useMeTracks()`	Your tracks
`useMeLikes()`	Your liked tracks
`useMePlaylists()`	Your playlists
`useMeFollowings()`	Who you follow
`useMeFollowers()`	Your followers

Actions

Mutation hooks for authenticated users.

Hook	Methods
`useLike()`	`likeTrack(id)`, `unlikeTrack(id)`
`useFollow()`	`follow(userId)`, `unfollow(userId)`
`useRepost()`	`repostTrack(id)`, `unrepostTrack(id)`

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>
    </>
  );
}

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!,
});

`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;
}

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 });
}

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);

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)

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:

Route	Method	Description
`/resolve?url=`	GET	Resolve a SoundCloud URL to an API resource
`/search/tracks?q=`	GET	Search tracks
`/search/users?q=`	GET	Search users
`/search/playlists?q=`	GET	Search playlists
`/tracks/:id`	GET	Track details
`/tracks/:id/stream`	GET	Stream URLs
`/tracks/:id/comments`	GET	Track comments
`/tracks/:id/likes`	GET	Track likes
`/tracks/:id/related`	GET	Related tracks
`/tracks/:id/like`	POST/DELETE	Like/unlike (auth)
`/tracks/:id/repost`	POST/DELETE	Repost/unrepost (auth)
`/users/:id`	GET	User details
`/users/:id/tracks`	GET	User tracks
`/users/:id/playlists`	GET	User playlists
`/users/:id/likes/tracks`	GET	User likes
`/users/:id/followers`	GET	User followers
`/users/:id/followings`	GET	User followings
`/playlists/:id`	GET	Playlist details
`/playlists/:id/tracks`	GET	Playlist tracks
`/playlists/:id/like`	POST/DELETE	Like/unlike (auth)
`/playlists/:id/repost`	POST/DELETE	Repost/unrepost (auth)
`/me`	GET	Current user (auth)
`/me/tracks`	GET	Your tracks (auth)
`/me/likes`	GET	Your likes (auth)
`/me/playlists`	GET	Your playlists (auth)
`/me/followings`	GET	Your followings (auth)
`/me/followers`	GET	Your followers (auth)
`/me/follow/:userId`	POST/DELETE	Follow/unfollow (auth)
`/auth/login`	GET	OAuth URL (PKCE)
`/auth/callback`	GET	Token exchange
`/auth/refresh`	POST	Refresh token
`/auth/logout`	POST	Sign out
`/next?url=`	GET	Pagination cursor

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`);
  },
});

The SCRouteTelemetry object:

Field	Type	Description
`route`	`string`	Route path (e.g. "/tracks/123")
`method`	`string`	HTTP method
`durationMs`	`number`	Total handler duration
`status`	`number`	HTTP response status
`error`	`string?`	Error message if handler threw

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";

Requirements

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

License

MIT

Package	Purpose
soundcloud-api-ts	TypeScript-first SoundCloud API client — the base this package builds on
soundcloud-api-ts-next ← you are here	Next.js integration: hooks, secure API routes, OAuth PKCE, RSC helpers
soundcloud-widget-react	React component for the SoundCloud HTML5 Widget API — embed players and control playback programmatically

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

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
llms-full.txt		llms-full.txt
llms.txt		llms.txt
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
typedoc.json		typedoc.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

soundcloud-api-ts-next

Install

Quick Start

Hooks

General

Tracks

Users

Playlists

Server Components (RSC)

TanStack Query / SWR

Infinite Scroll

Authentication

Login

Callback Page

Authenticated Hooks

Actions

Server-Side Auth Manager

`initLogin()` — generate PKCE URL + CSRF state

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

`refreshToken(refreshToken)` — refresh an expired token

API Reference

Server Routes

Route Telemetry

Types

Requirements

License

Related

About

Uh oh!

Releases 29

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

soundcloud-api-ts-next

Install

Quick Start

Hooks

General

Tracks

Users

Playlists

Server Components (RSC)

TanStack Query / SWR

Infinite Scroll

Authentication

Login

Callback Page

Authenticated Hooks

Actions

Server-Side Auth Manager

initLogin() — generate PKCE URL + CSRF state

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

refreshToken(refreshToken) — refresh an expired token

API Reference

Server Routes

Route Telemetry

Types

Requirements

License

Related

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 29

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`initLogin()` — generate PKCE URL + CSRF state

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

`refreshToken(refreshToken)` — refresh an expired token

Packages