{"id":23282141,"url":"https://github.com/bitpatty/next-image-s3-imgproxy-loader","last_synced_at":"2025-07-19T01:03:56.167Z","repository":{"id":37820139,"uuid":"413390247","full_name":"BitPatty/next-image-s3-imgproxy-loader","owner":"BitPatty","description":"nextjs next/image extension for imgproxy (S3 connections only)","archived":false,"fork":false,"pushed_at":"2025-07-15T10:54:47.000Z","size":2112,"stargazers_count":39,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-16T00:42:52.326Z","etag":null,"topics":["imgproxy","nextjs"],"latest_commit_sha":null,"homepage":"","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/BitPatty.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2021-10-04T11:21:13.000Z","updated_at":"2025-07-15T10:54:49.000Z","dependencies_parsed_at":"2023-02-15T07:45:29.851Z","dependency_job_id":"3e97b7cd-d9d4-4e85-8a03-c4f72c08a2b1","html_url":"https://github.com/BitPatty/next-image-s3-imgproxy-loader","commit_stats":{"total_commits":583,"total_committers":4,"mean_commits":145.75,"dds":0.176672384219554,"last_synced_commit":"3d7dca8b41d46a38ccecf9807fc2090b61c5540a"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/BitPatty/next-image-s3-imgproxy-loader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitPatty%2Fnext-image-s3-imgproxy-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitPatty%2Fnext-image-s3-imgproxy-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitPatty%2Fnext-image-s3-imgproxy-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitPatty%2Fnext-image-s3-imgproxy-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BitPatty","download_url":"https://codeload.github.com/BitPatty/next-image-s3-imgproxy-loader/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BitPatty%2Fnext-image-s3-imgproxy-loader/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265866190,"owners_count":23840937,"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":["imgproxy","nextjs"],"created_at":"2024-12-20T00:14:44.310Z","updated_at":"2025-07-19T01:03:56.146Z","avatar_url":"https://github.com/BitPatty.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `next/image` loader for imgproxy (S3)\n\nThis library is a layer on top of the the [next/image](https://nextjs.org/docs/api-reference/next/image) component, which allows you to load images from an [imgproxy](https://github.com/imgproxy/imgproxy) instance connected to an S3. With this library, the NextJS server acts as a middleman between the client and the imgproxy instance to perform additional tasks, such as applying signatures and/or guards before loading an image.\n\n\u003e **If you want to access the imgproxy instance directly from your client you can simply use the `next/image` component itself - no need to install this library** (you might wanna look into the [imgproxy-url-builder](https://github.com/BitPatty/imgproxy-url-builder) to build the request URL however).\n\n![Request Flow](https://github.com/BitPatty/next-image-s3-imgproxy-loader/raw/master/request_flow.png)\n\n## Sample Usage\n\n\u003e You can find additional examples in the [demo project](https://github.com/BitPatty/next-image-s3-imgproxy-loader/blob/master/example/pages/index.tsx).\n\n### Installation\n\nYou can install the package via npm:\n\n```sh\nnpm install --save @bitpatty/next-image-s3-imgproxy-loader\n```\n\n### Registering the endpoint\n\n#### Method 1: Custom Server\n\nThe library by default proxies request through a custom endpoint. To register the endpoint create a [custom server](https://nextjs.org/docs/advanced-features/custom-server) in your project and add the following lines:\n\n```js\n// server.js\nconst imgProxy = require('@bitpatty/next-image-s3-imgproxy-loader');\n\napp.prepare().then(() =\u003e {\n  createServer((req, res) =\u003e {\n    const parsedUrl = parse(req.url, true);\n    const { pathname, query } = parsedUrl;\n\n    if (pathname === imgProxy.IMGPROXY_ENDPOINT) {\n      // Add other middleware here, such as auth guards\n      // ...\n      imgProxy.handle(\n        new URL('\u003curl to your imgproxy instance\u003e'),\n        query,\n        res,\n        // (Optional) Additional configuration options\n        {\n          // (Optional) If your imgproxy uses signatures, specify\n          // the key and salt here\n          signature: {\n            // (Required) The IMGPROXY_KEY (hex encoded)\n            key: '\u003cimgproxy secret\u003e',\n            // (Required) The IMGPROXY_SALT (hex encoded)\n            salt: '\u003cimgproxy salt\u003e',\n          },\n          // (Optional) If your imgproxy instance uses\n          // the IMGPROXY_SECRET, specify the token here\n          authToken: '\u003cmy-token\u003e',\n          // (Optional) If you wanna restrict access to specific\n          // buckets add an array of valid bucket names\n          bucketWhitelist: ['\u003cmy-bucket\u003e'],\n          // (Optional) A list of imgproxy headers that should be\n          // forwarded through the imgproxy endpoint\n          forwardedHeaders: ['\u003cmy-header\u003e'],\n          // (Optional) An object containing additional request\n          // headers that should be sent to the imgproxy endpoint\n          requestHeaders: {\n            'My-Header': 'My-Value',\n            // ...\n          },\n          // (Optional) The logger configuration. If you want additional\n          // debug output you can adjust the log level.\n          logging: {\n            // (Optional) The logger to use (defaults to console)\n            // The logger should implement the signature for\n            // for console.debug, console.warn and console.error\n            logger: console,\n            // (Optional) The log level, must be one of\n            // 'debug', 'warn' or 'error' (defaults to 'error')\n            level: 'debug',\n          },\n        },\n      );\n    } else {\n      handle(req, res, parsedUrl);\n    }\n  }).listen(3000, (err) =\u003e {\n    if (err) throw err;\n    console.log('\u003e Ready on http://localhost:3000');\n  });\n});\n```\n\n#### Method 2: API Endpoint\n\nFor serverless environments you can use an API endpoint instead of a custom endpoint.\n\nThe setup is similar, register your endpoint as follows:\n\n```typescript\n// pages/api/image.ts\nimport { NextApiRequest, NextApiResponse } from 'next';\nimport { handle } from '@bitpatty/next-image-s3-imgproxy-loader';\n\nconst handler = (req: NextApiRequest, res: NextApiResponse): void =\u003e {\n  if (req.method !== 'GET') {\n    res.statusCode = 405;\n    res.send('');\n    return;\n  }\n\n  handle(new URL('http://localhost:4000/'), req.query, res, {\n    // Handler Options\n  });\n};\n\nexport default handler;\n```\n\nWith this method, you have to [supply the endpoint](#overriding-the-endpoint) to the `\u003cProxyImage\u003e` component.\n\n## Using the component\n\nAfter registering the endpoint you can use the `\u003cProxyImage /\u003e` component as you would with the `Image` component from `next/image`, except that you need to provide a file (`\u003cbucketname\u003e/\u003cfilename\u003e`) instead of `src` and optional proxy params for image transformations/optimizations.\n\n```tsx\nimport ProxyImage from '@bitpatty/next-image-s3-imgproxy-loader';\nimport pb from '@bitpatty/imgproxy-url-builder';\n\n\u003cProxyImage\n  file=\"mybucket/myfile.png\"\n  proxyParams={pb().rotate(180).blur(10).build()}\n/\u003e;\n```\n\n\u003e Note: The layout prop is automatically set to 'fill' if no width is set\n\n## Using the raw path\n\nIn case using the component is not an option, you can instead use the image path itself, by utilizing the `buildProxyImagePath` function.\n\n```tsx\nimport { buildProxyImagePath } from '@bitpatty/next-image-s3-imgproxy-loader';\nimport pb from '@bitpatty/imgproxy-url-builder';\n\nconst imagePath = buildProxyImagePath('test-bucket/test-image.png', {\n  proxyParams: pb().blur(10).build(),\n});\n\n\u003cimg src={imagePath} /\u003e;\n```\n\nor as background image\n\n```tsx\nimport { buildProxyImagePath } from '@bitpatty/next-image-s3-imgproxy-loader';\nimport pb from '@bitpatty/imgproxy-url-builder';\n\nconst imagePath = buildProxyImagePath('test-bucket/test-image.png', {\n  proxyParams: pb().blur(10).format('jpg').build(),\n});\n\n\u003cdiv\n  style={{\n    backgroundImage: `url(${imagePath})`,\n    backgroundSize: 'cover',\n  }}\n\u003e\n  {/* Content */}\n\u003c/div\u003e;\n```\n\n## Overriding the endpoint\n\nIf you use a different endpoint than the one provided by `IMGPROXY_ENDPOINT` you can override the endpoint used by the component by providing the `endpoint` property. `endpoint` can be both a path but also a URL.\n\n```tsx\n\u003cProxyImage file=\"mybucket/myfile.png\" endpoint=\"/my-endpoint\" /\u003e;\n\n// Or\nbuildProxyImagePath('test-bucket/test-image.png', {\n  endpoint: '/my-endpoint',\n});\n```\n\n## Forwarded Headers\n\nBy default, the following imgproxy headers will be forwarded in the response to the client:\n\n```json\n[\n  \"date\",\n  \"expires\",\n  \"content-type\",\n  \"content-length\",\n  \"cache-control\",\n  \"content-disposition\",\n  \"content-dpr\"\n]\n```\n\nIf you want to forward a different set of headers you can use the `forwardedHeaders` option to specify a custom list of headers. Note that if `forwardedHeaders` is specified, all headers not specified in the list will be omitted in the response.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitpatty%2Fnext-image-s3-imgproxy-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitpatty%2Fnext-image-s3-imgproxy-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitpatty%2Fnext-image-s3-imgproxy-loader/lists"}