{"id":26967046,"url":"https://github.com/pascal-brand38/astro-sprite","last_synced_at":"2025-06-28T14:35:40.204Z","repository":{"id":258685268,"uuid":"874328316","full_name":"pascal-brand38/astro-sprite","owner":"pascal-brand38","description":"Sprite generation (png, webp,...) dedicated Astro framework","archived":false,"fork":false,"pushed_at":"2024-10-24T15:58:34.000Z","size":98,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-25T14:32:29.274Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/astro-sprite","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/pascal-brand38.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-17T16:23:09.000Z","updated_at":"2024-10-24T15:57:57.000Z","dependencies_parsed_at":"2025-02-26T18:32:38.288Z","dependency_job_id":null,"html_url":"https://github.com/pascal-brand38/astro-sprite","commit_stats":null,"previous_names":["pascal-brand38/astro-sprite"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-brand38%2Fastro-sprite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-brand38%2Fastro-sprite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-brand38%2Fastro-sprite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pascal-brand38%2Fastro-sprite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pascal-brand38","download_url":"https://codeload.github.com/pascal-brand38/astro-sprite/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246969065,"owners_count":20862482,"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":[],"created_at":"2025-04-03T08:37:41.446Z","updated_at":"2025-06-28T14:35:40.189Z","avatar_url":"https://github.com/pascal-brand38.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# astro-sprite\r\n\r\n**astro-sprite** is a npm package aimed at building a sprite from small images/icons,\r\nto be used with [Astro](https://astro.build/).\r\nThe sprite is created as a png, webp, or avif image.\r\n\r\nTypically, from single small images/icons (png, webp, avif)\r\n![](https://raw.githubusercontent.com/pascal-brand38/astro-sprite/main/src/data/src/english.png) and\r\n![](https://raw.githubusercontent.com/pascal-brand38/astro-sprite/main/src/data/src/france.png) and\r\n![](https://raw.githubusercontent.com/pascal-brand38/astro-sprite/main/src/data/src/facebook.png) and\r\n![](https://raw.githubusercontent.com/pascal-brand38/astro-sprite/main/src/data/src/youtube.png) and\r\n![](https://raw.githubusercontent.com/pascal-brand38/astro-sprite/main/src/data/src/play_20x20.png),\r\nastro-sprite integration creates the following bigger image\r\n(the sprite), that contains all small icons:\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"https://raw.githubusercontent.com/pascal-brand38/astro-sprite/main/src/data/dst/astro-sprite.png\" /\u003e\r\n\u003c/p\u003e\r\n\r\n\r\nas well as a .css file, that used by the html to display a small image from the sprite. Typically, it includes:\r\n\r\n```css\r\n.astro-sprite { background-image:url(/img/astro-sprite.png?v=0cfc71);}\r\n.astro-sprite-english { background-position: -0px -0px; width: 32px; height: 32px; }\r\n.astro-sprite-facebook { background-position: -32px -0px; width: 32px; height: 32px; }\r\n.astro-sprite-france { background-position: -64px -0px; width: 32px; height: 32px; }\r\n.astro-sprite-play_20x20 { background-position: -96px -0px; width: 20px; height: 20px; }\r\n.astro-sprite-youtube { background-position: -116px -0px; width: 32px; height: 32px; }\r\n```\r\n\r\nIt is then rather easy to display the english flag in html, using for example:\r\n```html\r\n\u003cdiv class=\"astro-sprite astro-sprite-english\"\u003e\r\n\u003c/div\u003e\r\n```\r\n\r\nFor more information about sprites and their benefits, here is a link selection:\r\n\r\n* [mdn web docs](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_images/Implementing_image_sprites_in_CSS)\r\n* [w3schools](https://www.w3schools.com/css/css_image_sprites.asp)\r\n* [GTMetrix](https://gtmetrix.com/combine-images-using-css-sprites.html)\r\n\r\n\r\n\u003cbr\u003e\r\n\r\n# Usage\r\n\r\n## Installation\r\n\r\n### Quick install\r\n\r\nTo install astro-sprite, run the following from your project directory and follow the prompts:\r\n\r\n* Using NPM: ```npx astro add astro-sprite```\r\n* Using Yarn: ```yarn astro add astro-sprite```\r\n* Using PNPM: ```pnpx astro add astro-sprite```\r\n\r\n\r\n### Manual install\r\n\r\nFirst, install the astro-sprite package using your package manager. If you're using npm, run this in the terminal:\r\n\r\n```bash\r\nnpm install astro-sprite\r\n```\r\n\r\nThen, apply this integration to your astro.config.mjs file using the integrations property:\r\n\r\n```js\r\nimport { defineConfig } from 'astro/config';\r\nimport sprite from 'astro-sprite'\r\n\r\nexport default defineConfig({\r\n  integrations: [\r\n    sprite()\r\n  ],\r\n});\r\n```\r\n\r\nThe default behavior of astro-sprite is the following:\r\n* Look for all ```.png``` images in ```assets/astro-sprite```\r\nlocated in the astro src directory\r\n* Save the resulting sprite image as ```img/astro-sprite.png```,\r\nin the astro public dir\r\n* Save the resulting css file as ```css/astro-sprite.css```\r\nin the astro src dir\r\n  * the class name containing the ```background-image```\r\n    css property is ```.astro-sprite```\r\n  * each icon in the sprite have a dedicated class name\r\n    that starts with ```.astro-sprite-```, followed by the\r\n    filename base. Typically, ```.astro-sprite-english```\r\n    reference icon in ```english.png```\r\n\r\n\u003cbr\u003e\r\n\r\n## Customizations\r\n\r\n```sprite-astro``` can be customized to better fit your need.\r\nHere are the default values that can be customized:\r\n\r\n```js\r\nimport { defineConfig } from 'astro/config';\r\nimport sprite from 'astro-sprite'\r\n\r\nexport default defineConfig({\r\n  integrations: [\r\n    sprite({\r\n      src: {\r\n        dir: 'img/astro-sprite',\r\n        extension: '.png',\r\n      },\r\n      dst: {\r\n        spriteFile: 'img/astro-sprite.png',\r\n        cssFile: 'css/astro-sprite.css',\r\n        preloadFile: 'components/SpritePreload.astro',\r\n        cssMainClass: '.astro-sprite',\r\n        cssPrefix: '.astro-sprite-',\r\n        cssSelector: '',\r\n      },\r\n      verbose: true,\r\n    })\r\n  ],\r\n});\r\n```\r\n\r\nCustomized properties are:\r\n* ```src```: properties related to the source icons:\r\n  * ```dir```: directory where the single icons are located, relative to the astro srcDir.\r\n  * ```extension```: all files in ```src.dir``` with the provided extension will be\r\n    used the sprite. ```.webp``` and ```.avif``` can be used\r\n* ```dst```: properties related to the output of the integration\r\n  * ```spriteFile```: the output sprite filename, relative to the astro publicDir\r\n    A ```.webp``` or ```.avif``` file can be used\r\n  * ```cssFile```: the output css filename, relative to the astro srcDir\r\n  * ```preloadFile```: an astro component, to be use in the head section of the html,\r\n    in order to preload the sprite, not waiting for the css to be loaded.\r\n    Set it to ```undefined``` not to generate this file.\r\n  * ```cssMainClass```: the css class that contains the property ```backgroud: url();```\r\n  * ```cssPrefix```: each icon will be related to a css class, prefixed by this\r\n    property, and suffixed by the icon file name\r\n  * ```cssSelector```: a css selector added to each icon class, such as ```::before```\r\n* ```verbose```: verbose mode on or off\r\n\r\n\r\n\r\n\r\n# Best practices\r\n\r\n## Scss\r\n\r\nScss can be used to import the generated sprite css file in your\r\nscss file. Here is the\r\n[astro documentation about scss](https://docs.astro.build/fr/guides/styling/#sass-et-scss).\r\n\r\nIn your main scss file, you may then add:\r\n```scss\r\n@import \"../css/astro-sprite\";\r\n```\r\n\r\n## Preload\r\n\r\nIn order not to wait the css to be loaded to load the associated sprite,\r\nan astro component is created. Its name is ```dst.preloadFile```, which equals\r\n```components/SpritePreload.astro``` by default.\r\n\r\nIn order to preload the sprite, add in the head section this code:\r\n\r\n```astro\r\n---\r\nimport SpritePreload from \"../components/SpritePreload.astro\";\r\n---\r\n\u003chead\u003e\r\n   ...\r\n   \u003cSpritePreload/\u003e\r\n   ...\r\n\u003c/head\u003e\r\n```\r\n\r\n## Span\r\n\r\n```span``` is an easy way to add icons inlined your text, such as:\r\n\r\n```html\r\n\u003cp\u003e\r\n  \u003cspan class=\"astro-sprite astro-sprite-english\"\u003e\u003c/span\u003e the english flag\r\n\u003c/p\u003e\r\n```\r\n\r\nTo achieve a correct result, ```::before``` selector must be used, as with\r\n```js\r\nexport default defineConfig({\r\n  integrations: [\r\n    sprite({\r\n      dst: {\r\n        cssMainClass: '.astro-sprite::before',\r\n        cssSelector: '::before',\r\n      }\r\n    })\r\n  ],\r\n});\r\n```\r\n\r\nAnd add in your main .css / .scss file the following:\r\n```scss\r\n.astro-sprite::before {\r\n  content: \"\";\r\n  display:inline-block;\r\n  vertical-align:middle;\r\n}\r\n```\r\n\r\n\r\n## Get rid of ```.astro-sprite``` css class\r\nInstead of using both ```astro-sprite astro-sprite-english``` to specify an\r\nicon, this is possible to specify only ```astro-sprite-english``` by using the following\r\n(```cssMainClass``` applies to any css class containing ```astro-sprite-```):\r\n```js\r\nexport default defineConfig({\r\n  integrations: [\r\n    sprite({\r\n      dst: {\r\n        cssMainClass: '[class*=\"astro-sprite-\"]',\r\n      }\r\n    })\r\n  ],\r\n});\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpascal-brand38%2Fastro-sprite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpascal-brand38%2Fastro-sprite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpascal-brand38%2Fastro-sprite/lists"}