{"id":14676815,"url":"https://github.com/pmb0/express-sharp","last_synced_at":"2025-04-06T00:09:26.008Z","repository":{"id":2615177,"uuid":"46784613","full_name":"pmb0/express-sharp","owner":"pmb0","description":"🏞 Real-time image processing for your express application.","archived":false,"fork":false,"pushed_at":"2024-01-17T20:21:33.000Z","size":24606,"stargazers_count":140,"open_issues_count":30,"forks_count":31,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-03-14T17:14:38.932Z","etag":null,"topics":["express","express-sharp","image-proxy","image-resizer","libvips","sharp"],"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/pmb0.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":"2015-11-24T10:33:19.000Z","updated_at":"2024-06-11T13:13:57.407Z","dependencies_parsed_at":"2024-01-14T06:55:34.390Z","dependency_job_id":"60700440-7c49-4d75-afd1-778395254804","html_url":"https://github.com/pmb0/express-sharp","commit_stats":{"total_commits":837,"total_committers":12,"mean_commits":69.75,"dds":"0.43130227001194743","last_synced_commit":"c511a19cfe8be697709dd7c44c2b6dd752941f1d"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmb0%2Fexpress-sharp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmb0%2Fexpress-sharp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmb0%2Fexpress-sharp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmb0%2Fexpress-sharp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pmb0","download_url":"https://codeload.github.com/pmb0/express-sharp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415967,"owners_count":20935387,"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":["express","express-sharp","image-proxy","image-resizer","libvips","sharp"],"created_at":"2024-09-12T09:00:56.754Z","updated_at":"2025-04-06T00:09:25.974Z","avatar_url":"https://github.com/pmb0.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.github.com/pmb0/express-sharp/master/docs/express-sharp.gif\" width=\"100%\" /\u003e\n  \u003cp\u003eReal-time image processing for your express application.\u003c/p\u003e\n\u003c/div\u003e\n\n[![npm version](https://badge.fury.io/js/express-sharp.svg)](https://www.npmjs.com/package/express-sharp)\n[![Test Coverage][coveralls-image]][coveralls-url]\n[![Build Status][build-image]][build-url]\n\n# Description \u003c!-- omit in toc --\u003e\n\nexpress-sharp adds real-time image processing routes to your express application. Images are processed with [sharp](https://github.com/lovell/sharp), a fast Node.js module for resizing images.\n\n```\n                      express-sharp\n    Express app         endpoint          image path    transformation                \n┌─────────────────┐┌────────────────┐┌──────────────────┐ ┌────────┐\nhttps://example.com/path/to/my-scaler/images/my-image.jpg?w=100\u0026h=50\n```\n\nOriginal images are loaded via an image adapter. Currently this includes HTTP and file system adapters.\n\n# Highlights \u003c!-- omit in toc --\u003e\n\n- Fast resizing of images (see [sharp Performance](https://sharp.pixelplumbing.com/performance))\n- [Supports multiple backends, from which the original images are downloaded](#image-adapters)\n- [Supports multiple caching backends](#caching)\n- [Image URLs can be signed to prevent attacks](#url-signing)\n\n\n# Table of contents \u003c!-- omit in toc --\u003e\n\n- [Install](#install)\n- [Express server integration](#express-server-integration)\n  - [Server configuration](#server-configuration)\n  - [Image Adapters](#image-adapters)\n    - [File System](#file-system)\n    - [HTTP](#http)\n    - [Amazon S3](#amazon-s3)\n    - [Custom](#custom)\n  - [Caching](#caching)\n  - [URL signing](#url-signing)\n  - [Debug logging](#debug-logging)\n- [Client integration](#client-integration)\n- [License](#license)\n\n# Install\n\n```sh\n$ yarn add express-sharp\n```\n\nSee [sharp installation](https://sharp.pixelplumbing.com/install) for additional installation instructions.\n\n# Express server integration\n\nExample *app.js* (See also `example/app.ts` in this project):\n\n```js\nimport express from 'express'\nimport { expressSharp, FsAdapter, HttpAdapter } from 'express-sharp'\n\nconst app = express()\n\n// Fetch original images via HTTP\napp.use(\n  '/some-http-endpoint',\n  expressSharp({\n    imageAdapter: new HttpAdapter({\n      prefixUrl: 'http://example.com/images',\n    }),\n  })\n)\n\n// Alternative: Load original images from disk\napp.use(\n  '/fs-endpoint',\n  expressSharp({\n    imageAdapter: new FsAdapter(path.join(__dirname, 'images')),\n  })\n)\n\napp.listen(3000)\n```\n\nRender `/images/image.jpg` with 400x400 pixels:\n\n```sh\ncurl http://my-server/express-sharp-endpoint/images/image.jpg?w=400\u0026h=400\n```\n\nSame as above, but with 80% quality, `webp` image type and with progressive enabled:\n\n```sh\ncurl http://my-server/express-sharp-endpoint/images/image.jpg?w=400\u0026h=400\u0026f=webp\u0026q=80\u0026p\n```\n\n## Server configuration\n\n```js\nimport { expressSharp } from 'express-sharp'\n\napp.use('/some-http-endpoint', expressSharp(options))\n```\n\nSupported `options`:\n\n| Name | Description | Default |\n|------|-------------|---------|\n| `autoUseWebp` | Specifies whether images should automatically be rendered in webp format when supported by the browser. | `true` |\n| `cache` | If specified, the [keyv cache]((https://github.com/lukechilds/keyv)) configured here is used to cache the retrieval of the original images and the transformations. | - |\n| `cors` | Any valid [CORS configuration option](https://expressjs.com/en/resources/middleware/cors.html) | - |\n| `imageAdapter` | Configures the image adapter to be used (see below). Must be specified. | - |\n| `secret` | If specified, express-sharp will validate the incoming request to verify that a valid signature has been provided. The secret is used to compute this signature. | - |\n\n## Image Adapters\n\nexpress-sharp contains the following standard image adapters.\n\n### File System\n\nWith this adapter original images are loaded from the hard disk.\n\n```js\nimport { FsAdapter } from 'express-sharp'\n\nconst adapter = new FsAdapter('/path/to/images')\n```\n\n### HTTP\n\nLoads original images via HTTP. To use this adapter, the peer dependency `got` must be installed:\n\n```sh\n$ yarn add got\n```\n\n```js\nimport { HttpAdapter } from 'express-sharp'\n\nconst adapter = new HttpAdapter({\n  prefixUrl: 'http://localhost:3000/images',\n})\n```\n\nThe constructor can be passed any [got options](https://github.com/sindresorhus/got#options).\n\n### Amazon S3\n\nLoads images from Amazon S3. To use this adapter, the peer dependency `aws-sdk` must be installed:\n\n```sh\n$ yarn add aws-sdk\n```\n\n```js\nimport { S3Adapter } from 'express-sharp'\n\nconst bucketName = 'my-bucketname'\nconst adapter = new S3Adapter(bucketname)\n```\n\nThe AWS SDK expects the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be set.\n\n### Custom\n\nIf you needed your own adapters can be used. An \"image adapter\" is a class that implements the `ImageAdapter` interface:\n\n```ts\nimport { ImageAdapter } from 'express-sharp'\n\nclass MyAdapter implements ImageAdapter {\n  async fetch(id: string): Promise\u003cBuffer | undefined\u003e {\n    if (imageDoesNotExist(id)) {\n      return undefined\n    }\n\n    return Buffer.from('my image blob')\n  }\n}\n```\n\n## Caching\n\nThe fetching of the original images and the transformations can be cached. To enable this feature, the `cache` option must be passed to the `expressSharp` middleware. Any [keyv cache stores](https://github.com/lukechilds/keyv) can be passed.\n\n\nIn-memory cache example:\n\n```js\nconst cache = new Keyv({ namespace: 'express-sharp' })\n\napp.use(\n  '/my-endpoint',\n  expressSharp({\n    cache,\n    imageAdapter: ...\n  })\n)\n```\n\nRedis example:\n\n```js\nconst cache = new Keyv('redis://', { namespace: 'express-sharp' }\n\napp.use(\n  '/my-endpoint',\n  expressSharp({\n    cache,\n    imageAdapter: ...\n  })\n)\n```\n\n## URL signing\n\nBy setting the environment variable `EXPRESS_SHARP_SIGNED_URL_SECRET` or by specifying the `secret` option when calling the `express-sharp` middleware, signed URLs are activated. This reduces the attack surface on the server, since the caller cannot produce an unlimited number of URLs that cause load on the server.\n\nIn order to compute the signature, the supplied client should be used:\n\n```js\nimport { createClient } from 'express-sharp'\n\nconst endpoint = 'https://example.com/my-express-sharp-endpoint'\nconst secret = 'test'\nconst client = createClient(endpoint, secret)\n\nconst imageUrl = client.url('/foo.png', { width: 500 })\n\n// https://example.com/my-express-sharp-endpoint/foo.png?w=500\u0026s=Of3ty8QY-NDhCsIrgIHvPvbokkDcxV8KtaYUB4NFRd8\n```\n\n## Debug logging\n\nThis project uses [debug](https://www.npmjs.com/package/debug). To display debug messages from `express-sharp`, the `DEBUG` environment variable must be exported so that it contains the value `express-sharp*`. Example:\n\n```sh\n$ export DEBUG='my-app:*,express-sharp*'\n```\n\n\n# Client integration\n\nexpress-sharp comes with a client that can be used to generate URLs for images.\n\n```js\nimport { createClient } from 'express-sharp'\n\nconst client = createClient('http://my-base-host', 'optional secret')\n\nconst originalImageUrl = '/foo.png'\nconst options = { width: 500 }\nconst fooUrl = client.url(originalImageUrl, options)\n```\n\nCurrently the following transformations can be applied to images:\n\n| Client option name | Query param name | Description |\n|--------------------|------------------|-------------|\n| quality | `q` | Quality is a number between 1 and 100 (see [sharp docs](https://sharp.pixelplumbing.com/en/stable/api-output/)). |\n| width | `w` |\n| height | `h` |\n| format | `f` | Output image format. Valid values: every valid [sharp output format string](https://sharp.pixelplumbing.com/api-output#toformat), i.e. `jpeg`, `gif`, `webp` or `raw`. |\n| progressive | `p` | Only available for jpeg and png formats. Enable progressive scan by passing `true`. |\n| crop | `c` | Setting crop to `true` enables the [sharp cropping feature](https://sharp.pixelplumbing.com/api-resize#crop). Note: Both `width` and `height` params are neccessary for crop to work. Default is `false`. |\n| trim | `t` | Setting trim to `true` enables the [sharp trim feature](https://sharp.pixelplumbing.com/api-resize#trim). |\n| gravity | `g` | When the crop option is activated you can specify the gravity of the cropping. Possible attributes of the optional `gravity` are `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center` and `centre`. Default is `center`. |\n\n# License\n\nexpress-sharp is distributed under the MIT license. [See LICENSE](./LICENSE) for details.\n\n[coveralls-image]: https://img.shields.io/coveralls/pmb0/express-sharp/master.svg\n[coveralls-url]: https://coveralls.io/r/pmb0/express-sharp?branch=master\n[build-image]: https://github.com/pmb0/express-sharp/workflows/Tests/badge.svg\n[build-url]: https://github.com/pmb0/express-sharp/actions?query=workflow%3ATests\n","funding_links":[],"categories":["TypeScript","Middleware"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmb0%2Fexpress-sharp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmb0%2Fexpress-sharp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmb0%2Fexpress-sharp/lists"}