resolve-plugins-sync

Synchronously resolve plugins / transforms / presets just like Babel and Browserify does it, using CommonJS require builtin. For example, useful for loading complex configs from package.json file.

You might also be interested in always-done.

Table of Contents

• Install
• Usage
• Background
  • What and Why?
  • Resolution
• API
  • resolvePluginsSync
• Related
• Contributing
• Building docs
• Running tests
• Author
• License

Install

Install with npm

$ npm install resolve-plugins-sync --save

or install using yarn

$ yarn add resolve-plugins-sync

Usage

For more use-cases see the tests

const resolvePluginsSync = require('resolve-plugins-sync')

// fake
const baz = require('tool-plugin-baz')
const qux = require('tool-plugin-qux')

const result = resolvePluginsSync([
  'foo',
  ['bar', { some: 'options here' }],
  [baz, { a: 'b' }],
  qux
], {
  prefix: 'tool-plugin-'
})

Background

What and Why?

Because we need. Because many famous tools do exact same thing. They use same kind of resolution of their presets, plugins, transforms and whatever you wanna call it. This one is pretty configurable and small. Most of this resolution can be seen in the users package.jsons configs.

For example browserify.transform field in package.json

{
  "browserify": {
    "transform": [
      "babel",
      ["uglifyify", {
        "compress": true
      }]
    ]
  }
}

And because both babel and browserify uses same resolution things may gone more wild.

Let's take this example

{
  "browserify": {
    "transform": [
      ["babel", {
        "presets": [
          ["es2015", {
            "modules": false
          }]
        ],
        "plugins": [
          ["react", { "some": "more options" }]
          "add-module-exports"
        ]
      }],
      ["uglifyify", {
        "compress": true
      }]
    ]
  }
}

And so on, and so on... infinite nesting. That's just freaking crazy, right?

That's all about what this package does - you give it an array and it does such thing - in case with Browserify if they use this package they should pass browserify.transform as first argument.

It's so customizable that it match to all their needs - both for Babel plugins/presets/transforms and Browserify transforms. The browserify transforms are a bit different by all others. They accept filename, options signature. And so, because they don't accept options as first argument, like Babel's transforms or like Rollup's plugins, we need a bit configuration to make things work for Browserify.

That's why this package has opts object through which you can pass opts.first to set first argument for the plugin/transform function. Another thing that you can do is to pass opts.args if you want more control over the passed arguments to the plugin/transform function.

Resolution

How we resolve plugins? Resolving algorithm has 4 steps. You should know that in the following paragraphs item means each element in the passed array to resolvePluginsSync().

1) If item is string, it tries to require it from locally installed dependencies, calls it and you can pass a opts.prefix which will be prepended to the item string. Think for it like rollup-plugin-, babel-plugin-, gulp- and etc. You may want to see the comments for resolveFromString inside the source code.

2) If item is function, it will call it and if you want to pass arguments to it you can pass opts.args array or opts.first. If opts.args is passed it calls that item function with .apply. If opts.first is passed it will pass it as first argument to that function.

3) If item is object, nothing happens, it just returns it in the result array.

4) If item is array, then there are few possible scenarios (see comments for resolveFromArray inside the source code):

• if 1st argument is string - see 1
• if 1st argument is function - see 2
• if 2nd argument is object it will be passed to that resolve function from 1st argument

API

resolvePluginsSync

Babel/Browserify-style resolve of a plugins array and optional opts options object, where each "plugin" (item in the array) can be

1. string, 2) function, 3) object or 4) array. Useful for loading complex and meaningful configs like exactly all of them - Babel, ESLint, Browserify. It would be great if they use that package one day :) The rolldown bundler already using it as default resolution for resolving rollup plugins. :)

Params

• array {Array|String}: of "plugins/transforms/presets" or single string, which is arrayified so returned result is always an array
• opts {Object}: optional custom configuration
• opts.prefix {String}: useful like babel-plugin- or rollup-plugin-
• opts.context {Any}: custom context to be passed to plugin function, using the .apply method
• opts.first {Any}: pass first argument for plugin function, if it is given, then it will pass plugin options as 2nd argument, that's useful for browserify-like transforms where first argument is filename, second is transform options
• opts.args {Array}: pass custom arguments to the resolved plugin function, if given - respected more than opts.first
• returns {Array}: result resolved plugins, always an array

Example

const resolve = require('resolve-plugins-sync')

// fake
const baz = require('tool-plugin-baz')
const qux = require('tool-plugin-qux')

resolve([
  'foo',
  ['bar', { some: 'options here' }],
  [baz, { a: 'b' }],
  qux
], {
  prefix: 'tool-plugin-'
})

Related

• always-done: Handle completion and errors with elegance! Support for streams, callbacks, promises, child processes, async/await and sync functions. A drop-in replacement… more | homepage
• minibase: Minimalist alternative for Base. Build complex APIs with small units called plugins. Works well with most of the already existing… more | homepage
• try-catch-core: Low-level package to handle completion and errors of sync or asynchronous functions, using once and dezalgo libs. Useful for and… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guidelines for advice on opening issues, pull requests, and coding standards.
If you need some help and can spent some cash, feel free to contact me at CodeMentor.io too.

In short: If you want to contribute to that project, please follow these things

1. Please DO NOT edit README.md, CHANGELOG.md and .verb.md files. See "Building docs" section.
2. Ensure anything is okey by installing the dependencies and run the tests. See "Running tests" section.
3. Always use npm run commit to commit changes instead of git commit, because it is interactive and user-friendly. It uses commitizen behind the scenes, which follows Conventional Changelog idealogy.
4. Do NOT bump the version in package.json. For that we use npm run release, which is standard-version and follows Conventional Changelog idealogy.

Thanks a lot! :)

Building docs

Documentation and that readme is generated using verb-generate-readme, which is a verb generator, so you need to install both of them and then run verb command like that

$ npm install verbose/verb#dev verb-generate-readme --global && verb

Please don't edit the README directly. Any changes to the readme must be made in .verb.md.

Running tests

Clone repository and run the following in that cloned directory

$ npm install && npm test

Author

Charlike Mike Reagent

• github/tunnckoCore
• twitter/tunnckoCore
• codementor/tunnckoCore

License

Copyright © 2016-2017, Charlike Mike Reagent. MIT

This file was generated by verb-generate-readme, v0.6.0, on October 10, 2017.
Project scaffolded using charlike cli.