prebuilder v0.0.1

Motivation

When building anything with javascript / typescript, sometimes we would want to have granular control over our codebase by conditionally including/excluding code or have different code for a specific build preset.

This is very useful in various cases, like for example:

• Building different versions for:
  • different platforms
    • ex: having a windows / unix specific default path
    • ex: having a different api url for desktop / mobile platforms
    • ex: importing "path" when building for Node.js, or npm's "browser-path" when building for browser
  • different client / server versions
• Migrating to a newer version of a dependecy, in a non-destructive way, by retaining old version of code (allowing to go back if needed).
• Enabling assertions, debugging and any sort of backdoor in non-production builds.
• Simplifying unit testing by including test functions only in non-production builds.

Features

• Source analysis: remembers which are unchanged source files, and skips them for a faster preprocess.
• Comprehensive internal flow checks: preprocess errors do not stop prebuilding mid-way avoiding any loss of data.
• Ease-of-use thanks to a Rollup helper and a Typescript helper

Other packages

• @prebuilder/lib A preprocess utility usable in Node.js and/or in the browser
• @prebuilder/rollup A Prebuilder helper for an out of the box Rollup integration
• @prebuilder/tsc A Prebuilder helper for an out of the box Typescript integration
• @prebuilder/rollup-plugin A Rollup plugin for very simple use cases

Install

npm i --save-dev prebuilder

prebuild resolve --srcDir "src" --outDir "pre-build" --preprocessDefines "TARGET_BROWSER, ANDROID"

Case 1) import depending on target platform

#if TARGET_BROWSER
import path from 'browser-path';
#else
const path = require('path');
#endif

import path from 'browser-path';

Case 2) debugging & testing

class MyClass {

   constructor(apiUrl) {
       this.apiUrl = apiUrl;
       this.myData = fetchData(apiUrl);
   }

   #if DEBUG
   // log info
   console.log("api: " +this.apiUrl);
   // test
   Test = () => {
      console.log("MyClass test:");

      try {
         JSON.parse(this.myData);
         console.log("data ✔");
      } catch {
         console.error("data ✘");
      }
   }
   #endif
}

class MyClass {

   constructor(apiUrl) {
      this.apiUrl = apiUrl;
      this.myData = fetchData(apiUrl);
   }















}

Case 3) Function definition depending on feature support

    // negative #if
#if !PARAM_2_SUPPORTED
    var myFunction = (param) => {
        return param + 1;
    }
#else
    var myFunction = (param1, param2) => {
        return param * param2 + 1;
    }
#endif

    var myFunction = (param) => {
        return param + 1;
    }

Case 4) Variable definition depending on platform

    // commented mode
//#if ANDROID
   myConfig = {
      apiUrl:"api.site.net/android",
      greeting: "Hi Android user!",
   };
//#endif
//#if IOS
   //#post-code myConfig = {
   //#post-code    apiUrl: "api.site.net/ios",
   //#post-code    greeting: "Hi iOS user!"
   //#post-code };
//#endif

myConfig = {
    apiUrl: "api.site.net/android",
    greeting: "Hi Android user!",
};

Commands

Resolves directives in every script of a given source folder, and caches their original versions.

prebuild resolve --srcDir "src"

Restores back original scripts (with unresolved directives) if resolved with --onTheSpot mode.

prebuild restore

Resolves scripts, executes a given command then restores them back. This is useful to run bundlers and linters on resolved code, thus avoiding runtime errors.

prebuild wrap "my command" --srcDir "src"

Prints command line info on this tool.

prebuild --help

Planned features

• ☑ use a config .js file
• ☑ (optional) resolve files in same folder
• ☑ watch mode
• ☐ include / exclude files & folders
• ☐ implement #elseif directive
• ☐ implement #put directive
• ☐ implement #define-local directive
• ☐ comment mode support for html
• ☐ comment mode support for css
• ☐ inline directives
• ☐ prebuild multiple sources concurrently
• ☐ directive extensibility
• ☐ plugins
• ☐ config file extensibility

Current limitations

• commented mode requires no space between double slash and directive //#if not // #if (solution planned).

v 1.1

• Load configuration from file
• bugfix: parseArgs returns null

v 1.2

• Added possibility to resolve files to a specific folder, as default
• resolution in same folder as source with --onTheSpot parameter
• resolve files to a specific folder as default with --outDir
• Renamed preduild start command to preduild wrap
• Renamed --dir command to --srcDir
• Hide temp folder on windows

v 1.3

• Added watch mode
• Added wrap feature: run command only the first time, when passing it to wrap() with watch mode active (useful when running tools in watch mode)
• Added wrap feature: run command in another process to avoid freezing prebuilder (useful when running tools in watch mode)

Licence

MIT