{"id":22632426,"url":"https://github.com/uploadcare/nextjs-loader","last_synced_at":"2025-04-11T20:11:09.607Z","repository":{"id":38195399,"uuid":"409458822","full_name":"uploadcare/nextjs-loader","owner":"uploadcare","description":"Uploadcare custom image loader for Next.js","archived":false,"fork":false,"pushed_at":"2023-05-12T05:37:58.000Z","size":913,"stargazers_count":22,"open_issues_count":1,"forks_count":4,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-21T23:35:13.737Z","etag":null,"topics":["cdn","custom-loader","image-optimization","images","loader","nextjs","optimization","performance-optimization","react","uploadcare"],"latest_commit_sha":null,"homepage":"https://uploadcare-nextjs-loader.netlify.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uploadcare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-23T05:23:13.000Z","updated_at":"2025-01-21T14:32:18.000Z","dependencies_parsed_at":"2024-06-19T00:07:13.499Z","dependency_job_id":"aaaaa5b8-d133-4a21-84b9-670ed4d9ed2d","html_url":"https://github.com/uploadcare/nextjs-loader","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fnextjs-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fnextjs-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fnextjs-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uploadcare%2Fnextjs-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uploadcare","download_url":"https://codeload.github.com/uploadcare/nextjs-loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248473127,"owners_count":21109628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdn","custom-loader","image-optimization","images","loader","nextjs","optimization","performance-optimization","react","uploadcare"],"created_at":"2024-12-09T02:17:32.665Z","updated_at":"2025-04-11T20:11:09.575Z","avatar_url":"https://github.com/uploadcare.png","language":"TypeScript","readme":"# Uploadcare custom image loader for Next.js\n![Test Status][test-status-img]\n[![NPM version][npm-img]][npm-link]\n\n\u003ca href=\"https://uploadcare.com/?utm_source=github\u0026utm_campaign=nextjs-loader\"\u003e\n  \u003cimg align=\"right\" width=\"56\" height=\"56\"\n    src=\"https://ucarecdn.com/1cc871de-5d82-442d-b4d6-aa2e35966879/-/resize/112x112/-/quality/lightest/logocircle2x.png\"\n    alt=\"\"\u003e\n\u003c/a\u003e\n\nThe package helps you use the Uploadcare's transformation and CDN services from a Next.js app smoothly and easily.\n\nIt provides the `uploadcareLoader` function, which you can use as [a custom loader for the Next's Image component](https://nextjs.org/docs/api-reference/next/image#loader), and the `UploadcareImage` component with the custom loader enabled by default.\n\n* [Demo](#demo)\n* [Dependencies](#dependencies)\n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Usage](#usage)\n* [Props](#props)\n* [Notes](#notes)\n* [Known Issues](#known-issues)\n* [Links](#links)\n\n## Demo\n\nLook at the demo [here][demo-link].\n\n## Dependencies\n\nThe only dependency is Next.js \u003e= 10.0.5.\n\n## Installation\n\n```shell_script\nyarn add @uploadcare/nextjs-loader\n```\n\n## Configuration\n\nInform Next that you're going to use a custom image loader through `next.config.js`:\n\n```js\n// next.config.js\nmodule.exports = {\n  images: {\n    loader: \"custom\"\n  }\n}\n```\n\nAdd your public Uploadcare key to your `.env*` config file. You can copy it from Dashboard -\u003e API Keys -\u003e Public key.\n\n```ini\n#.env\nNEXT_PUBLIC_UPLOADCARE_PUBLIC_KEY=\"YOUR_PUBLIC_KEY\"\n```\n\nAlternatively, in case you're using a [custom proxy endpoint][docs-custom-proxy-endpoint], set the proxy domain.\n\n```ini\n#.env\nNEXT_PUBLIC_UPLOADCARE_CUSTOM_PROXY_DOMAIN=\"proxy.example.com\"\n```\n\nIf you're using a proxy, provide your application's base URL (also whitelisted), which is required to process local images properly:\n\n```ini\n#.env\nNEXT_PUBLIC_UPLOADCARE_APP_BASE_URL=\"https://your-domain.com/\"\n```\n\nThat's it. You may now use `@uploadcare/nextjs-loader` in your app (see [Usage](#usage)).\n\n---\n\nBelow are optional parameters which you may not need:\n\n```ini\n#.env\n# A comma-separated list of transformation parameters. Default: format/auto, stretch/off, progressive/yes\nNEXT_PUBLIC_UPLOADCARE_TRANSFORMATION_PARAMETERS=\"format/auto, stretch/off, progressive/yes\"\n# Uploadcare CDN domain. Default: ucarecdn.com\nNEXT_PUBLIC_UPLOADCARE_CUSTOM_CDN_DOMAIN=\"cdn.example.com\"\n```\n\n\u003e Please note `NEXT_PUBLIC_UPLOADCARE_TRANSFORMATION_PARAMETERS` override corresponding default parameters and keep others in place.\n\nImage transformation settings example:\n\n```js{noAutoLinker}\n# .env\nNEXT_PUBLIC_UPLOADCARE_TRANSFORMATION_PARAMETERS=\"format/auto, quality/smart_retina, stretch/off, progressive/yes\"\n```\n\nThe default image transformation parameters are `format/auto, stretch/off, progressive/yes`. \nIf `quality` isn't explicitly specified, the plugin will use `quality/smart` by default.\n\n## Usage\n\n**Option 1**. Use the `UploadcareImage` component and leave us the rest ;)\n```tsx\nimport UploadcareImage from '@uploadcare/nextjs-loader';\n\n\u003cUploadcareImage\n  alt=\"A test image\"\n  src=\"https://your-domain/image.jpg\"\n  width=\"400\"\n  height=\"300\"\n/\u003e\n```\nThe `UploadcareImage` component supports the same parameters as the Next `Image` component.\n\n**Option 2**. Pass `uploadcareLoader` to the `Image` component:\n\n```tsx\nimport Image from 'next/image';\nimport { uploadcareLoader } from '@uploadcare/nextjs-loader';\n\n\u003cImage\n  alt=\"A test image\"\n  src=\"https://your-domain/image.jpg\"\n  width=\"400\"\n  height=\"300\"\n  quality=\"80\"\n  loader={uploadcareLoader}\n/\u003e\n```\n\n**Option 3 (Next.js v13+ only)**. Use the [`loaderFile` setting][loader-file] to enable Uploadcare image loader for all images by default.\n\n1. Configure the `loaderFile` in your `next.config.js` like the following:\n\n```js\nmodule.exports = {\n  images: {\n    loader: 'custom',\n    loaderFile: './node_modules/@uploadcare/nextjs-loader/build/loader.js',\n  },\n}\n```\n\n2. Use `Image` as usual, with Uploadcare loader enabled implicitly:\n\n```tsx\nimport Image from 'next/image';\n\n\u003cImage\n  alt=\"A test image\"\n  src=\"https://your-domain/image.jpg\"\n  width=\"400\"\n  height=\"300\"\n  quality=\"80\"\n/\u003e\n```\n\n**Option 4**. Use the [next-image-loader](https://www.npmjs.com/package/next-image-loader) plugin to enable Uploadcare image loader for all images by default\n\nIn that case, you may not need the `loader: \"custom\"` setting in your `next.config.js`.\n\n1. Install [next-image-loader](https://www.npmjs.com/package/next-image-loader) and enable it as described in its README.\n\n2. Create `image-loader.config.js` in the project root (in the same directory as `next.config.js`)\nand add this code to it:\n\n```js\n// image-loader.config.js\nimport { imageLoader } from 'next-image-loader/build/image-loader';\nimport { uploadcareLoader } from '@uploadcare/nextjs-loader';\n\nimageLoader.loader = uploadcareLoader;\n```\n\n3. Use `Image` as usual, with Uploadcare loader enabled implicitly:\n\n```tsx\nimport Image from 'next/image';\n\n\u003cImage\n  alt=\"A test image\"\n  src=\"https://your-domain/image.jpg\"\n  width=\"400\"\n  height=\"300\"\n  quality=\"80\"\n/\u003e\n```\n\nPlease note that you can still use any other loader for a separate image like this:\n\n```tsx\nimport Image from 'next/image';\nimport anotherLoader from '[another-loader-project-name]';\n\n\u003cImage\n  alt=\"A test image\"\n  src=\"https://your-domain/image.jpg\"\n  width=\"400\"\n  height=\"300\"\n  quality=\"80\"\n  loader={anotherLoader}\n/\u003e\n```\n\nwhere `anotherLoader` will be used instead of the Uploadcare loader for this particular image.\n\n## Props\n\n### `placeholder` and `blurDataURL`\n\n[Read Next.js Image Component docs](https://nextjs.org/docs/api-reference/next/image#placeholder) about `placeholder` and `blurDataURL`.\n\nThere are two possible use cases:\n\n  1. [When `src` is a string](#when-src-is-a-string)\n  2. [When `src` is a static import](#when-src-is-a-static-import)\n\n#### When `src` is a string\n\nIf you pass `placeholder=\"blur\"` to the `Image` or `UploadcareImage` component, the `blurDataURL` property will be used as the placeholder. In this case you must provide the `blurDataURL` property using our `getBlurDataURL` server-side helper.\n\nHere is the `getBlurDataURL` interface:\n\n```ts\nfunction getBlurDataURL(\n  src: string,\n  width = 10,\n  quality = 1\n): Promise\u003cstring\u003e\n```\n\nUsage example:\n\n```tsx\nimport UploadcareImage, { getBlurDataURL } from '@uploadcare/nextjs-loader';\n\nconst BLUR_IMAGE_URL = \"https://your-domain/image.jpg\"\n\nexport const getStaticProps = async () =\u003e {\n  const blurDataURL = await getBlurDataURL(BLUR_IMAGE_URL);\n\n  return {\n    props: { blurDataURL }\n  };\n};\n\nexport default ({ blurDataURL }) =\u003e {\n  return (\n    \u003cUploadcareImage\n      alt=\"Blurred image\"\n      src={BLUR_IMAGE_URL}\n      width=\"400\"\n      height=\"300\"\n      placeholder=\"blur\"\n      blurDataURL={blurDataURL}\n    /\u003e\n  )\n}\n```\n\n#### When `src` is a static import\n\nYou can use both `UploadcareImage` and `Image` component with custom loader. In this case Next.js will generate base64 encoded image for `blurDataURL` automatically during build time.\n\n```tsx\nimport staticImage from 'image.jpg'\n\n\u003cUploadcareImage\n  alt=\"A test image\"\n  src={staticImage}\n  width=\"400\"\n  height=\"300\"\n  quality=\"80\"\n  placeholder=\"blur\"\n/\u003e\n```\n\n## Notes\n\n- If you have jpegs larger than 3000px and you want loader to resize them up to 5000px, you need to pass filename with `jpeg` or `jpg`  extension to the src url. See [Output image dimensions docs](https://uploadcare.com/docs/transformations/image/#dimensions) for more details. When no filename provided, we'll treat the image as non-jpeg and can resize it up to 3000px only.\n\n- If you pass a local image url, the loader returns it AS IS if the app is run in the development mode or if the `NEXT_PUBLIC_UPLOADCARE_APP_BASE_URL` is not set.\n\n- Next.js Image component allows numeric only `quality` value. Uploadcare CDN supports string-based quality only (see [our docs](https://uploadcare.com/docs/transformations/image/compression/#operation-quality)). So numeric quality values will be mapped onto string ones using the following intervals:\n\n  - 1-38 - lightest\n  - 39-70 - lighter\n  - 71-80 - normal\n  - 81-88 - better\n  - 89-100 - best\n\n## Known Issues\n\n**Issue 1:** Console warning like this:\n\u003e Image with src \"${src}\" has a \"loader\" property that does not implement width. Please implement it or use the \"unoptimized\" property instead.\nRead more: https://nextjs.org/docs/messages/next-image-missing-loader-width\n\nNext checks whether the image url which loader generates has the exact value which user passed through the `width` property of the `Image` component. And because the Uploadcare loader doesn't process SVG and GIF images, it just returns the same `src` value without adding any transformation parameters to it (including `width`). That's why Next reports the console warning.\n\n**Fix:** Ignore the warning for now.\n\n## Links\n\n- [Uploadcare image compression documentation][uploadcare-transformation-image-compression-docs]\n- [Uploadcare File Uploader for React](https://github.com/uploadcare/react-widget)\n\n[test-status-img]: https://github.com/uploadcare/nextjs-loader/actions/workflows/test-and-lint.yml/badge.svg\n[npm-img]: https://img.shields.io/npm/v/@uploadcare/nextjs-loader.svg\n[npm-link]: https://www.npmjs.com/package/@uploadcare/nextjs-loader\n[demo-link]: https://uploadcare-nextjs-loader.netlify.app/\n[uploadcare-transformation-image-compression-docs]: https://uploadcare.com/docs/transformations/image/compression/?utm_source=github\u0026utm_campaign=nextjs-loader\n[docs-custom-proxy-endpoint]: https://uploadcare.com/docs/delivery/proxy/#usage-endpoint\n[last-next-12-release]: https://github.com/uploadcare/nextjs-loader/tree/v0.4.0\n[loader-file]: https://nextjs.org/docs/api-reference/next/image#loader-configuration\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuploadcare%2Fnextjs-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuploadcare%2Fnextjs-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuploadcare%2Fnextjs-loader/lists"}