common-exports

Convert ES Modules (even in dependencies) to CommonJS. Resolves dependency issues and creates both ES and CommonJS module compatibility for packages.

Goals

Using this tool suite, you can:

• Convert packages in node_modules from es6 Module into cloned CommonJs module (this will be stored in a directory of your choosing)
• Convert your own project from es6 Module into cloned CommonJs module, so you can distribute more compatible code

Installation

In your project's root directory, run: npm install --save-dev gulp common-exports (or yarn add --dev gulp common-exports if you use Yarn).

It is recommended to install gulp with the -g flag, so that you can run it with gulp instead of node_modules/.bin/gulp.

Usage

In your gulpfile.js add the following:

const convertCommon = () => {
  const { makeCommon } = require('common-exports')
  const mainFile = 'path to the main file you wish to convert'
  const vendorPath = 'path to the directory where your exported file (and dependencies) should go'
  return makeCommon(mainFile, vendorPath, { rootPath: './' })
}

exports.convertCommon = convertCommon

Create a babel.config.js file if you do not already have one and add the following content:

module.exports = {
  plugins: [
    '@babel/plugin-transform-modules-commonjs'
  ],
  presets: [
    [
      '@babel/preset-env',
      {
        useBuiltIns: 'usage',
        corejs: { version: '3.6', proposals: true },
        targets: { node: 'current' }
      }
    ]
  ]
}

The import configuration above is the use of the plugin-transform-modules-commonjs plugin since that will do the major work of converting each file.

If you are copying packages from node_modules, ensure that you change your .gitignore for node_modules to be /node_modules instead to allow subdirectories to be included if you need them bundled.

Make sure to use the correct main file you wish to start conversion at and also the output directory for the conversion.

common-exports

Bundle a project or vendor projects for usage as CommonJS AND ES6 modules.

Version: 1.0.0
Author: Joshua Heagle [email protected]

• common-exports
  • .checkPackageExports(exports, modulePath) ⇒ string | null
  • .copyResources(baseFilePath, [config]) ⇒ undefined
  • .customChanges(baseFilePath, content, [config]) ⇒ string
  • .findImports(fileContents) ⇒ Array
  • .importRegex() ⇒ string
  • .isCommonModule(moduleInfo) ⇒ boolean
  • .makeModuleInfo(dirPath, moduleName, rootPath) ⇒ Array.<ModuleInfo>
  • .replaceImportMeta(content) ⇒ string
  • .replaceImports(srcPath, destPath, [config]) ⇒ reduceImports
  • .resolveImports(file, [rootPath]) ⇒ Array.<ModuleInfo>
  • .resolveMainFile(modulePath) ⇒ string | null
  • .resolveModule(root, moduleName, current) ⇒ Array.<string>
  • .resolvePackageExports(packageData, modulePath) ⇒ string | null
  • .verifyModule(moduleName, current) ⇒ Array.<string> | null
  • .makeCommon(srcPath, destPath, [config]) ⇒ stream.Stream

common-exports.checkPackageExports(exports, modulePath) ⇒ string | null

Given the configured exports from a package, determine the preferred entry path.

Kind: static method of common-exports

| Param | Type | Description | | --- | --- | --- | | exports | object | string | The relative path used to locate the module. | | modulePath | string | |

common-exports.copyResources(baseFilePath, [config]) ⇒ undefined

Based on configured 'copyResources', if we are in the corresponding based path copy each src to dest.

Kind: static method of common-exports

| Param | Type | Default | Description | | --- | --- | --- | --- | | baseFilePath | string | | The source / module path to process. | | [config] | Object.<'copyResources', Object.<string, Array.<Object.<('src'|'dest'|'updateContent'), (string|function())>>>> | {} | The copyResources config may be present, and if it has the source path as a property, then the src and dest will be used to copy resources. |

common-exports.customChanges(baseFilePath, content, [config]) ⇒ string

Based on configured 'customChanges', if we are in the corresponding based path, apply the change function to the content.

Kind: static method of common-exports

| Param | Type | Default | Description | | --- | --- | --- | --- | | baseFilePath | string | | The source / module path to process. | | content | string | | The file content which will receive changes. | | [config] | Object.<'customChanges', Object.<string, Array.<Object.<'updateContent', function()>>>> | {} | The customChanges config may be present, and if it has the source path as a property, then the updateContent function will be applied to the contents. |

