Quick Start

Get a photo search running in minutes using published npm packages (@media-sdk/core@^0.3.1, react packages @^0.3.0). No monorepo clone required.

Starter template (recommended)

Copy the basic React starter — a self-contained Vite app with Pexels + Pixabay, capability-gated tabs and filters:

# Clone the repo, or copy examples/basic-react to your project
cd examples/basic-react
pnpm install
cp .env.example .env   # add VITE_PEXELS_API_KEY and/or VITE_PIXABAY_API_KEY
pnpm dev

See the starter README for the full 5-minute path.

Core — photo search

import { ApiKeyProvider, PexelsMediaClient } from "@media-sdk/core";

const client = new PexelsMediaClient(
  new ApiKeyProvider(process.env.PEXELS_API_KEY!),
);

const result = await client.searchPhotos({
  query: "nature",
  page: 1,
  perPage: 20,
});

console.log(result.items);
console.log(result.pagination);

Install:

pnpm add @media-sdk/core@^0.3.1

Set PEXELS_API_KEY in your environment (see Installation).

React — search with hooks

import { MediaProvider, useMediaSearch } from "@media-sdk/react";
import { ApiKeyProvider, PexelsMediaClient } from "@media-sdk/core";

const client = new PexelsMediaClient(
  new ApiKeyProvider(import.meta.env.VITE_PEXELS_API_KEY),
);

function SearchApp() {
  const { data, loading, error } = useMediaSearch({
    query: "nature",
    perPage: 20,
  });

  if (loading) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data?.items.map((photo) => (
        <li key={photo.id}>
          <img src={photo.src.medium} alt={photo.alt ?? ""} />
        </li>
      ))}
    </ul>
  );
}

export function App() {
  return (
    <MediaProvider client={client}>
      <SearchApp />
    </MediaProvider>
  );
}

Install:

pnpm add @media-sdk/core@^0.3.1 @media-sdk/react@^0.3.0 react react-dom

Set VITE_PEXELS_API_KEY in .env for Vite apps.

Pixabay

Swap the client — the hook API stays the same:

import { ApiKeyProvider, PixabayMediaClient } from "@media-sdk/core";

const client = new PixabayMediaClient(
  new ApiKeyProvider(process.env.PIXABAY_API_KEY!),
);

Gate UI features with capabilities, not provider strings:

import { useMediaCapabilities } from "@media-sdk/react";

function Tabs() {
  const caps = useMediaCapabilities();
  return caps.operations.curatedPhotos ? <CuratedTab /> : null;
}

Next steps

Topic	Link
Install all packages and configure TypeScript	Installation
Pexels auth, curated photos, filters	PexelsMediaClient
Pixabay auth, hotlinking, filters	PixabayMediaClient
Capability matrix and provider differences	Provider Comparison
Multi-provider setup and env vars	Provider Configuration
MediaClient interface reference	MediaClient
Capability-driven UI gating	Capabilities
React hooks reference	Hooks
Presentational components	UI Components
Live multi-provider demo	Demo