{"id":20020655,"url":"https://github.com/netcentric/progux","last_synced_at":"2025-05-05T01:30:43.102Z","repository":{"id":40291695,"uuid":"344765034","full_name":"Netcentric/progux","owner":"Netcentric","description":"Progressive User Experience Library","archived":false,"fork":false,"pushed_at":"2023-07-14T06:51:54.000Z","size":966,"stargazers_count":18,"open_issues_count":3,"forks_count":5,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-29T00:20:50.377Z","etag":null,"topics":["progressive-enhancement","user-experience","web-performance"],"latest_commit_sha":null,"homepage":"http://progux.org/","language":"JavaScript","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/Netcentric.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2021-03-05T09:49:33.000Z","updated_at":"2025-04-17T11:05:21.000Z","dependencies_parsed_at":"2024-11-13T08:34:25.710Z","dependency_job_id":"18735ed1-f696-4497-b88e-b3dbfadb5dd2","html_url":"https://github.com/Netcentric/progux","commit_stats":{"total_commits":46,"total_committers":10,"mean_commits":4.6,"dds":0.6739130434782609,"last_synced_commit":"d52f0fdbe4125dd9f874a223d0ab7bcca4e57514"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcentric%2Fprogux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcentric%2Fprogux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcentric%2Fprogux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcentric%2Fprogux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Netcentric","download_url":"https://codeload.github.com/Netcentric/progux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252422932,"owners_count":21745515,"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":["progressive-enhancement","user-experience","web-performance"],"created_at":"2024-11-13T08:33:31.954Z","updated_at":"2025-05-05T01:30:42.622Z","avatar_url":"https://github.com/Netcentric.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![ProgUX logo](assets/Logo_ProgUX.png)\n\n# @netcentric/ProgUX\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@netcentric/progux\"\u003e\n    \u003cimg src=\"https://badgen.net/npm/v/@netcentric/progux\" alt=\"Current npm version\"\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://bundlephobia.com/result?p=@netcentric/progux\"\u003e\n    \u003cimg src=\"https://flat.badgen.net/bundlephobia/min/@netcentric/progux\" alt=\"Minified size\"\u003e\n   \u003c/a\u003e\n\u003c/p\u003e\n\n\u003e The Progressive User Experience Library (ProgUX) lets you progressively enhance your website or PWA based on the following criteria:\n\n- Users Preferences\n  - Prefers Reduced Motion\n  - Save Data Settings\n  - Tracking Settings\n- Device Capabilities\n  - CPU Capacity\n  - Memory Level\n- Network\n  - Connection Speed\n\nThe library is using modern browser APIs to collect the data of the current session and creates a JavaScript object in the Session Storage and CSS classes in the \u003cbody\u003e. Each of these can be used to decide what features, content, web fonts, JavaScript, CSS, etc. will be delivered to the user to create a progressive user experience.\n\nThe idea is similar to [react-adapitve-hooks](https://github.com/GoogleChromeLabs/react-adaptive-hooks).\nHowever ProgUX is not limited to React and provides a simulator which makes it easy to test different settings in the developer/test mode.\n\n## Installation\n\nTo start using ProgUX inline the code from `dist/prod/bundle.js` before any other JavaScript and CSS code in the \u003chead\u003e and call the progUX() to initialise the script. If you want to override any of the configurations pass it to the function as an object.\n\n```\n\u003cscript type=\"application/javascript\"\u003e\n  !function(){\"use strict\";const n=n=\u003e\"connection\"in navigator ... // inline whole code\n\n  progUX({\n      sessionStorageKey: 'someOtherKeyName'\n  });\n\u003c/script\u003e\n```\n\nThe web performance impact to run the production code is about ~10ms (measured on a local dev environment without throtteling).\n\n## Usage\n\nHow your application changes and adapts to the environmental constraints and capabilities is ultimately up to you. ProgUX will not perform any magic that will change your application, it simply provides each developer who uses it a snapshot with which they can make decisions.\n\nUltimately how you use this is up-to-you, below we describe how you can gain access to this information.\n\nOnce installed and the application has reloaded developers will have access to an object in the session storage as well as a number of classes to reference in the `\u003cHTML\u003e` tag.\n\n### Session Storage Object\n\nThe object will contain the following keys and values:\n\n```javascript\nconnectionSpeed: String; // 'slow/fast/unknown'\ncpuLevel: String; // 'low/mid/high/unknown'\nmemoryLevel: String; // 'low/mid/high/unknown'\nreducedMotion: Boolean;\nsaveData: Boolean;\ndoNotTrack: Boolean;\n```\n\n### CSS Classes\n\nThe `\u003cHTML\u003e` tag will contain the following classes\n\n```\nconnectionSpeed-[slow/fast/unknown]\ncpuLevel-[low/mid/high/unknown]\nmemoryLevel-[low/mid/high/unknown]\nreducedMotion-[true/false]\nsaveData-[true/false]\ndoNotTrack-[true/false]\n```\n\nThe output will look similar to this\n\n```\n\u003chtml class=\"connectionSpeed-slow cpuLevel-low ...\"\u003e\n```\n\nYou then have access to the classes to make decisions in your code, for example\n\n```\n.connectionSpeed-slow {\n  .stage-image {\n    display: block;\n  }\n\n  .stage-video {\n    display: none;\n  }\n}\n```\n\n_To try to limit the impact of unnecessary JavaScript checks ProgUX will only update the `connectionSpeed` during a user session. This is simply because we believe that this is the only one of our checks likely to change during a session._\n\n### Development/testing Environment\n\nTo aid developers and testers we have provided a `dist/dev/dev-bundle.js` and `dist/dev/dev-bundle.css` files that contain extra features.\n\nUsing this script will run the checks in exactly the same way as the production script but contains a modal that allows you to change the settings on the fly.\n\nYou can inline this script as well or use it as modules (JS). CSS you can add to your project and link to the stylesheet in the head.\n\n#### Settings Modal\n\nOnce your application has loaded you will see a cog icon (by default in the top left of your screen), if you click the icon it will open the settings modal.\n\n![Alt](assets/settings_modal.png)\n\nThe modal will automatically be set to reflect the current settings and to make adjustments to this you simply alter the controls to your new desired configuration and hit the 'Submit' button. This will force a page reload, the session storage object and the classes in the HTML will have been updated\n\nInside the modal there is also a toggle switch to show a 'Current Status' bar.\n\n![Alt](assets/status_bar.png)\n\nThis is designed so that if you need to take screenshots of particular variations of the application it will be easy to identify the ProgUX settings at that time.\n\nThe Status Bar is moveable to provide you with the best result.\n\n### Configuration\n\nProgUX provides a `config.js` file found in `src/js`.\n\nInside the file you will find an object with the following properties\n\n```javascript\n// prod and dev\nsettings: lowRAM: Number; // 0.25, 0.5, 1, 2, 4, 8\nlowCPU: Number; // \u003e 0\nslowConnectionTypes: Array; // 'slow-2g','2g','3g', or '4g'\nsessionStorageKey: String; // 'progressiveUserSettings',\n// dev only\nsessionStorageDevKey: String; // 'progressiveUserDevSettings',\ndefaultDevSettings: isDraggable: Boolean;\nmode: String; // 'closed','open'\nposTop: Number; // 20 (in px)\nposLeft: Number; // 20 (in px)\n```\n\nYou can use this attribute names and structure when overriding wanted attributes.\n\n### Overriding config\n\nOveeride of the default congiguration is possible by passing the object with new values for wanted properties to init function (progUX() or progUXdev())\n\nOverriding the values will set the thresholds tested by ProgUX in your application.\nFor instance, by default `slowConnectionTypes` is set to `['slow-2g', '2g', '3g']`, if you considered '3g' to not be a slow connection you could remove it.\n\nOverriding the sessionStorageKey will alter the name of the object saved in your session storage, etc.\n\n## Browser Support\n\nUnfortunately, not all modern browsers support all the APIs, so please check support list before using and plan fallback.\n\n- [Network Information API - saveData](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API) is available in [Chrome 61+, Opera 48+, Edge 79+, Chrome for Android 76+, Firefox for Android 68+](https://caniuse.com/#search=saveData)\n\n- [Navigator API - doNotTrack](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/doNotTrack) is available in [Chrome 23+, Firefox 32+, Opera 12.1+, Edge 17+, Chrome for Android 76+, Firefox for Android 68+](https://caniuse.com/?search=navigator.doNotTrack)\n\n- [Prefers Reduced Motion Media Query](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) is available in [Chrome 74+, Firefox 63+, Safari 10.1+ Opera 12.1+, Edge 79+, Chrome for Android 76+, Firefox for Android 68+, iOS Safari 10.3+](https://caniuse.com/?search=prefers-reduced-motion)\n\n- [Network Information API - effectiveType](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType) is available in [Chrome 61+, Opera 48+, Edge 79+, Chrome for Android 76+, Firefox for Android 68+](https://caniuse.com/#search=effectiveType)\n\n- [Hardware Concurrency API](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorConcurrentHardware/hardwareConcurrency) is available in [Chrome 37+, Safari 10.1+, Firefox 48+, Opera 24+, Edge 15+, Chrome for Android 76+, Safari on iOS 10.3+, Firefox for Android 68+, Opera for Android 46+](https://caniuse.com/#search=navigator.hardwareConcurrency)\n\n- [Device Memory API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/deviceMemory) is available in [Chrome 63+, Opera 50+, Edge 79+, Chrome for Android 76+, Opera for Android 46+](https://caniuse.com/#search=deviceMemory)\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\n### Run project locally\n\nTo test project locally, there are 2 basic html files with integration of both production and development versions of ProgUX.\nTo start local server run\n```\nnpm run start\n``` \nfor production mode or\n```\nnpm run start-dev\n``` \nfor development mode.\n\nIf you want to do some development, there are also watchers included.\nTo run them open a new tab next to one where server is running and run:\n```\nnpm run watch\n``` \n\nFor any questions and issues feel free to contact us.\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetcentric%2Fprogux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetcentric%2Fprogux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetcentric%2Fprogux/lists"}