{"id":32358679,"url":"https://github.com/ciyoxe/nuxt-image-optimizer","last_synced_at":"2026-04-12T07:32:55.620Z","repository":{"id":319989752,"uuid":"1080357497","full_name":"Ciyoxe/nuxt-image-optimizer","owner":"Ciyoxe","description":"On‑demand image optimization for Nuxt. Serves responsive, cached images with CLS‑safe placeholders via a simple `\u003co-img\u003e` component and HTTP endpoints powered by Sharp.","archived":false,"fork":false,"pushed_at":"2025-10-21T09:06:51.000Z","size":151,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-21T11:11:54.861Z","etag":null,"topics":["frontend","nuxt","nuxt-module","nuxt3","nuxt4","optimization","vue","web"],"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/Ciyoxe.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-21T08:53:06.000Z","updated_at":"2025-10-21T09:06:55.000Z","dependencies_parsed_at":"2025-10-21T11:12:01.248Z","dependency_job_id":"dc90cc56-584e-4d00-af4e-7b477951dcef","html_url":"https://github.com/Ciyoxe/nuxt-image-optimizer","commit_stats":null,"previous_names":["ciyoxe/nuxt-image-optimizer"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Ciyoxe/nuxt-image-optimizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ciyoxe%2Fnuxt-image-optimizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ciyoxe%2Fnuxt-image-optimizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ciyoxe%2Fnuxt-image-optimizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ciyoxe%2Fnuxt-image-optimizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ciyoxe","download_url":"https://codeload.github.com/Ciyoxe/nuxt-image-optimizer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ciyoxe%2Fnuxt-image-optimizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280664280,"owners_count":26369795,"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","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["frontend","nuxt","nuxt-module","nuxt3","nuxt4","optimization","vue","web"],"created_at":"2025-10-24T13:29:25.091Z","updated_at":"2025-10-24T13:29:25.898Z","avatar_url":"https://github.com/Ciyoxe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nuxt Image Optimizer\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![License][license-src]][license-href]\n[![Nuxt][nuxt-src]][nuxt-href]\n\nOn‑demand image optimization module for Nuxt. Serves responsive, cached images with CLS‑safe placeholders via a simple `\u003co-img\u003e` component and HTTP endpoints powered by Sharp.\n\n## Features\n\n- In‑process image optimization (via Sharp) and caching with background auto‑refresh and LRU‑like eviction.\n- Responsive `srcset`/`sizes` with configurable media keys (`xs`–`xxl`)\n- CLS‑safe placeholders and preloading\n- SSR-time sizes and aspect-ratio probing\n- Domain allow‑list for remote images, supports local files from `public/`\n\n## Quick Start\n\nInstall:\n\n```bash\nnpm i nuxt-image-optimizer\n```\n\nEnable and minimally configure in `nuxt.config`:\n\n```ts\n// nuxt.config.ts\nexport default defineNuxtConfig({\n  modules: [\n    'nuxt-image-optimizer',\n  ],\n  cachedImageOptimizer: {\n    domains: ['images.example.com'],\n  },\n});\n```\n\n## How it works:\n\n- Nitro server proxies all image requests to the custom endpoint.\n- The endpoint validates parameters, then:\n  - If cached, serves the optimized image.\n  - If not cached, returns the original image immediately and adds optimization task to queue.\n- Background maintenance periodically refreshes old cached images (background tasks are also queued).\n- Eviction removes the least-used cached images using aging algorithm to fit in cache size limit.\n\n## Component usage\n\n```vue\n\u003ctemplate\u003e\n  \u003co-img\n    src=\"https://images.example.com/photo.jpg\"\n    alt=\"A photo\"\n    role=\"img\"\n    format=\"webp\"\n    quality=\"75\"\n    srcset=\"320,640,1024\"\n    sizes=\"sm:100vw,50vw\"\n    placeholder=\"30,320\"\n    @load=\"onLoad\"\n    @load:placeholder=\"onPlaceholder\"\n    @error=\"onError\"\n  /\u003e\n\u003c/template\u003e\n```\n\nProps:\n- `src`: Image URL. Local `/...` paths work out of the box; remote hosts must be allowed in config.\n- `format`: Desired output format (webp/avif/jpeg/png). If omitted, server uses `conversion.format` from config.\n- `quality`: Image quality (1–100). If omitted, server uses `conversion.quality` from config.\n- `srcset`: Comma‑separated widths for responsive images, e.g. \"320, 640, 1024\".\n- `sizes`: How wide the image should be at different breakpoints, e.g. \"sm:100vw, 50vw\". Breakpoints are defined in `sizes` section of config.\n- `placeholder`: Low‑quality preview to show first, in format \"quality, width, height\", e.g. \"30,320\". If prop omitted, no placeholder will be shown. Width and height are optional, if omitted, the placeholder will use size constraints from config.\n- `preload`: Adds preload link to page head.\n\nEvents:\n- `load:placeholder` — fired when the placeholder finished loading (if placeholder prop defined)\n- `load` — fired when the final image finished loading\n- `error` — fired if the final image fails to load (note, that placeholder loading error will be ignored, only the final image triggers it)\n\nStyles:\n- `data-status` attribute — \"placeholder\", \"completed\" or \"error\".\n- `--original-width` var — original image width (not sized down by optimizer)\n- `--original-height` var — original image height\n- `--aspect-ratio` var — original image aspect ratio\n\nSome behaviour diffs from default image component:\n- If no `alt` or `role` attributes provided, the component will use `role=\"presentation\"`.\n- Loading and error events are always emitted, even if Vue was not initialized before. In such case, they will be triggered in `onMounted` hook.\n\n\n## Configuration\n\n```ts\n// defaults\n{\n  cache: {\n    // if queue is full, new optimization tasks will be rejected\n    queueSize: 1000,\n    // pause between optimization works to reduce CPU load, format can be like '5s', '100ms', '1m', '2h'\n    queueTimeout: '5s',\n    // 'in-memory' for memory cache, or storage path for filesystem cache, like '.cache/oimgs'\n    storagePath: 'in-memory',\n    // max cache size, format can be like '100KB', '122MB', '14GB'\n    maxSize: '20MB',\n    // max number of cached image sizes (only width and height caching for ssr sizes probing)\n    sizeCacheMaxCount: 10000,\n  },\n  // background image refreshing, active only if main queue is empty\n  autoRefresh: {\n    // background refresh interval, cached images will be refreshed every 30 minutes by default\n    // WARN: avif images processing can be very slow (up to 10 seconds for large ones) and may occur queue overflows\n    maxAge: '30m',\n    // if queue is full, new refresh tasks will be rejected\n    queueSize: 10,\n    // pause between refresh works to reduce CPU load\n    queueTimeout: '5s',\n  },\n  conversion: {\n    // 'webp' | 'avif' | 'jpeg' | 'png', overwritten by component prop\n    format: 'webp',\n    // 1..100, overwritten by component prop\n    quality: 75,\n    // default width, overwritten by component prop\n    width: 4096,\n    // default height, overwritten by component prop\n    height: 4096,\n    // codec effort, 0..10 - higher is slower but smaller file sizes\n    cpuEffort: 6,\n  },\n  // media queries list to use in 'sizes' prop\n  // you can define your own keys, like '2xl'\n  sizes: {\n    xs: '(width \u003c 320px)',\n    sm: '(width \u003c 640px)',\n    md: '(width \u003c 768px)',\n    lg: '(width \u003c 1024px)',\n    xl: '(width \u003c 1280px)',\n    xxl: '(width \u003c 1280px)',\n  },\n  // allow‑list for remote hosts\n  domains: [],\n}\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Develop with playground\nnpm run dev\n\n# Type check\nnpm run test:types\n\n# Lint\nnpm run lint\n```\n\n## License\n\nMIT\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/nuxt-image-optimizer/latest.svg?style=flat\u0026colorA=020420\u0026colorB=00DC82\n[npm-version-href]: https://npmjs.com/package/nuxt-image-optimizer\n[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-image-optimizer.svg?style=flat\u0026colorA=020420\u0026colorB=00DC82\n[npm-downloads-href]: https://npm.chart.dev/nuxt-image-optimizer\n[license-src]: https://img.shields.io/npm/l/nuxt-image-optimizer.svg?style=flat\u0026colorA=020420\u0026colorB=00DC82\n[license-href]: ./LICENSE\n[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js\n[nuxt-href]: https://nuxt.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fciyoxe%2Fnuxt-image-optimizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fciyoxe%2Fnuxt-image-optimizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fciyoxe%2Fnuxt-image-optimizer/lists"}