{"id":12320,"library":"unsplash-js","title":"Unsplash JavaScript API Wrapper","description":"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.","status":"abandoned","version":"7.0.20","language":"javascript","source_language":"en","source_url":"https://github.com/unsplash/unsplash-js","tags":["javascript","unsplash","photos","api","images","splash","free","typescript"],"install":[{"cmd":"npm install unsplash-js","lang":"bash","label":"npm"},{"cmd":"yarn add unsplash-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add unsplash-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Recommended polyfill for `fetch` in Node.js environments.","package":"node-fetch","optional":true},{"reason":"Recommended polyfill for `fetch` in browser environments that lack native support.","package":"whatwg-fetch","optional":true}],"imports":[{"note":"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.","wrong":"const { createApi } = require('unsplash-js');","symbol":"createApi","correct":"import { createApi } from 'unsplash-js';"},{"note":"When providing node-fetch as a custom fetch implementation, it's typically imported as a default export.","wrong":"import { fetch } from 'node-fetch';","symbol":"NodeFetch","correct":"import nodeFetch from 'node-fetch';"},{"note":"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.","symbol":"RequestInit, Response","correct":"type RequestInit = nodeFetch.RequestInit; type Response = nodeFetch.Response;"}],"quickstart":{"code":"import { createApi } from 'unsplash-js';\nimport nodeFetch from 'node-fetch';\n\n// Ensure global fetch types are available for TypeScript in Node.js\ndeclare global {\n  var fetch: typeof nodeFetch.default;\n  type RequestInit = nodeFetch.RequestInit;\n  type Response = nodeFetch.Response;\n}\n\n// Set global fetch for Node.js if not already present\nif (typeof global !== 'undefined' && !global.fetch) {\n  global.fetch = nodeFetch.default;\n}\n\nconst MY_ACCESS_KEY = process.env.UNSPLASH_ACCESS_KEY ?? '';\n\nif (!MY_ACCESS_KEY) {\n  console.error('UNSPLASH_ACCESS_KEY environment variable is not set.');\n  process.exit(1);\n}\n\nconst unsplash = createApi({\n  accessKey: MY_ACCESS_KEY,\n  // Optional: Provide node-fetch explicitly if not setting globally, or for type compatibility\n  fetch: nodeFetch.default as unknown as typeof fetch,\n});\n\nasync function getRandomPhoto() {\n  try {\n    const result = await unsplash.photos.getRandom({\n      count: 1,\n      orientation: 'landscape',\n    });\n\n    if (result.type === 'success' && result.response.length > 0) {\n      const photo = result.response[0];\n      console.log('Random Photo:', photo.urls.regular);\n      console.log('Photographer:', photo.user.name);\n      console.log('Download URL (trigger download):', photo.links.download_location);\n    } else if (result.type === 'error') {\n      console.error('Failed to fetch random photo:', result.errors);\n    }\n  } catch (error) {\n    console.error('An unexpected error occurred:', error);\n  }\n}\n\ngetRandomPhoto();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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') });`","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=7.0.0"},{"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`).","message":"Adherence to Unsplash API Guidelines is mandatory. This includes hotlinking images, attributing photographers, and triggering a download when appropriate.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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') });`","cause":"The runtime environment (typically Node.js) does not have a global `fetch` function available, and no polyfill was provided.","error":"ReferenceError: fetch is not defined"},{"fix":"Use a type assertion when passing `node-fetch.default`: `fetch: nodeFetch.default as unknown as 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.","error":"Argument of type 'typeof import(\"node-fetch\")' is not assignable to parameter of type 'typeof fetch'."},{"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.","cause":"The `accessKey` configured for `unsplash-js` is incorrect, expired, or missing required permissions.","error":"Error: Request failed with status code 401. 'The access key provided is invalid.'"}],"ecosystem":"npm"}