{"id":29776845,"url":"https://github.com/godaddy/asset-system","last_synced_at":"2025-07-27T10:20:40.422Z","repository":{"id":31447199,"uuid":"127899829","full_name":"godaddy/asset-system","owner":"godaddy","description":"asset-system is a cross platform SVG based asset system for React and React-Native. This mono-repo is the home for all asset-* packages.","archived":false,"fork":false,"pushed_at":"2024-01-09T15:53:55.000Z","size":401,"stargazers_count":20,"open_issues_count":58,"forks_count":6,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-07-14T22:56:54.768Z","etag":null,"topics":["asset-bundle","asset-list","asset-parser","asset-provider","asset-system","asset-webpack","assets","react","react-native","svg","svgs"],"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/godaddy.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-04-03T11:48:55.000Z","updated_at":"2024-04-24T07:35:51.000Z","dependencies_parsed_at":"2023-01-14T19:03:47.776Z","dependency_job_id":"6f2e035d-3959-4663-91f5-7f63bdc21254","html_url":"https://github.com/godaddy/asset-system","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/godaddy/asset-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fasset-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fasset-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fasset-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fasset-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/godaddy","download_url":"https://codeload.github.com/godaddy/asset-system/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fasset-system/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266093921,"owners_count":23875559,"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-bundle","asset-list","asset-parser","asset-provider","asset-system","asset-webpack","assets","react","react-native","svg","svgs"],"created_at":"2025-07-27T10:20:39.611Z","updated_at":"2025-07-27T10:20:40.412Z","avatar_url":"https://github.com/godaddy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# asset system [![Build Status](https://img.shields.io/travis/babel/babel/master.svg?label=travis\u0026maxAge=43200)](https://travis-ci.org/godaddy/asset-system) [![Coverage Report](https://img.shields.io/codecov/c/github/godaddy/asset-system/master.svg?maxAge=43200)](https://codecov.io/gh/godaddy/asset-system)\n\n`assets-{*}` is a cross platform asset system for React and React-Native.\nIt allows you to use the same assets and logic on web and native devices.\n\nWhat you are looking at is the mono repo for all `asset-*` projects. If\nare looking for specific documentation about a projects:\n\n- [asset-provider][provider] The React(-native) Components.\n- [asset-parser][parser] Response parser / encoder.\n- [asset-bundle][bundle] Bundles svgs in to a single bundle.\n- [asset-webpack][webpack] WebPack plugin.\n- [asset-list][list] Generates documentation about the bundle.\n\n## Table of Contents\n\n- [Design Goals](#design-goals)\n- [Examples](#examples)\n- [Project structure](#project-structure)\n- [Integrate with WebPack](#integrate-with-webpack)\n  - [Specify the `file-loader` for .svg extensions](#specify-the-file-loader-for-svg-extensions)\n  - [Configure plugin](#configure-plugin)\n  - [Producing a bundle](#producing-a-bundle)\n- [Integrate with Next.js](#integrate-with-nextjs)\n- [Integrate with warehouse.ai](#integrate-with-warehouseai)\n- [Project Management](#project-management)\n  - [Install](#install)\n  - [Testing](#testing)\n  - [Publishing](#publishing)\n- [License](#license)\n\n## Design Goals\n\nWhen designing the asset system from the ground up, we established some humble\ndesign goals that the system should satisfy:\n\n- **isomorphic** Asset loading and presenting should work in React **and**\n  React-Native without having to change a single line of code.\n- **scalable** Assets should be scalable without any degradation in quality\n  regardless of the size and resolution.\n- **performance focused** Highly optimized bundle, built-in caching and request\n  optimizations.\n- **UX/DX first** Easy to use, intuitive API's. With `height` and `width` as\n  required properties we [prevent unwanted layout reorganization/relayout][sizing].\n- **accessibility** ARIA properties and roles are used where possible and\n  `accessibilityLabel` for React-Native.\n- **modifications** Various of hooks should be present in the transformation\n  process to support on the fly modification e.g. recoloring of the asset so you\n  can prevent duplicates.\n\n## Examples\n\nWe have prepared 2 examples where we integrate `asset-provider` in to\nan application.\n\n- [web](/examples/web) Integration in to a web application.\n- [react-native](/examples/reactnative) Integration in to a React-Native application.\n\n## Project structure\n\nThe README that you're currently reading is in the root of our [mono][mono]\nrepository. All related projects/packages are available in the [packages][packages]\nfolder that is in the root of this repository. This makes it easier to contribute\nchanges to the multiple packages at once as they tightly coupled/integrated.\n\nThis undertaking is separated into multiple standalone packages:\n\n- [asset-provider][provider]\n- [asset-parser][parser]\n- [asset-bundle][bundle]\n- [asset-webpack][webpack]\n- [asset-list][list]\n\nThe following flow chart illustrates how the various of packages are used:\n\n```\n[ asset-provider] -\u003e [ \u003cProvider uri={} /\u003e ] -\u003e [ \u003cAsset name={} /\u003e ]\n          ^                         ^\n          |                         |\n    XMLHTTPRequest         [ asset-parser ]\n          |                         ^\n          v                         |\n [ ~ bundle.svgs ~ ]                |\n          ^                         |\n          |                         |\n  [ asset-bundle ] \u003c - - - - - - - - - - - - - -\u003e [ asset-list ]\n          ^\n          |\n  [ asset-webpack ]\n```\n\nLets start from the bottom and move our way upwards. There is a WebPack plugin\nthat can extract SVG's from your JavaScript files (or you can create a\nseparate JavaScript file that requires the SVGS). All found SVG assets are\nthen passed to the [asset-bundle][bundle] library.\n\nThis library will parse, optimize and combine all SVGS in to a single file\nformat. This will reduce HTTP requests leading to better performance. The\nresulted bundle will then be encoded using the [asset-parser][parser].\n\nOnce this process is done, [asset-list][list] will generate documentation\nabout the created bundle so you can easily see which files are embedded, the\ndimensions of the assets and the total file size.\n\nYou can then upload the resulting bundle to your CDN for usage.\n\nThe [asset-provider][provider] contains `\u003cProvider\u003e` (root) and `\u003cAsset\u003e`\n(child) components for fetching/presenting assets from the uploaded svgs\nbundle. The `\u003cProvider uri={ }\u003e` will fetch the bundle once an nested child\n`\u003cAsset /\u003e` component is encountered. Once bundle is downloaded the\n[/asset-parser][parser] decode the HTTP payload. The bundled SVG's will only be\ntransformed to SVG elements once a `\u003cAsset name={} /\u003e` component references.\n\n## Integrate with WebPack\n\nImport the loader in to your [`webpack.config.js`](/examples/webpack.config.js):\n\n```js\nimport SVGBundler from 'asset-webpack';\n```\n\n#### Specify the `file-loader` for .svg extensions\n\nFirst we need to ensure that `.svg` files are handled as normal, static, files.\nThis is done by specifying a `file-loader` for the given extension. Update the\nmodule loaders to contain the following:\n\n```js\nmodule: {\n  loaders: [\n    { test: /\\.svg$/, loaders: [ 'file-loader' ] }\n  ]\n}\n```\n\n#### Configure plugin\n\nThe following arguments are accepted:\n\n- `filename` The filename of the resulting SVG Asset Bundle. It will be stored\n  in the folder you specified in your `webpack.config.js`'s `ouptput.path`.\n- `options` Additional configuration that will be forwarded to the\n  `asset-bundle` processor.\n\n```js\n{\n  ...,\n  plugins: [\n    new SVGBundler('bundle.svgs', { /* opts */ })\n  ]\n}\n```\n\n#### Producing a bundle\n\nCreate an entry file that requires the SVG assets:\n\n```js\nrequire('./file.svg');\nrequire('./another.svg');\nrequire('./more.svg');\n```\n\n## Integrate with [next.js][next]\n\nNext.js is a minimalistic framework for server-rendered React applications. The\nrender flow of Next.js is as followed:\n\n1. On first render, your application will be rendered on the **server** and the\n   resulting HTML will be send to the client.\n2. The returned HTML will be rehydrated with ReactDOM so all event listeners\n   are attached again and every re-render of your application will work as\n   intended.\n\nThis means that if you include an SVG element in your application it will send\nto the client on initial render as part of the HTML payload as well as be\nincluded in the client-side bundle as it needs to be available for re-rendering.\n\nAsset-System's build-in optimizations will automatically resolve this\nduplication as it will render a placeholder with the same dimensions as the\noriginal SVG, and once the application is rehydrated on the client-side it\nfetch the SVG bundle, and render your intended SVG in the placeholder. As the\nplaceholder is the same dimensions as the actual SVG, there will be no annoying\njumping of layout (relayout).\n\nIn order to implement Asset-System with Next.js, we need to add our\n`asset-webpack` module to their own `webpack.config.js`, this is done by\ncreating a custom `next.config.js` and assigning a `webpack` function that\nalters the webpack. In this example we use `webpack-merge` to help with the\nmerging of our new webpack rules:\n\n```js\n// next.config.js\nmodule.exports = {\n  webpack: function webpack(config) {\n    return require('webpack-merge').smart(config, {\n      module: {\n        rules: [\n          {\n            test: /\\.(svg)$/,\n            use: ['file-loader']\n          }\n        ]\n      },\n      plugins: [\n        new Bundler('static/bundle.svgs', {\n          root: __dirname\n        })\n      ]\n    });\n  }\n}\n```\n\nOnce you have your custom `next.config.js` in place, you can reference the\ngenerated bundle at `/_next/static/bundle.svgs` in your pages:\n\n```js\n// pages/index.js\n\nimport Provider, { Asset } from 'asset-provider';\nimport reactLogo from '@fortawesome/fontawesome-free/svgs/brands/react.svg';\n\nexport default function Index(props) {\n  return (\n    \u003cProvider uri='/_next/static/bundle.svgs'\u003e\n      \u003ch1\u003eRendering the React Logo\u003c/h1\u003e\n      \u003cAsset name={ reactLogo } width={ 100 } height={ 100 } title='The React logo' /\u003e\n    \u003c/Provider\u003e\n  )\n}\n```\n\n## Integrate with [warehouse.ai][warehouse]\n\nThe system was designed to be compatible [warehouse.ai][warehouse], which is\nwhat we use internally at GoDaddy to compile and distribute our front-end code.\nIf you've also adopted warehouse, you can easily integrate `asset-system` in\nyour build flow.\n\nWe assume you've already setup your own scope according to the warehouse\ninstructions that are outlined in their docs.\n\nUpdate the projects `package.json` to include the following:\n\n- `build` which activates `webpack`\n- `publishConfig` that points to the Warehouse server\n\n```js\n{\n  ...\n  \"build\": \"webpack\",\n  \"publishConfig\": {\n    \"registry\": \"https://custom.wrhs.url.here.com\"\n  },\n  ...\n}\n```\n\nNow that the `package.json` is updated you need to specify which files should\nbe uploaded to the CDN. This is done by creating a [`whrs.toml`](/examples/whrs.toml)\nwhich contains the following:\n\n```\n[files]\ndev = ['dist/bundle.svgs']\ntest = ['dist/bundle.svgs']\nprod = ['dist/bundle.svgs']\n```\n\nYou can specify multiple bundles that need be uploaded, or create multiple\npackages.\n\n## Project management\n\nManaging your first mono repo can be overwhelming at first, luckily we have\nsome tools that will make this a lot easier and automate most of the processes.\n\nThis repo is managed by the `mono-repos` package which comes with CLI and Node.js\nAPI for managing packages. It's already installed as devDependency, but you\ncan also install it globally:\n\n```\nnpm install --global mono-repos\n```\n\n### Install\n\nWe've provided an installation script that will automatically go through\nall the packages, install the dependencies, and symlink them if needed. This\nprocess is ran automatically when you run:\n\n```\nnpm install\nmono --install\n```\n\nIn the root of the repository. You can always run `npm install` in the package\nfolder as well, but that will not setup the correct symlinks for you.\n\n### Testing\n\nYou can either run tests separately, or run them all at once (recommended for new\nreleases).\n\n```\nnpm test\n\nmono --test\n```\n\nFor testing individual packages\n\n```\nnpm run test:provider\nnpm run test:bundle\nnpm run test:list\nnpm run test:webpack\n\nmono --test bundle\nmono --test webpack\nmono --test provider\n```\n\nIf this isn't your thing, you can also still go in to the package's directory\nand run the `npm test` command there for the individual test.\n\n### Publishing\n\nThe publishing is automated using the `mono` command as well, it ensures that\nfollowing happens in the correct order, and format so we can still correctly\ntrack individual publishes in our `git tags`:\n\n- Increases version number.\n- Create dist commit.\n- Create the correct git tag.\n- Push to repo.\n- Publish package.\n\nTo bump all packages:\n\n```\nnpm run publish -- --release major\nmono --publish --release major\n```\n\nIf the `--release` flag is omitted we assume it's a `patch` release by default.\nWhen you want to release an individual package:\n\n```\nnpm run publish:provider\nnpm run publish:bundle\nnpm run publish:parser\n\nmono --publish provider\nmono --publish bundle\nmono --publish parser\n```\n\n## License\n\n[MIT](LICENSE)\n\n[bundle]: /packages/bundle\n[parser]: /packages/parser\n[webpack]: /packages/webpack\n[provider]: /packages/provider\n[list]: /packages/list\n[svgs]: https://github.com/godaddy/svgs\n[sizing]: https://facebook.github.io/react-native/docs/images.html#why-not-automatically-size-everything\n[mono]: https://github.com/3rd-Eden/mono-repos/mono.md\n[packages]: /packages/\n[warehouse]: https://github.com/godaddy/warehouse.ai\n[next]: https://github.com/zeit/next.js\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodaddy%2Fasset-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgodaddy%2Fasset-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodaddy%2Fasset-system/lists"}