@webpack-utilities/loader

webpack Loader Utils

Stats

StarsIssuesVersionUpdatedCreatedSize
@webpack-utilities/loader
001.0.0-alpha.03 years ago3 years agoMinified + gzip package size for @webpack-utilities/loader in KB

Readme

npm node deps test coverage code style chat

Loader Utils

webpack Loader Helpers

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 returned options 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&params), 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 of JSON.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)
} 

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.