Rollup plugin to rebase, inline or copy assets referenced from the code
MIT License
Rollup plugin to rebase, inline or copy assets referenced from the JavaScript code.
import smartAsset from "rollup-plugin-smart-asset"
const smartAssetOpts = { ... }
export default {
input: "src/index.tsx",
output: {
file: "dist/index.js",
format: "iife"
},
plugins: [
...
smartAsset(smartAssetOpts)
...
]
}
For libraries it is recommended to use inline
or copy
mode with keepImport
option to delegate bundling to consumer's package bundler. Asset hashing is not
needed for this case and it is safe to set useHash: false
and keepName: true
.
For applications it is also recommended to use inline
or copy
mode with
enabled by default hashing.
Default settings are set to be the same as in postcss-smart-asset
to have one
config for both of them.
Main options:
url
: Mode: rebase
(default), inline
and copy
extensions
: What file extensions to process, defaults to[".svg", ".gif", ".png", ".jpg"]
unless exclude
or include
are used.include
or exclude
options are used.include
: Micromatch pattern or array of micromatch patterns for files thatexclude
: Micromatch pattern or array of micromatch patterns for files thatemitFiles
: Disable generating files if false
, by default it's true
-For more details about include
/ exclude
syntax please refer to:
https://github.com/micromatch/micromatch
Rebase asset references to be relative to specific directory.
Output:
// without keepImport (inside wrapper)
export default "public_path_to_asset"
// with keepImport and cjs module format
const myAsset = require("relative_path_to_asset_from_bundle")
// with keepImport and esm module format
import myAsset from "relative_path_to_asset_from_bundle"
Options:
publicPath
: Reference file from JS using this path, relative to html pagerebasePath
: Rebase all asset urls to this directory, defaults to current directory.keepImport
: Keep import, so consumer of your package could define their ownsourceMap
: Set to true
to keep source map.Inline assets as base64 urls directly in source code.
Keep in mind, all options for copy
mode will be used if falled back to copy
mode.
Output:
export default "data:{mimeType};base64,{data}"
Options:
maxSize
: Max file size to inline (in kb), fallback is copy
mode,14
kbytes.Copy asset to target directory and rebase original references to point to target path depending on provided configuration.
Output:
// without keepImport (inside wrapper)
export default "public_path_to_asset"
// with keepImport and cjs module format
const myAsset = require("relative_path_to_asset_from_bundle")
// + file is copied to target directory
// with keepImport and esm module format
import myAsset from "relative_path_to_asset_from_bundle"
// + file is copied to target directory
Options:
publicPath
: Reference file from JS using this path, relative to html pageassetsPath
: Copy assets to this directory, relative to rollup output.useHash
: Enable to use [hash][ext]
instead of default [name][ext]
.keepName
: Use both hash and name [name]~[hash][ext]
if useHash
is true
.nameFormat
: Use custom name format using these patterns [name]
, [ext]
,[hash]
.hashOptions
: Hash options.
hash
: Any valid Node's crypto hashing algorithm e.g. sha1
, md5
etc,metrohash64
or metrohash128
if metrohash
is installed,xxhash32
or xxhash64
if xxhash
is installed.sha1
.encoding
: Hash encoding hex
, base64
base62
, base58
, base52
,base49
, base36
, base32
, base26
. Default is base52
.maxLength
: Maximum length of returned digest. Keep in mind that8
.keepImport
: Keep import, so consumer of your package could define their ownPreserve Modules
Rollup preserveModules: true
is supported but additional context is required
for the plugin to properly detect rebased path to the asset.
Additional options needed:
outputDir
: Path to output dir, should be the same as output.dir
, can't bepreserveModules
: Set to true
to activate mode, can beinputFile
: Path to main entry, should be the same as input.file
,input.file
are notChanges:
hashOptions.hash
defaults to sha1
instead of metrohash128
.asset-hash
.xxhash
and metrohash
.The default configuration is changed in favor of default hash functions
that are available in NodeJS without requirement to build any native
extensions during npm install
.
If you would like to use ultra fast metrohash64
or metrohash128
hashes
then do npm install metrohash
and set hashOptions.hash
to metrohash64
or metrohash128
.
If you would like to use ultra fast xxhash32
or xxhash64
hashes
then do npm install xxhash
and set hashOptions.hash
to xxhash32
or xxhash64
.
https://github.com/rollup/rollup-plugin-url or https://github.com/rollup/plugins/tree/master/packages/url
This Rollup plugin has fewer options, doesn't work if asset is already loaded
by another plugin (by sourcemaps, for example) and doesn't have keepImport
like option (designed for applications).
https://github.com/sebastian-software/postcss-smart-asset
This PostCSS plugin works for assets referenced from CSS, but doesn't work for assets imported from JavaScript.
https://github.com/sebastian-software/rollup-plugin-rebase
This Rollup plugin is designed for libraries, has keepImport
like option
enabled by default so can't be used for applications.
PRs are very welcome!
MIT