merger-js

MergerJS

Yet another lightweight and simple cross-platform CLI build tool to bundle JavaScript files, with file imports, ES6+ minification, auto build capabilities, and native OS notifications.

Because merger uses uglify-es for minification, you don't need to use any kind of transpilers in conjunction with this tool. You can use ES6+.

MergerJS does not support circular dependencies

NPM: LINK
GitHub: LINK
License: MIT
Dependencies:
├── uglify-es
├── neo-async
├── chokidar
├── commander
├── inquirer
├── node-notifier
├── chalk
├── line-by-line

---

Features

• CLI tooling
• Merge multiple JS files into one
• Support for multiple source/build files
• Use @import comments on a source file to specify the build order
• Minification, supporting ES6+ (optional)
• Auto builds on files changes (optional)
• Native OS build notifications (optional)
• Import a directory (use @import<<DIR 'directoryName/')
• Import a file from the node_modules folder (use $import 'file-name')
• Import a file from an URL (use %import 'url')

 

Getting Started

For the latest version of the README, always refer to the MergerJS GitHub repository's master branch:
https://github.com/joao-neves95/merger-js/blob/master/README.md

1) Node.js

You will need Node.js version 10+ installed to run merger.

2) Install merger with NPM

Install globally -g with NPM:

npm i merger-js -g

or

npm install merger-js -g

 

Use:

1. Make a header file (the source file; the first file to be merged) containing, on the top, comments importing the files in the order you want them to be built, from the first to the last.
   Just like in a browser.

   Example:

   // $import 'sweetalert2/dist/sweetalert2.all.min.js'
   // %import 'https://cdnjs.cloudflare.com/ajax/libs/react/16.4.2/cjs/react.development.js'
   // %<<github '/twbs/bootstrap/v4-dev/dist/js/bootstrap.min.js'
   // @'externalLibs'
   // @import<<dir '/enums/'
   // @import 'utilities'
   // @import 'someModel'
   // @import 'someView'
   // @import 'someController'
   // @import 'someOtherModel'
   // @import 'someOtherView'
   // @import 'someOtherController'
   // @import 'someOtherFeature'
   

   • Learn more about the import syntax below in the "Import Syntax" section.
   • Instead of // @import 'fileName', you can just // @'fileName' or $'file-name';
   • The extension names .js are optional;
   • The import of the header file (source file) is optional;
   • You can import files from different directories relative to the same source file.
     Example: // @import '../otherFolder/someFile'

 

1. Run merger init on the root of your project:
   This will set up the configuration model as well as some global configurations (minification, auto builds on file changes, native OS notifications).
   You can alter them later through the CLI with the "merger set" command (learn more below in the "Commands" section).

 

1. Run merger add to add a new source file (header file) to your merger configuration file (learn more below in the "Commands" section).

2. Run merger or merger build to start building (learn more below in the "Commands" section).

 

Import Syntax:

• // @import 'relativePathToTheFile' or // @'relativePathToTheFile':
  Using an @ token on an import statement imports a file relative to the header file.
  

  • Pushing (<<) dir, DIR, directory or DIRECTORY into @import, imports an entire directory. Using this method, the files are not compiled in any specific order.
    E.g.: // @import<<dir '../otherDirectory/' // @<<DIR 'someDirectoryHere/'

• // $import 'pathRelativeToNodeModules' or // $'node_modules_file':
  Using a $ token imports relative to the "node_modules" directory.

• // %import 'https://specificUrl.com/file.min.js' or // $'https://specificUrl.com/file.min.js':
  Using a % token imports a file from a specific URL. The file is downloaded and stored in node_modules in the first time and later fetch from there in order to not download the file in each build.
  

  • Pushing (<<) GH, gh, github or GITHUB into %import, imports a file from a GitHub repository.
    If the branch name is not provided, it defaults to the "master" branch.
    E.g.: // %import<<GH '<userName>/<repositoryName>/<branchName>/<pathToFile>'
// $<<github '/twbs/bootstrap/v4-dev/dist/js/bootstrap.min.js'

 

Commands

• merger init: Configure merger. It creates a merger-config.json file on your working directory.

• merger log: Print the configuration file contents.

• merger add: Add a new source file to the merger config file.
  You should run this command on the directory where the source file you want to add is located.
  MergerJS will give you the directory path, you input the source file name (the extension names are optional), or a relative path to that directory, and MergerJS will locate the configuration file and update it.

• merger rm: Remove a source file from the merger-config file.
  You can run this command anywhere within your project (after the configuration file). MergerJS will give you all your files within your configuration file and you remove one just by selecting it.

• merger or merger build: Execute the build with the configuration you gave it on the merger-config.json file.
  You can run it anywhere within your project's folder.

  • merger auto, merger build -a or merger build --auto: Execute an automatic build session. You can do this, for example, when you have auto builds turned off and you don't want to change that.

• merger set <configuration> <value>: Edit a configuration key on the merger-config file.
  You can run it anywhere within your project's folder.
  At the moment you can pass:

  • The <configuration> mnfy, minify or uglify and the <value> -t / --true or -f / --false to set minification to true or false (on/off);
  • The <configuration> auto or autobuild and the <value> -t / --true or -f / --false to set auto builds to true or false (on/off);
  • The <configuration> ntfs, notifs, notify, or notifications and the <value> -t / --true or -f / --false to set the native OS notifications to true or false (on/off);

  Examples: merger set minify -f, merger set autobuild --true, merger set notifs -t

• merger update: Update MergerJS. Same as npm install merger-js -g

 

Example of a File Structure

|-- root/

|-- merger-config.json
|-- package.json
|-- .env
|-- node_modules/
|-- (...)

|-- server/

|-- (...)

|-- client/

|-- css

|-- (...)

|-- js

|-- mergerBuildFile.js
|-- src

|-- sourceFile.header.js (the header file containing all the imports; the first file to be build)
|-- utilities.js
|-- someOtherView.js
|-- someOtherModel.js
|-- someController.js

 

Known Issues

The auto build does not work properly and all times on Visual Studio. It works very well on Visual Studio Code though.

 

Versioning

Merger uses SemVer for versioning. You can read the changelog here.

 

Code Style

JavaScript Standard Style, with semicolons.

Since version 3.6.5, every asynchronous function should make exclusive use of promises with the async/await syntax, avoiding multiple callback chaining, unless using a callback instead of a promise does make sense and does not contribute to a more confusing code.

 

Motivation

When I started doing academic web projects, I felt the need for a build tool to merge all my JS files into one, cleaning the HTML pages and optimizing my workflow.
I wanted something simple and fast, so I built MergerJS to use in my small web-app projects.