{"id":16858660,"url":"https://github.com/verlok/responsive-images-automator","last_synced_at":"2025-03-22T06:31:17.665Z","repository":{"id":69565603,"uuid":"455590799","full_name":"verlok/responsive-images-automator","owner":"verlok","description":"Automate the analysis of your image dimensions, automate the generation of responsive images HTML code, test the outcome with puppeteer","archived":false,"fork":false,"pushed_at":"2022-12-06T14:13:54.000Z","size":3119,"stargazers_count":39,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-18T09:02:26.911Z","etag":null,"topics":["automation","hacktoberfest","performance","performance-analysis","responsive-images","web-performance","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verlok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":null,"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":"2022-02-04T15:07:01.000Z","updated_at":"2024-07-12T11:26:23.000Z","dependencies_parsed_at":"2023-09-16T06:15:27.078Z","dependency_job_id":null,"html_url":"https://github.com/verlok/responsive-images-automator","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verlok%2Fresponsive-images-automator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verlok%2Fresponsive-images-automator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verlok%2Fresponsive-images-automator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verlok%2Fresponsive-images-automator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verlok","download_url":"https://codeload.github.com/verlok/responsive-images-automator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244918500,"owners_count":20531682,"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":["automation","hacktoberfest","performance","performance-analysis","responsive-images","web-performance","workflow-automation"],"created_at":"2024-10-13T14:14:38.487Z","updated_at":"2025-03-22T06:31:15.732Z","avatar_url":"https://github.com/verlok.png","language":"JavaScript","funding_links":["https://ko-fi.com/verlok"],"categories":[],"sub_categories":[],"readme":"# Responsive images automator\n\n\u003cimg width=\"1276\" alt=\"Responsive images automator\" src=\"https://user-images.githubusercontent.com/1127721/161528200-ff6914cf-3712-4a22-a6be-cf532c197b5f.png\"\u003e\n\nResponsive images automator does 3 main things for you. It:\n\n1. **Extracts data** from your existing images\n2. **Generates responsive images tags** for you\n3. **Tests** the generated image tags\n\nHere goes some more detailed information.\n\nThere is also [this video](https://www.youtube.com/watch?v=vuWH34f6uds) from the [LazyLoad Conference 2022](https://webdirections.org/lazyload/) where I explain how to use this tool.\n\n# 1 - Extract Rendered CSS Widths\n\n\u003cimg width=\"1274\" alt=\"Extract images dimensions from your web pages\" src=\"https://user-images.githubusercontent.com/1127721/161528333-8ea71e39-3c08-4274-86a0-59e939e34e50.png\"\u003e\n\nIn this stage, responsive images automator does:\n\n- **Extract** useful information such as the `width` (in CSS pixels and in `vw` unit) from your pages, at different viewport dimensions (which you can provide)\n- **Analyse** the current intrinsic widths with calculated formulas, to help you understand the current level of optimisation of your images.\n- **Provide** an easy and intuitive way to select new intrinsic widths to optimise your images\n\n### Configuration files\n\n- `config/resolutions.json` or `config/resolutions.xlsx` (the first found is used). NOTE: If you choose to use the Excel file, there's a specific format to follow, see example in `config/examples/resolutions.xlsx`.\n- `config/images.json` or `config/images.xlsx` (the first found is used). NOTE: If you choose to use the Excel file, there's a specific format to follow, see example in `config/examples/webdev/images.xlsx`.\n- `config/blacklisted_domains.js`, a list of domains containing blocking scripts that could hinder this tool from navigating around freely.\n- `config/blacklisted_paths.js`, a list of paths to blocking scripts on your own domain that could hinder this tool from navigating around freely.\n\n### Execution\n\nAfter installing all dependencies with `npm install`, just run the following command in your terminal.\n\n```\nnpm run extract\n```\n\nA magically driven browser window will appear, doing all what was promised in the previous lines.\n\n### Output\n\nFind the extracted data in `/data/datafile.xlsx`, one worksheet per row of the images config file.\n\n## Analyse Extracted Data\n\nIn the columns of the extracted file, you will find:\n\n| Column name                | Meaning                                                                                                                                                                                                                                                                 |\n| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `current` `Intrinsic` `Width`    | The current intrinsic width, meaning the width of the downloaded images                                                                                                                                                                                                 |\n| `current` `Rendered` `Fidelity`  | The current rendered fidelity (pixel ratio), meaning the ratio between the downloaded image width and the rendered width in CSS pixel                                                                                                                                   |\n| `current` `RTI` `Fidelity` `Ratio`  | The current rendered-to-ideal fidelity ratio, meaning the ratio between the ideal fidelity ratio and the current fidelity ratio. In other words, the ideal value to find here would be 1                                                                                |\n| `current` `Evaluation`        | The evaluation of the current image intrinsic width, from BIG to POOR. It is ideal to get an `OK` here, but also a `(+)` or a `(-)` are acceptable                                                                                                                      |\n| `current` `Waste`             | This tells you how much you are wasting, in percentage. This value considers the `currentRTIFidelityRatio` AND the `usage`, so the wider the usage, the bigger the waste                                                                                                |\n| `ideal` `Intrinsic` `Width`      | The calculation of the ideal intrinsic width you would have to use to get an `OK` evaluation                                                                                                                                                                            |\n| **`chosen` `Intrinsic` `Width`** | **The proposed intrinsic width. You can and should change this value. This value will be used to generate the HTML of your responsive images**                                                                                                                          |\n| `chosen` `Rendered` `Fidelity`   | The chosen rendered fidelity (pixel ratio), meaning the ratio between the width of image that would be downloaded and the rendered width in CSS pixel                                                                                                                   |\n| `chosen` `RTI` `Fidelity` `Ratio`   | The chosen rendered-to-ideal fidelity ratio, meaning the ratio between the ideal fidelity ratio and the chosen fidelity ratio. You should try to get a value as close as possible to 1 in this cell                                                                     |\n| `chosen` `Evaluation`         | The evaluation of the chosen intrinsic width, from BIG to POOR. You should try to get an `OK` here, but also a `(+)` or a `(-)` are acceptable. You should act if you find a `BIG` or `POOR` evaluation and the resolution is used enough to generate significant waste |\n| `chosen` `Waste`              | This calculates how much you would be wasting, in percentage, with the chosen numbers. This value considers the `chosenRTIFidelityRatio` AND the `usage`, so the wider the usage, the bigger the waste                                                                  |\n\n## Time To Optimise!\n\nThis is where you, human, come into play. \nYou have to decide which intrinsic widths you want to use, with the help of the suggestion in the `IdealIntrinsicWidth` column, and change the values in the `ChosenIntrinsicWidth` column, taking into account the values ​​generated by the magic formulas in the columns on the far right.\nWhen you are done, save the file.\n\n**Don't panic!** Here are the steps you need to follow.\n\n### A - Open the data file\n\nOpen extracted data (`/data/datafile.xlsx`) in Excel.\n\n### B - Define intrinsic widths\n\nYou'll need to define ideal images' intrinsic widths in order to have a few (5 or 6) final image dimensions and minimise waste.\n\nThe magic formulas in the rightmost columns of the spreadsheet will guide you.\n\nAdjust `chosenIntrinsicWidth` where you see \"POOR\" or \"BIG\" indications in the `chosenEvaluation` column. You want to accept a \"BIG\" on rarely used resolutions, e.g. 320@2x.\n\nNow check: do you have similar `chosenIntrinsicWidth` values? If you do, group them by using one of the similar values. It is generally a good idea to use the one that corresponds to the most used resolution.\n\n### C - (Optional) Polish VW\n\nIf you have different but similar values in the `imgVW` column, it's a good idea to group them to get lighter HTML code and the same result. E.g. if you have `vw` values like `39`, `40`, `41`, you should probably set them all to `40`.\n\n### D - Repeat for each worksheet\n\nDo the above steps for each of the worksheets. In case you don't know, worksheets are the Excel tabs below the cells\n\n### E - (Optional) Multiple pages refinement\n\nReusing the same dimensions across pages will leverage CDN cache and browser cache for all of your users.\n\nSo check: do you have similar `chosenIntrinsicWidth` values ACROSS PAGES?\n\nIf you do have similar `chosenIntrinsicWidth` values, group them by using one of the similar values and repeat the process.\n\n---\n\n**Love this project? 😍 [Buy me a coffee!](https://ko-fi.com/verlok)**\n\n---\n\n# 2 - Generate Image Tags\n\n\u003cimg width=\"1276\" alt=\"Generates HTML code for responsive images\" src=\"https://user-images.githubusercontent.com/1127721/161528489-f3b153ef-da59-409c-b398-2f8f0dd17029.png\"\u003e\n\nIn this stage, responsive images automator does:\n\n- **Spin up** an HTTP server\n- **Generate the HTML** for every image using the data we have in the `data/datafile.xslx` in the configuration file\n\n### Execution\n\nAfter installing all dependencies with `npm install`, just run the following command in your terminal.\n\n```\nnpm run start\n```\n\nThis will launch the server and output a list of the URLs you can visit, like the following:\n\n```\nhttp://localhost:8080/image/{{imageName}}/\n```\n\n...with `{{imageName}}` being the name you used in `config/images.xlsx`.\n\nWhen the page will be loaded by the browser, an image will be rendered in it. \n\nUnder the rendered image, find the generated HTML code.\n\n---\n\n**Love this project? 😍 [Buy me a coffee!](https://ko-fi.com/verlok)**\n\n---\n\n# 3 - Test Generated Image Tags\n\n\u003cimg width=\"1277\" alt=\"Makes sure browsers download the correct image\" src=\"https://user-images.githubusercontent.com/1127721/161528572-d5b57969-159a-4153-b4da-eac25778784f.png\"\u003e\n\nIn this stage, responsive images automator does:\n\n- **Generate the tests** files you need\n- **Test the generated tag** to effectively check if browsers download the images of the intrinsic width you selected.\n\n### Execution\n\nAfter installing all dependencies with `npm install`, just run the following command in your terminal.\n\nTo generate test files, run the command:\n\n```\nnpm run build:tests\n```\n\nWhile the server is running in another terminal window (see `npm run start` above), run:\n\n```zsh\nnpm run test\n```\n\nThis will open an invisible browser and make sure that, at different resolutions, the downloaded image is always the one you intended.\n\n### Something is red?\n\nTests are made to understand if you made mistakes and change things accordingly. \n\nIf some test returned a red statement, read it carefully and try to understand why your browser downloaded a differnt image at that specific resolution.\n\nIf you aren't able to understand, you could open an issue and request for advice. I can't guarantee how quick I will reply, but I will reply at some point.\n\n---\n\n**Love this project? 😍 [Buy me a coffee!](https://ko-fi.com/verlok)**\n\n---\n\n### Something is broken?\n\nIf you found errors in this tool, please open an issue and report it to me. Thanks!\n\n---\n\n**Love this project? 😍 [Buy me a coffee!](https://ko-fi.com/verlok)**\n\n---\n\n## Conference Talks About This Tool\n\nI talked about this tool at [CSS Day IT conference 2022](https://2022.cssday.it/schedule/). [In this blog post](https://www.andreaverlicchi.eu/css-day-2022-talk-automating-responsive-images-automator-ottimizzazione-immagini-4-0/) you will find the slides and the video of that talk.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverlok%2Fresponsive-images-automator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverlok%2Fresponsive-images-automator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverlok%2Fresponsive-images-automator/lists"}