{"id":25731333,"url":"https://github.com/hieunc229/express-imgwiz","last_synced_at":"2025-05-07T16:25:28.645Z","repository":{"id":36789333,"uuid":"230372572","full_name":"hieunc229/express-imgwiz","owner":"hieunc229","description":"Resize, format images on-the-fly middleware for expressjs","archived":false,"fork":false,"pushed_at":"2022-02-18T09:02:54.000Z","size":134,"stargazers_count":29,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-25T17:49:29.029Z","etag":null,"topics":["express-middleware","expressjs","image-processing","photos","resize-images","sharp","thumbnail","thumbnail-generator"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hieunc229.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}},"created_at":"2019-12-27T04:24:33.000Z","updated_at":"2024-05-21T08:28:15.000Z","dependencies_parsed_at":"2022-08-08T17:01:43.130Z","dependency_job_id":null,"html_url":"https://github.com/hieunc229/express-imgwiz","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hieunc229%2Fexpress-imgwiz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hieunc229%2Fexpress-imgwiz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hieunc229%2Fexpress-imgwiz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hieunc229%2Fexpress-imgwiz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hieunc229","download_url":"https://codeload.github.com/hieunc229/express-imgwiz/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252914112,"owners_count":21824313,"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-middleware","expressjs","image-processing","photos","resize-images","sharp","thumbnail","thumbnail-generator"],"created_at":"2025-02-26T02:45:55.754Z","updated_at":"2025-05-07T16:25:28.624Z","avatar_url":"https://github.com/hieunc229.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"imgwiz.svg\" height=\"140\"/\u003e\n\n# express-imgwiz\n\nFormat, resize images on-the-fly for `expressjs`. `express-imgwiz` use `sharp` underneat. It comes as both [middleware](#use-as-a-middleware-serve-static-files) and [request handler](#use-as-a-handler-serve-photos-from-urls).\n\nTips: Use with a CDN service to not re-generate image every time a request comes in. Remember to set cache TTL for a long period. If you are using Cloudflare, set the option to cache everything.\n\nExample: [resized image url](https://wiz.saltar.co/photos/?url=https://i.imgur.com/MBDUWNw.jpg\u0026sharpen=true\u0026fm=png\u0026h=100)\n\n![resized image](https://wiz.saltar.co/photos/?url=https://i.imgur.com/MBDUWNw.jpg\u0026sharpen=true\u0026fm=png\u0026h=100)\n\n\n# 1. Installation\n\n`express-imgwiz` is available as a npm package. You can install via `npm` or `yarn` as normal\n\n```ssh\n// install using npm\n$ npm install express-imgwiz\n\n// install using yarn\n$ yarn add express-imgwiz\n```\n\n# 2. How to use\n\nYou can use `express-imgwiz` as either a middleware or a handler. Note that they took the same arguments, but there is a `/:path` param when using as `handler`.\n\n- Arguments:\n    - `staticDir` (string, required): your static image directory \n    - `cacheDir` (string): save generated file on disk into the given directory\n\n### 2.1. Example using as middleware\n\n```js\n\n// For ES6 syntax\nimport { imgWizMiddleware } from \"express-imgwiz\";\nimport path from \"path\";\n\n// Or vanila nodejs syntax\nconst { imgWizMiddleware } = require(\"express-imgwiz\");\nconst path = require(\"path\")\n\napp.use(\"/photos\", imgWizMiddleware({ \n    staticDir: path.join(__dirname, \"static\"), // comment out to disable serving static files\n    cacheDir: path.join(__dirname, \"cached\") // comment out to disable local caching\n}))\n```\n\n### 2.2. Example using as handler\n\n```js\n\n// For ES6 syntax\nimport { imgWizHandler } from \"express-imgwiz\";\nimport path from \"path\";\n\n// Or vanila nodejs syntax\nconst { imgWizHandler } = require(\"express-imgwiz\");\nconst path = require(\"path\")\n\napp.get(\"/photos/:path\", imgWizHandler({ \n    staticDir: path.join(__dirname, \"static\"), // comment out to disable serving static files\n    cacheDir: path.join(__dirname, \"cached\") // comment out to disable local caching\n}))\n```\n\n### 2.3. Available transform options:\n\n```js\n- `h` (number): resize height (h=460)\n- `w` (number): resize width (w=640)\n- `q` (number): quality (q=80)\n- `fit` (\"cover\" | \"contain\" | \"fill\" | \"inside\" | \"outside\"): resize fit\n- `position` (\"top\" | \"right top\" | \"right\" | \"right bottom\" | \"bottom\" | \"bottom left\" | \"left top\"): resize position\n- `background`: (string): background colour when using a `fit=contain` (background=blue, background=#ffffff, background=(139,195,74,0.4))\n\n- `sharpen` (\"true\" | \"sigma ?, flat (1), jagged (2)\"): sharpen target image (sharpen=true, [view more about sharpen](https://sharp.pixelplumbing.com/en/stable/api-operation/#sharpen))\n- `fm` (\"webp\" | \"jpg\" | \"jpeg\" | \"tiff\" | \"png\"): format target image\n- `kernel` (\"nearest\" | \"cubic\" | \"mitchell\" | \"lanczos2\" | \"lanczos3\"): image kernel option\n- `enlarge` (\"true\" | \"false\"): enlarge image if given size is bigger than actual size\n- `blur` (\"true\" or number (0.1 - 1000)): blur image\n- `url` (string, optional): the target photo URL. If no `url` is specify, the library will look up on `staticDir` if enabled. Note: Use `encodeURIComponent` if `url` has query, otherwise it will fail. For example: `encodeURIComponent(\"https://host.com/photo.png?quey=value\")`\n```\n\n```js\nExample URL using transform queries\n\n// Serving a static file image: \n// https://yourdomain.com/photos/image-file.png\u0026fm=png\u0026q=80\u0026sharpen=true\n\n// Get image from a URL: \n// https://yourdomain.com/photos/?url=https://imagehost.com/image-file.png\u0026fm=png\u0026q=80\u0026sharpen=true\n```\n\n### 2.4. Enviroment Variables\n\n- `process.env.EXPRESS_WIZ_CACHE_AGE` (number): Set caching age in seconds (default `31557600`)\n- `process.env.EXPRESS_WIZ_404_IMAGE` (string): Set a path to 404 error image (default `undefined`). _Note: Path is relative to the root directory, and only `png`,`jpeg` or `jpg` image is accepted to avoid unnecessary minetype checking_\n\n# 3. Changelog\n\n- v0.1.4: handle static images in sub-directory, add error when request a non-existing image using url\n- v0.1.3: added error handlers and `EXPRESS_WIZ_404_IMAGE` to display a default image \n- v0.1.2: combine codes into a `handleRequest`, update getting `mine` method, clean up code\n- v0.1.1: add file extension when it doesn't included in url\n- v0.1.0: fix serving staticc `svg` file\n- v0.0.9: fix serving local `svg` file, clean up codes\n- v0.0.8: fix `.svg` image error, added `background` option (thanks to @TheAndroidGuy)\n- v0.0.6-0.0.7: code improvement\n- v0.0.5: added local cache\n- v0.0.4: update server response status code\n- v0.0.3: added local cache\n- v0.0.1-v0.0.2: intiate project\n\nFeel free to ask or give feedback. Thank you!\n\n# 4. TODO\n\nWrite tests. Cases should be tested:\n\n- Transform format querires\n\n- Serve local images\n    - Serve svg\n    - Serve other images\n\n- Serve static file for sub directory\n    - static file without query\n    - static file with query\n\n- Serve image using URL\n    - Serve svg\n    - Serve svg with queries (should exclude query)\n    - Serve image\n    - Serve image with queries\n\n- Serving non-existing image (404)\n    - Non-existing image using URL\n    - Non-existing svg\n    - Non-existing image","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhieunc229%2Fexpress-imgwiz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhieunc229%2Fexpress-imgwiz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhieunc229%2Fexpress-imgwiz/lists"}