unsplash-js

library7.0.20jsnpmunverified

unsplash-js is the official JavaScript wrapper for the Unsplash API, providing a convenient way to interact with Unsplash's photo services. The library abstracts away direct HTTP requests, offering methods for accessing photos, users, collections, and search functionalities. The current stable version is 7.0.20. Historically, it saw frequent minor updates for new API features and bug fixes, as evidenced by the recent v7.0.x releases. However, as of the latest README, the project has been officially archived and no longer receives support or updates, meaning new API features from Unsplash will not be integrated into this library, and critical bug fixes are unlikely. Developers are now directed to use the Unsplash developer documentation to make requests directly to the API, rather than relying on this wrapper.

communication http-networking web-framework

npm install unsplash-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNSPLASH-JS

unsplash-js

communicationjavascriptv7.0.20

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.

createApi

✓ import { createApi } from 'unsplash-js';

✗ const { createApi } = require('unsplash-js');

The library primarily uses ESM imports. While CJS might work with transpilation, direct require() is not the intended or officially supported way for modern usage.

NodeFetch

✓ import nodeFetch from 'node-fetch';

✗ import { fetch } from 'node-fetch';

When providing node-fetch as a custom fetch implementation, it's typically imported as a default export.

RequestInit, Response

✓ type RequestInit = nodeFetch.RequestInit; type Response = nodeFetch.Response;

These types are globally presumed by unsplash-js. In Node.js environments using node-fetch, they often need to be manually declared or asserted to resolve TypeScript issues, especially with node-fetch v3.

Initializes the Unsplash API client with an access key and fetches a random landscape photo, demonstrating basic API interaction and best practices for Node.js with `node-fetch` and TypeScript.

import { createApi } from 'unsplash-js'; import nodeFetch from 'node-fetch'; // Ensure global fetch types are available for TypeScript in Node.js declare global { var fetch: typeof nodeFetch.default; type RequestInit = nodeFetch.RequestInit; type Response = nodeFetch.Response; } // Set global fetch for Node.js if not already present if (typeof global !== 'undefined' && !global.fetch) { global.fetch = nodeFetch.default; } const MY_ACCESS_KEY = process.env.UNSPLASH_ACCESS_KEY ?? ''; if (!MY_ACCESS_KEY) { console.error('UNSPLASH_ACCESS_KEY environment variable is not set.'); process.exit(1); } const unsplash = createApi({ accessKey: MY_ACCESS_KEY, // Optional: Provide node-fetch explicitly if not setting globally, or for type compatibility fetch: nodeFetch.default as unknown as typeof fetch, }); async function getRandomPhoto() { try { const result = await unsplash.photos.getRandom({ count: 1, orientation: 'landscape', }); if (result.type === 'success' && result.response.length > 0) { const photo = result.response[0]; console.log('Random Photo:', photo.urls.regular); console.log('Photographer:', photo.user.name); console.log('Download URL (trigger download):', photo.links.download_location); } else if (result.type === 'error') { console.error('Failed to fetch random photo:', result.errors); } } catch (error) { console.error('An unexpected error occurred:', error); } } getRandomPhoto();

Debug

Known issues

breakingThe `unsplash-js` project has been officially archived and is no longer maintained. It will not receive updates, new features, or bug fixes. Developers should transition to direct API calls using the Unsplash developer documentation.

fix

Migrate your application to make direct HTTP requests to the Unsplash API using `fetch` or a similar HTTP client, following the official Unsplash API documentation for endpoints, authentication, and guidelines.

affects: >=7.0.0

gotchaThis library depends on the `fetch` API. In Node.js environments, you must provide a polyfill like `node-fetch`, either globally or explicitly when calling `createApi`.

fix

For Node.js, install `node-fetch` (`npm i node-fetch`) and then either set `global.fetch = require('node-fetch');` or pass it directly: `createApi({ accessKey: 'YOUR_KEY', fetch: require('node-fetch') });`

affects: >=1.0.0

gotchaWhen using `node-fetch` v3 with TypeScript, there's a known incompatibility where `node-fetch` pollutes the global namespace with 'dom' type definitions, causing conflicts with `unsplash-js`'s expectation of global `fetch`, `RequestInit`, and `Response` types.

fix

Use a type assertion: `fetch: nodeFetch.default as unknown as typeof fetch,` when passing `node-fetch.default` to `createApi`. Alternatively, stick to `node-fetch` v2 if possible.

affects: >=7.0.0

gotchaAdherence to Unsplash API Guidelines is mandatory. This includes hotlinking images, attributing photographers, and triggering a download when appropriate.

fix

Always embed images using the URLs provided by the API (hotlinking). Display the photographer's name (e.g., 'Photo by [Photographer Name] / Unsplash'). When users download a photo from your application, trigger the Unsplash download endpoint (`photo.links.download_location`).

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: fetch is not defined

The runtime environment (typically Node.js) does not have a global `fetch` function available, and no polyfill was provided.

fix

Install `node-fetch` (`npm install node-fetch`) and set it globally (`global.fetch = require('node-fetch');`) or pass it directly to `createApi`: `createApi({ accessKey: 'YOUR_KEY', fetch: require('node-fetch') });`

Argument of type 'typeof import("node-fetch")' is not assignable to parameter of type 'typeof fetch'.

TypeScript type conflict when passing `node-fetch` to `createApi`, especially with `node-fetch` v3, due to differing global type definitions or incorrect import/assignment.

fix

Use a type assertion when passing `node-fetch.default`: `fetch: nodeFetch.default as unknown as typeof fetch,`.

Error: Request failed with status code 401. 'The access key provided is invalid.'

The `accessKey` configured for `unsplash-js` is incorrect, expired, or missing required permissions.

fix

Double-check your Unsplash developer account for the correct 'Access Key' and ensure it's properly configured in your application. Register as a developer if you haven't already.

Upgrade

Version history

7.0.20latest on npm

Audit

Dependencies

node-fetchoptionalRecommended polyfill for `fetch` in Node.js environments.

whatwg-fetchoptionalRecommended polyfill for `fetch` in browser environments that lack native support.

Agent activity

26 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/unsplash/unsplash-js ↗

packagehttps://www.npmjs.com/package/unsplash-js ↗

homepagehttps://unsplash.com/developers ↗