{"id":17068926,"url":"https://github.com/localnerve/sass-asset-functions","last_synced_at":"2025-09-13T12:05:58.604Z","repository":{"id":42623595,"uuid":"349266977","full_name":"localnerve/sass-asset-functions","owner":"localnerve","description":"Supplies a set of functions to Sass that keep physical asset location details out of your source code","archived":false,"fork":false,"pushed_at":"2024-05-17T18:24:07.000Z","size":1552,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-21T18:25:17.543Z","etag":null,"topics":["asset-management","build-tool","nodejs","sass","sass-functions"],"latest_commit_sha":null,"homepage":"","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/localnerve.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-19T01:35:21.000Z","updated_at":"2024-05-30T01:40:22.599Z","dependencies_parsed_at":"2023-01-21T15:15:35.288Z","dependency_job_id":"6a55ec6b-7aae-406b-bcdf-764a6e611d96","html_url":"https://github.com/localnerve/sass-asset-functions","commit_stats":{"total_commits":18,"total_committers":2,"mean_commits":9.0,"dds":0.05555555555555558,"last_synced_commit":"ad5175e5213eda41131ba7299c6627e74fc70bff"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fsass-asset-functions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fsass-asset-functions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fsass-asset-functions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fsass-asset-functions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localnerve","download_url":"https://codeload.github.com/localnerve/sass-asset-functions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248610810,"owners_count":21132998,"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":["asset-management","build-tool","nodejs","sass","sass-functions"],"created_at":"2024-10-14T11:15:35.671Z","updated_at":"2025-09-13T12:05:58.592Z","avatar_url":"https://github.com/localnerve.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sass Asset Functions\n\n\u003e Supplies a set of functions to Sass that keep physical asset location details out of your source code. Allows one to define a cache-busting policy, specify asset hosts by url, and use arbitrary build-time metadata to drive css generation.\n\n![Verify](https://github.com/localnerve/sass-asset-functions/workflows/Verify/badge.svg)\n[![npm version](https://badge.fury.io/js/%40localnerve%2Fsass-asset-functions.svg)](https://badge.fury.io/js/%40localnerve%2Fsass-asset-functions)\n[![Coverage Status](https://coveralls.io/repos/github/localnerve/sass-asset-functions/badge.svg?branch=master)](https://coveralls.io/github/localnerve/sass-asset-functions?branch=master)\n\n## Overview\n\nThis module provides a set of Sass functions that help with asset management in web projects, similar to what Compass provided. You can use functions like `image-url()` instead of plain `url()` and the module will automatically resolve paths correctly based on your build configuration. Further, you can expose arbitrary built-time metadata (typically from image processors) for use in sass to generate image references, dimensions, types, breakpoints, etc.\n\n_This is a sass compiler plugin that uses the [functions](https://sass-lang.com/documentation/js-api/interfaces/options/#functions) option of the sass javascript api. Supports modern and legacy sass javascript api: `render`, `compile`, and `compileAsync`_\n\n## Origin/History\n\nThis module provides some of the asset functions that came with [Compass](http://compass-style.org). Originally a fork of  [node-sass-asset-functions](https://github.com/fetch/node-sass-asset-functions) that was never merged.\n\n## Release Notes\n\n[Changelog](CHANGELOG.md)\n\n## Functions Exposed to Sass\n\n- `image-url($filename: null, $only_path: false)`\n- `image-width($filename: null)`\n- `image-height($filename: null)`\n- `font-url($filename: null, $only-path: false)`\n- `font-files($filenames...)`\n- `inline-image($filename: null, $mime-type: null)`\n- `lookup($keys...)`\n\n## Usage\n\nBasic usage is as easy as setting the `functions` property:\n\n```js\n// non-module, require usage\nconst sass = require('sass');\nconst { default: assetFunctions } = require('@localnerve/sass-asset-functions');\n\nconst result = sass.compile(scss_filename, {\n  functions: assetFunctions(/* options */)\n  [, options...]\n});\n```\n\n```js\n// module usage\nimport sass from 'sass';\nimport assetFunctions from '@localnerve/sass-asset-functions';\n\nconst result = sass.compile(scss_filename, {\n  functions: assetFunctions(/* options */)\n  [, options...]\n});\n```\n\n## Options\n\nAll options are optional.\n\n| name | type | description |\n| --- | --- | --- |\n| `sass` | Object | A reference to an alternate Sass compiler to use other than dart-sass (must expose `types`). Defaults to `undefined` and a dart-sass reference is used |\n| `legacyAPI` | Boolean | truthy to use the legacy sass API via the sass `render` function. Defaults to `false` |\n| `async` | Boolean | truthy to use modern sass API via the `compileAsync` function. Required if supplied `asset_cache_buster` or `asset_host` function options are asynchronous. Defaults to `false` |\n| `images_path` | String | The build-time file path to images. Defaults to `public/images` |\n| `fonts_path` | String | The build-time file path to fonts. Defaults to `public/fonts` |\n| `http_images_path` | String | The path to images as seen from the web (nothing to do with http). Defaults to `/images` |\n| `http_fonts_path` | String | The path to images as seen from the web (nothing to do with http). Defaults to `/fonts` |\n| `asset_cache_buster` | Function | Signature (http_path, real_path, callback(new_url)). Supply to perform url transform for `image-url` or `font-url`, presumably for asset cache busting, but useful for any change to the url path (before fragment) |\n| `asset_host` | Function | Signature (http_path, callback(new_url)). Supply to perform url transform for `image-url` or `font-url`, presumably to define an asset host, but useful for any change to the url before the path |\n| `data` | Object | An object of arbitrary data to reference at build-time. Defaults to `(empty)` |\n\n### Advanced Options Quick Links\n\n* **[Asset Cache Buster](#asset_cache_buster-a-function-to-rewrite-the-asset-path):** Modify URLs for cache busting (e.g., adding version numbers)\n* **[Asset Host](#asset_host-a-function-which-completes-with-a-string-used-as-asset-host):** Set custom hostnames for assets\n* **[Data Lookup](#lookup-a-function-to-use-arbitrary-data-in-sass-stylesheets):** Pass arbitrary data from JavaScript to Sass via the lookup() function\n\n### Examples\n\nYou can specify the paths to your resources using the following options (shown with defaults):\n\n```js\n{\n  images_path: 'public/images', // local directory\n  http_images_path: '/images',  // map to web path\n  fonts_path: 'public/fonts',   // local directory\n  http_fonts_path: '/fonts',    // map to web path\n  data: {}                      // build data exposed by *lookup*\n}\n```\n\nSo if your project images reside in `public/img` at build-time instead of `public/images`, you use it as follows:\n\n```js\nconst sass = require('sass');\nconst { default: assetFunctions } = require('@localnerve/sass-asset-functions');\n\nconst result = sass.compile(scss_filename, {\n  functions: assetFunctions({\n    images_path: 'public/img',  // the local path to the assets \n    http_images_path: '/images' // the path from the browser to the assets\n  })\n  [, options...]\n});\n```\n\n#### `lookup`: a function to use arbitrary data in sass stylesheets\n\nThis function retrieves arbitrary build-time data for reference in stylesheet compilation. Could be an asset name, prefix, or could be a whole list or map of things. Here's the list of javascript type mappings (everything else returns SassNull):\n  * Boolean =\u003e SassBoolean\n  * Number =\u003e SassNumber\n  * String =\u003e SassString\n  * Array =\u003e SassList\n  * Set =\u003e SassList\n  * Object =\u003e SassMap\n  * Map =\u003e SassMap\n\n```js\nconst result = sass.compile(scss_filename, {\n  functions: assetFunctions({\n    data: {\n      'hero-image-names': {\n        big: 'hero-1920x300.webp',\n        medium: 'hero-1440x300.webp',\n        small: 'hero-1024x300.webp'\n      },\n      nested: {\n        process: true,\n        'process-map': {\n          one: 'one',\n          two: 'two'\n        }\n      }\n    }\n  })\n});\n```\n\n```scss\n$hero-images: lookup('hero-image-names');\n@each $key, $val in $hero-images {\n  .hero-image-#{$key} {\n    background-image: image-url($val);\n  }\n}\n\n$nested-process: lookup('nested', 'process');\n$nested-data: lookup('nested', 'process-map');\n@if $nested-process {\n  @each $key, $val in $nested-data {\n    .process-#{$key} {\n      content: '#{$val}';\n    }\n  }\n}\n```\n\n#### `asset_host`: a function which completes with a string used as asset host.\n\n```js\nconst result = sass.compile(scss_filename, {\n  functions: assetFunctions({\n    asset_host: (http_path, done) =\u003e {\n      done('http://assets.example.com');\n      // or use the supplied path to calculate a host\n      done(`http://assets${http_path.length % 4}.example.com`);\n    }\n  })\n  [, options...]\n});\n```\n\n#### `asset_cache_buster`: a function to rewrite the asset path\n\nWhen this function returns a string, it's set as the query of the path. When returned an object, `path` and `query` will be used.\n\n```js\nconst result = sass.compile(scss_filename, {\n  functions: assetFunctions({\n    asset_cache_buster: (http_path, real_path, done) =\u003e {\n      done('v=123');\n    }\n  })\n  [, options...]\n});\n```\n\n##### A more advanced example of `asset_cache_buster`:\n\nHere we include the file's  hexdigest in the path, using the [`hexdigest`](https://github.com/koenpunt/node-hexdigest) module.\n\nFor example, `/images/myimage.png` would become `/images/myimage-8557f1c9b01dd6fd138ba203e6a953df6a222af3.png`.\n\n```js\nconst sass = require('sass');\nconst path = require('path');\nconst fs = require('fs');\nconst hexdigest = require('hexdigest');\nconst { default: assetFunctions } = require('@localnerve/sass-asset-functions');\n\nconst result = sass.compileAsync(scss_filename, {\n  functions: assetFunctions({\n    async: true,\n    asset_cache_buster: (http_path, real_path, done) =\u003e {\n      hexdigest(real_path, 'sha1', (err, digest) =\u003e {\n        if (err) {\n          // an error occurred, maybe the file doesn't exist.\n          // Calling `done` without arguments will result in an unmodified path.\n          done();\n        } else {\n          const extname = path.extname(http_path);\n          const basename = path.basename(http_path, extname);\n          const new_name = `${basename}-${digest}${extname}`;\n          done({path: path.join(path.dirname(http_path), new_name), query: null});\n        }\n      });\n    }\n  })\n  [, options...]\n});\n```\n\n#### `sass`: Overriding the default compiler with Node-Sass\n\nExample using the node-sass compiler using the new option `sass`.\n\n```js\nconst sass = require('node-sass');\nconst { default: assetFunctions } = require('@localnerve/sass-asset-functions');\n\nconst result = sass.compile(scss_filename, {\n  functions: assetFunctions({ sass })\n  [, options...]\n});\n```\n\n_As of version 7.0.0, node-sass integration is no longer tested_\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n## License\n\n* [MIT](LICENSE.md)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalnerve%2Fsass-asset-functions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalnerve%2Fsass-asset-functions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalnerve%2Fsass-asset-functions/lists"}