Unsplash JavaScript API Wrapper

Common errors

• ReferenceError: fetch is not defined

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

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

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

Warnings

• breaking The `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.
• gotcha This 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') });`
• gotcha When 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.
• gotcha Adherence 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`).

Install

• npm install unsplash-js npm
• yarn add unsplash-js yarn
• pnpm add unsplash-js pnpm

Imports

• createApi
  wrong:

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

  correct:

  import { createApi } from '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
  wrong:

  import { fetch } from 'node-fetch';

  correct:

  import nodeFetch 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.

Quickstart

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