@webpack-utilities/loader

    1.0.0-alpha.0 • Public • Published

    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)
    } 

    Keywords

    none

    Install

    npm i @webpack-utilities/loader

    DownloadsWeekly Downloads

    11

    Version

    1.0.0-alpha.0

    License

    MIT

    Unpacked Size

    21.5 kB

    Total Files

    17

    Last publish

    Collaborators

    • michael-ciniawsky