Pexels JavaScript

pexels is the official Pexels JavaScript client, giving Node.js and browser apps a single typed entry point for searching and fetching free stock photos and videos through the Pexels API. Calling createClient(apiKey) returns three namespaced resource clients — photos, videos, and collections — each mapping directly onto Pexels’ REST endpoints for search, curated/popular feeds, single-item lookups, and curated collections.

Built with TypeScript and compiled via microbundle into CommonJS, ESM, and UMD bundles, it ships type definitions out of the box and relies on isomorphic-fetch so the same code runs unmodified in Node.js or the browser, with no other runtime dependencies to manage.

What You Get

• A single createClient(apiKey) factory that returns typed photos, videos, and collections resource clients
• Photo endpoints for keyword search, curated feeds, single-photo lookup by ID, and a random-photo helper
• Video endpoints for keyword search, popular feeds, and single-video lookup by ID
• Collection endpoints for listing all collections, fetching a collection’s media, and browsing featured collections
• Full TypeScript type definitions for every request parameter and response shape, bundled with the package

Common Use Cases

• Populating a marketing site or blog with royalty-free stock photography pulled live from Pexels search results
• Building a photo/video picker inside a CMS or design tool backed by Pexels’ catalog
• Fetching a random curated photo to use as a dynamic hero image or placeholder background
• Surfacing a themed Pexels collection inside a media gallery feature

Under The Hood

Architecture main.ts exports a single createClient factory and the package’s shared types. createClient.ts builds a client object by calling three generator functions — generatePhotoEndpoints, generateVideoEndpoints, and generateCollectionEndpoints — each of which instantiates createFetchWrapper(apiKey, resourceType) to produce a per-resource-type HTTP fetcher bound to a base URL from constants.ts. createFetchWrapper returns a generic curried function that stringifies query params and issues the request via isomorphic-fetch, so the same code path runs in Node.js and the browser. This is a flat, single-layer functional architecture — no classes, no DI container, no hidden state beyond the closure-captured apiKey — where each domain resource module is independently swappable through object composition. If the shared fetch-wrapper’s response-parsing or error-throwing behavior changed, it would ripple identically across all three resource modules since they all delegate to it.

Tech Stack Written in TypeScript and compiled with microbundle into CommonJS, ESM, and UMD builds (dist/main.js, main.module.js, main.umd.js), with a single runtime dependency, isomorphic-fetch, polyfilling fetch for Node while using the browser’s native implementation. There is no web framework, ORM, or database involved since this is a stateless API-wrapper library; testing uses Jest with ts-jest for TypeScript transforms, and Prettier enforces formatting. The package is published to npm as pexels and also exposed via the unpkg CDN through its umd build field; no CI workflow configuration is present in the repository.

Code Quality The test suite (createClient.spec.ts) uses Jest snapshot testing against the live Pexels API — it requires a real API_KEY environment variable rather than mocking network calls — paired with a small mutateAllValuesToNull test utility that normalizes volatile live-data fields before snapshotting. Error handling is explicit but minimal: createClient throws a TypeError when no API key is supplied, and createFetchWrapper throws on non-ok HTTP responses using the response’s status text; there’s a shared ErrorResponse type but no typed error class hierarchy. Naming is consistent and descriptive throughout (generateXEndpoints, createFetchWrapper), and types are centralized in types.ts. No ESLint configuration or CI pipeline was found in the repository.

API Design The entire public surface is one createClient(apiKey) call returning three namespaces — photos, videos, collections — whose method names (search, curated, show, random, popular, featured, media) mirror Pexels’ own REST resource names, so anyone familiar with the HTTP API needs almost no ramp-up. Getting started takes a single line with no configuration objects, and TypeScript types are exported directly from the package so consumers get autocomplete without installing a separate @types package. It also ships isPhotos/isVideos/isError runtime type-checker helpers, a small but genuinely useful touch for discriminating response shapes beyond what a typical thin API wrapper offers.