About the Build Process

By virtue of being an interpreted language, JavaScript code is able to simply be executed "as-is" by a JavaScript interpreter such as the ones in hackmud, Node.js, and in your web-browser. On the other hand, languages such as the C family must first be translated into machine code by a compiler before they can be executed. So if JavaScript doesn't need to be compiled, why then does hackshell need a "build process"?

The short answer is that it doesn't - the hackshell source files can actually be used as-is in environments that support the latest JavaScript feature set. But most JavaScript environments don't support all of the language features that hackshell utilizes, so through a process called "transpilation" the hackshell source files are turned into files which nearly every popular JavaScript interpreter can understand.

More specifically, the hackshell source files in lib are written using relatively new language features implemented in a version of JavaScript referred to as ES6 or ES2015 - this is the same version of JavaScript which the hackmud interpreter was written to support (with many limitations).

Transpiling removes a lot of the requirements necessary to run hackshell, and additionally ensures it can be used in Node.js and web-browsers alike (a requirement since hackshell is used both in the browser as well as server-side to power the hackdev editor).

Build Process

The build process starts by looking over the source files for potential problems and strange coding practices in a process known as "linting" (here performed by the wonderful ESLint project). It then reports any problems it encounters and where they are allowing contributors to address them if needed. This is a function often provided by IDEs.

If no obvious errors are found which would prevent hackshell from functioning properly, the source files are then passed to the Rollup module bundler.

Rollup starts by taking a look at the file lib/index.js, then recursively grabs all of the referenced source files, transpiles them into more universal forms of JavaScript using Babel, concatenates the transpiled code into one chunk, then spits out the result into a file called a "bundle" in the dist directory.

Bundles

The hackshell build process creates two bundle files, both which contain all of the code necessary to use hackshell.

• dist/hackshell.js is a "legacy" bundle packaged in a format called a "Universal Module Definition" with support for what is more or less the lowest common denominator when it comes to JavaScript language features. In short, hackshell.js is suitable for dropping into a web-page or require()ing into virtually any version of Node, and it should "just work" without worrying about which JavaScript features the environment supports.
• dist/hackshell.mjs is a more "modern" bundle which retains most of ES6 features, and is thus executable in browsers and Node environments which support them.

Sourcemaps

The build process also creates a .map file for every bundle it produces. These are called "sourcemaps", and they describe how bundled code relates to the code in the lib source files.

Sourcemaps play an important role in debugging. Without a sourcemap, if an error occurs in transpiled code a developer would have to figure out which source code produced that transpiled code before the error could be corrected. With sourcemaps, developers can execute transpiled code while examining source files and errors can be described in relation to the source which produced them rather than the garbled translation.