common-exports.findImports(fileContents) ⇒ Array

Retrieve all the module names from imports.

Kind: static method of common-exports

| Param | Type | Description | | --- | --- | --- | | fileContents | string | The string of contents to parse for import matches. |

common-exports.importRegex() ⇒ string

Get the regex for detecting ES6 import statements.

Kind: static method of common-exports

common-exports.isCommonModule(moduleInfo) ⇒ boolean

Attempt to detect if the current module is a common js module.

Kind: static method of common-exports

| Param | Type | Description | | --- | --- | --- | | moduleInfo | Object.<(module|path|file), (string|null)> | An object containing the module, path, and file strings. |

common-exports.makeModuleInfo(dirPath, moduleName, rootPath) ⇒ Array.<ModuleInfo>

Create the Module Info object to store the name, path, and file for each matching module.

Kind: static method of common-exports

| Param | Type | Default | Description | | --- | --- | --- | --- | | dirPath | string | | Current relative directory to search. | | moduleName | string | | Path used in the import for the module. | | rootPath | string | null | The lowest path to search within for the module. |

common-exports.replaceImportMeta(content) ⇒ string

Find usages of import.meta and replace it with CommonJs compatible substitute.

Kind: static method of common-exports

| Param | Type | Description | | --- | --- | --- | | content | string | String of file contents to search for import.meta usage. |

common-exports.replaceImports(srcPath, destPath, [config]) ⇒ reduceImports

Take a srcPath, destPath, then return a function to reduce the content for replacing file imports.

Kind: static method of common-exports

| Param | Type | Default | Description | | --- | --- | --- | --- | | srcPath | string | | The original path of the file to be updated. | | destPath | string | | The outgoing path of the file once updated. | | [config] | Object.<string, Object.<string, *>> | {} | Additional configuration options. |

common-exports.resolveImports(file, [rootPath]) ⇒ Array.<ModuleInfo>

Given a file with buffer contents, identify all the imports it has and find their full paths.

Kind: static method of common-exports

| Param | Type | Default | Description | | --- | --- | --- | --- | | file | StreamFile | | The in-memory fetched file object. | | [rootPath] | string | null | null | The root path to use when resolving imports. |

common-exports.resolveMainFile(modulePath) ⇒ string | null

Given a module path, find the file which should be used as main, based on module import.

Kind: static method of common-exports

| Param | Type | Description | | --- | --- | --- | | modulePath | string | The relative path used to locate the module. |

common-exports.resolveModule(root, moduleName, current) ⇒ Array.<string>

Search for the given module and return the full path.

Kind: static method of common-exports

| Param | Type | Description | | --- | --- | --- | | root | string | The base path for searching. | | moduleName | string | The import name used for retrieving the module. | | current | string | The current directory we are checking for module matches. |

common-exports.resolvePackageExports(packageData, modulePath) ⇒ string | null

Given the package details, determined the configured module entry point.

Kind: static method of common-exports

| Param | Type | Description | | --- | --- | --- | | packageData | object | string | The package contents as an object. | | modulePath | string | |

common-exports.verifyModule(moduleName, current) ⇒ Array.<string> | null

Check if the current path contains the module we are looking for.

Kind: static method of common-exports

| Param | Type | | --- | --- | | moduleName | string | | current | string |

common-exports.makeCommon(srcPath, destPath, [config]) ⇒ stream.Stream

Apply babel to source files and output with commonJs compatibility.

Kind: static method of common-exports

| Param | Type | Default | Description | | --- | --- | --- | --- | | srcPath | string | array | | The relative path to the file to convert. | | destPath | string | | The relative path to the output directory. | | [config] | Object.<string, *> | {} | Add additional instructions to the process. | | [config.copyResources] | Object.<string, Array.<Object.<(src|dest|updateContent), (string|function())>>> | {} | Add custom files to copy for found modules. | | [config.customChanges] | Object.<string, Array.<Object.<updateContent, function()>>> | {} | Add custom content changes to the content used. | | [config.rootPath] | string | "''" | Specify the root to use, this helps identify where to stop. |