Pexels JavaScript Client

Common errors

• TypeError: Cannot read properties of undefined (reading 'photos')

  cause The `createClient` function was not properly called with an API key, or the key was invalid, leading to an uninitialized or failed client instance.
  fix Ensure `createClient('YOUR_API_KEY')` is called with a valid Pexels API key. Verify the key is correct and accessible (e.g., from environment variables).

• Error: Request failed with status code 401

  cause The provided Pexels API Key is either missing, incorrect, or expired.
  fix Check your API key. Ensure it's correctly copied, active, and passed to `createClient()`. You can generate a new one at https://www.pexels.com/api/new/ if needed.

• TS2305: Module '"pexels"' has no exported member 'Photo'.

  cause Attempting to import a TypeScript interface (`Photo`, `Video`) using a regular named import (`import { Photo } from 'pexels';`) instead of a type-only import.
  fix Change your import statement to `import type { Photo } from 'pexels';` for type definitions.

Warnings

• breaking As of v1.3.0, the client now throws an error when the API response is not `ok`. Previously, it might have returned a non-success response object that required manual checking.
  Fix: Ensure your error handling explicitly catches exceptions thrown by API calls, rather than relying solely on checking properties like `response.ok` on the returned object.
• gotcha An API Key is mandatory for almost all interactions with the Pexels API. Attempts to use the client without a valid key will result in authentication errors.
  Fix: Obtain an API key from Pexels (https://www.pexels.com/api/new/) and pass it to `createClient()`. For production, use environment variables (`process.env.PEXELS_API_KEY`) to manage keys securely.
• gotcha While the library ships TypeScript types, it's crucial to use `import type` for interfaces (e.g., `Photo`, `Video`) to prevent them from being bundled into your JavaScript output, which can increase payload size unnecessarily.
  Fix: Always use `import type { Photo, Video } from 'pexels';` when importing only type definitions.

Install

• npm install pexels npm
• yarn add pexels yarn
• pnpm add pexels pnpm

Imports

• createClient
  wrong:

  const createClient = require('pexels').createClient;

  correct:

  import { createClient } from 'pexels';

  The primary entry point for initializing the Pexels client. Named import is standard for ESM.
• Photo
  wrong:

  import { Photo } from 'pexels';

  correct:

  import type { Photo } from 'pexels';

  Use `import type` for TypeScript interfaces to ensure they are removed during compilation, avoiding runtime overhead.
• Video
  wrong:

  import { Video } from 'pexels';

  correct:

  import type { Video } from 'pexels';

  Type import for video objects returned by the API. Follows standard TypeScript best practices.

Quickstart

Demonstrates initializing the Pexels client with an API key and fetching curated photos, handling potential errors and types.

import { createClient } from 'pexels';
import type { Photo } from 'pexels';

const PEXELS_API_KEY = process.env.PEXELS_API_KEY ?? '';

if (!PEXELS_API_KEY) {
  console.error('PEXELS_API_KEY environment variable is not set.');
  process.exit(1);
}

const client = createClient(PEXELS_API_KEY);

async function fetchCuratedPhotos() {
  try {
    const query = 'nature';
    const photos = await client.photos.search({ query, per_page: 1 });

    if ('photos' in photos) {
      console.log(`Found ${photos.total_results} photos for '${query}'.`);
      if (photos.photos.length > 0) {
        const firstPhoto: Photo = photos.photos[0];
        console.log('First photo ID:', firstPhoto.id);
        console.log('Photographer:', firstPhoto.photographer);
        console.log('Original image URL:', firstPhoto.src.original);
      } else {
        console.log('No photos found for the query.');
      }
    } else {
      console.error('API Error:', photos);
    }
  } catch (error) {
    console.error('An unexpected error occurred:', error);
  }
}

fetchCuratedPhotos();