pexels

library0.0.11jsnpmunverified

The Pexels JavaScript client is an official, actively maintained wrapper for the Pexels API, designed to simplify interactions for both Node.js and browser environments. Currently stable at version 1.4.0, it provides a fluent interface for accessing Pexels' vast collection of photos and videos, including curated content and search functionality. Recent releases indicate a steady cadence of updates, including new API endpoint support (e.g., collections) and type enhancements for a robust TypeScript experience. Its key differentiator is being the officially supported client, ensuring alignment with the Pexels API and consistent maintenance. It internally utilizes `isomorphic-fetch` to provide a consistent fetching mechanism across different JavaScript runtimes.

http-networking

npm install pexels

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PEXELS

pexels

http-networkingjavascriptv0.0.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createClient

✓ import { createClient } from 'pexels';

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

The primary entry point for initializing the Pexels client. Named import is standard for ESM.

Photo

✓ import type { Photo } from 'pexels';

✗ import { Photo } from 'pexels';

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

Video

✓ import type { Video } from 'pexels';

✗ import { Video } from 'pexels';

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

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

Debug

Known issues

breakingAs 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.

affects: >=1.3.0

gotchaAn 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.

affects: >=1.0.1

gotchaWhile 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.

affects: >=1.0.1

Errors

Common errors & fixes

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

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

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'.

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.

Upgrade

Version history

0.0.11latest on npm

Audit

Dependencies

isomorphic-fetchrequiredProvides a consistent `fetch` API across Node.js and browser environments for making HTTP requests to the Pexels API.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/pexels/pexels-javascript ↗

packagehttps://www.npmjs.com/package/pexels ↗

homepagehttps://www.pexels.com ↗