Install
npm i -D @webpack-utilities/loader
Usage
Loader
loader.js
import { getOptions, resource } from '@webpack-utilities/loader'
function loader (src, map, meta) {
const options = getOptions(this)
if (options.name) {
const name = resource.getName(this, options.name, { content: src })
}
// ...
}
export default loader
Pitching Loader
loader.js
import { request } from '@webpack-utilities/loader'
function loader () {}
function pitch (req) {
const remaining = request.getRemaining(req)
// ...
}
export { pitch }
export default loader
Methods
Name | Type | Default | Description |
---|---|---|---|
getOptions |
{Function} |
null |
Recommended way to retrieve the options of a loader |
request |
{Object} |
undefined |
webpack Loader Request Helpers |
resource |
{Object} |
undefined |
webpack Loader Resource Helpers |
getOptions(this)
Recommended way to retrieve the options of a loader invocation
loader.js
const { getOptions } = require('@webpack-utilities/loader')
function loader () {
const options = Object.assign({}, getOptions(this))
}
⚠️ The returnedoptions
object is read-only. It may be re-used across multiple invocations. If you pass it on to another library, make sure to make a (deep) copy of it e.g
const { getOptions } = require('@webpack-utilities/loader')
const DEFAULTS = {}
function loader () {
const options = Object.assign({}, DEFAULTS, getOptions(this))
}
resource
Name | Type | Default | Description |
---|---|---|---|
getName |
{Function} |
resourcePath |
Interpolates placeholders within a given resourcePath
|
getHash |
{Function} |
[md5:hash:hex:8] |
Computes the Content Hash of the resource
|
resource.getName(this, name, options)
Interpolates a filename template using multiple placeholders and/or a regular expression. The template and regular expression are set as query params called name
and regExp
on the current loader's context (this
)
const name = resource.getName(this, name, options)
Placeholders
The following placeholders are replaced in the name
parameter
Name | Type | Default | Description |
---|---|---|---|
[ext] |
{String} |
path.extname |
The extension of the resource |
[name] |
{String} |
path.basename |
The basename of the resource |
[path] |
{String} |
path.dirname |
The path of the resource relative to the context
|
[hash] |
{String} |
[md4:hash:hex:8] |
The hash of the content, see hashes below for more info |
[N] |
{String} |
undefined |
The n-th match obtained from matching the current filename against the regExp
|
[ext]
this.resourcePath = "/app/js/javascript.js"
resource.getName(this, 'js/file.[ext]', { content })
js/file.js
[name]
this.resourcePath = '/app/page.html'
resource.getName(this, '[name].js', { content })
page.js
[path]
this.resourcePath = '/app/page.html'
resource.getName(this, '[path]/file.js', { content })
/app/file.js
[hash]
this.resourcePath = "/app/file.txt"
resource.getName(this, '[hash]', { content })
c31e9820
[N]
this.resourcePath = "/app/js/page-home.js"
resource.getName(this, "script-[1]", { regExp: "page-(.*)\\.js", content })
script-home.js
resource.getHash(src, type, digest, length)
const hash = resource.getHash(src, type, digest, length)
Hashes
[<type>:hash:<digest>:<length>]
optionally you can configure
Name | Type | Default | Description |
---|---|---|---|
src |
{String|Buffer} |
'' |
The content that should be hashed |
type |
{String} |
md4 |
md4 , md5 , sha1 , sha256 , sha512
|
digest |
{String} |
hex |
hex , base32 , base64
|
length |
{Number} |
8 |
The (maximum) length in chars |
Use sha512
hash instead of md4
with only 7 chars of the base64 encoded contents
this.resourcePath = "/app/file.txt"
resource.getName(this, '[sha512:hash:base64:7]', { content })
2BKDTjl
resource.parseQuery(this.resourceQuery)
Parses a {String}
(e.g. loader.resourceQuery
) as a query string, and returns an {Object}
./file.ext?param=value
const params = resource.parseQuery(this.resourceQuery)
if (params.param === "value") {
// Handle value
}
Query Strings
If the loader options have been passed as loader query string (loader?some¶ms
), the {String}
is parsed by using parseQuery
in the following way
Query String | Result |
---|---|
'' |
{Error} |
? |
{} |
?flag |
{ flag: true } |
?+flag |
{ flag: true } |
?-flag |
{ flag: false } |
?key=1 |
{ key: "1" } |
?key=value |
{ key: "value" } |
?key[]=value |
{ key: [ "value" ] } |
?key1&key2 |
{ key1: true, key2: true } |
?+flag1,-flag2 |
{ flag1: true, flag2: false } |
?key[]=a,key[]=b |
{ key: [ "a", "b" ] } |
?a%2C%26b=c%2C%26d |
{ "a,&b": "c,&d" } |
?{data:{a:1},isJSON5:true} |
{ data: { a: 1 }, isJSON5: true } |
request
Name | Type | Default | Description |
---|---|---|---|
from |
{Function} |
'' |
Makes a webpack compatible request from a generic url
|
stringify |
{Function} |
"" |
Stringifies a url in a webpack compatible manner |
getCurrent |
{Function} |
'' |
Get the current part of a module request |
getRemaining |
{Function} |
'' |
Get the remaining part of a module request |
request.from(url)
Converts a resource URL to a webpack
module request
const url = 'path/to/module.js'
const req = request.from(url)
"./path/to/module.js"
Module URLs
Any URL containing a ~
will be interpreted as a module request. Anything after the ~
will be considered the request path.
'~path/to/module.js'
const url = '~path/to/module.js'
const req = request.from(url)
"path/to/module.js"
Relative URLs
URLs that are root-relative (start with /
) can be resolved relative to some arbitrary path by using the root
parameter.
const root = './root'
const url = '/path/to/module.js'
const req = request.from(url, root)
"./root/path/to/module.js"
To convert a root-relative URL into a module URL, specify a root
value that starts with ~
.
const root = '~'
const url = '/path/to/module.js'
const req = request.from(url, root)
"path/to/module.js"
request.isURL(req)
http://google.com/
const isURL = request.isURL(req)
false
request.stringify(this, url)
Turns a request into a {String}
that can be used inside require()
or import
while avoiding absolute paths.
⚠️ Use it instead ofJSON.stringify(...)
if you're generating code inside a loader
Why is this necessary? Since webpack
calculates the hash before module paths are translated into module ids, we must avoid absolute paths to ensure
consistent hashes across different compilations.
const { getOptions, request } = require(@webpack-utilities/loader)
function loader (src) {
const options = Object.assign({}, getOptions(this))
if (options.urls) {
const imports = options.urls
.map((url, idx) => `import URL__${idx} from ${request.stringify(url)};`)
.join('\n')
}
return `
${imports}
export default ${src}
`
}
request.getCurrent(req)
const { request } = require('@webpack-utilities/loader')
function loader () {}
function pitch (req) {
const current = request.getCurrent(req)
}
request.getRemaining(req)
const { request } = require('@webpack-utilities/loader')
function loader () {}
function pitch (req) {
const remaining = request.getRemaining(req)
}