LS-WebBuilder

The LS-WebBuilder is a bundle tool that provides support of native import and export syntax in current web browsers down to IE 11.

Features

Combines all js files and needed assets like html and css.

Converts less files automatically to css on build time

Transpiles the javascript code with babel

Support TypeScript

Minifies production code and generate sourceMaps

Caches built files to improve build time:

• First build with around 600 js/ts files need 30+ seconds
• Later builds with only some modified files 1+ seconds

Installation

npm install -g ls-webbuilder

local installation is also possible

Usage

lsbuild

Command-line parameters

• --task=task-name
  • run the task with name task-name
• --clean[=all] | --clear[=all]
  • delete cache for current task
  • [delete all caches]
• --cache=cachePath
  • set cache path for the current build
• --path=projectPath
  • build the project under specified path
• -d | --dev | --develop | --development
  • same as --task=development (is the default behavior, if no task arg is given)
• --prod-test | --production-test
  • same as --task=production_test
• -p | --prod | --production
  • same as --task=production

Configuration

The lsbuild.json file defines the build configuration. It contains on root level an object with the following possible properties:

• outputDir
  • The target directory (default out)
• outputFile
  • The name of the result js file (default the name of the folder)
  • /projectName/lsbuild.json => projectName.js
• src
  • An array with included source files and folders (default ["src"])
  • supports glob
  • can be used to define an order
    • ["src/fileA.js", "src/fileB.js", "src/**"] will load all files in src folder but at first fileA.js then fileB.js
• aliases
  • An object with alias definitions
  • As key the "original" import path
  • As value a string oder string array with alternative import paths
• constantModules
  • An object with expressions that are available via module
  • constantModules: {"myConst": "function() {return window.screen.availHeight;}"}
  • import myConstant from 'myConst';
  • myConstant is then a function which will return the availHeight of the screen
• providedNodeModules
  • An array of installed node_modules to allow import without bundling
  • providedNodeModules: ["express"]
  • import * as express
  • Imports express on runtime
• extends
  • A relative path to another lsbuild.json file to inherit its properties
• environment
  • Contains definitions of the target browser technology
  • It should contain a development and a production environment
  • substructure:
    • targets
      • A map of browser versions {"chrome": "49", "node": "10", "ie": "9"}
  • The development environment can be a new browser in which you develop most time like chrome 70 but the production environment will be the browser you really want to support like ie 11 so the code will be transpiled in --dev for chrome 70 but in --prod-test or --prod for ie 11
• addInitLib
  • Initializes the ls-webbuilder framework.
  • Is only needed in the first loaded library but can be included in every lib
  • default false
• autoStart
  • The classes are initialized after System.start() is called.
  • This parameter appends the call at the end of the generated file
  • default false
• clean
  • Deletes the build cache before start building (same as --clean) (default false)
• skipSourcemaps
  • Prevents the sourcemap generation (default false)
• sourcemapPath
  • Sets an explicit sourcemapPath like http://example.com/mySourcemap.map
  • Can also be inline for inline sourcemaps and null for relative path to the generated sourcemap maps/jsName.js.map
  • default null
• modulePrefix
  • Can be defined to shrink the module paths.
  • It is a prefix which will be removed from each module
  • default is src/ so src/path/to/file will result in path/to/file
• lessToCss
  • converts all .less files to css code (default true)
• extensions
  • Treat listed extensions as specified type (relevant for compression)
  • extensions: {"myExtension": "xml", "myPictureFormat": "base64"}
  • extensions are case-insensitive

Default Extension behavior:

• js: .js
• ts: .ts
• less: .less
• css: .css
• html: .html
• xml: .xml
• json: .json
• json5: .json5
• base64: .png, .jpg / .jpeg, .gif, .bmp, .tiff / .tif, .svg (images are prefixed with data:image... stuff)
• text: all other extensions

Example

src/FileA.js

export class A {
    static method() {
        // your code here
    }
}

src/FileB.js

import {A} from './FileA.js';

export class B extends A {
    static anotherMethod() {
        // again your code
    }
}

package.json

{
  "name": "ExampleProject",
  "version": "1.0.0",
  "description": "My fancy project",
  "scripts": {
    "exampleTask": "lsbuild"
  }
}

lsbuild.json

{
  "extends": "./node_modules/my_config/lsbuild.json",
  "clean": false,
  "outputDir": "dist",
  "outputFile": "bundle.js",
  "addInitLib": true,
  "autoStart": true,
  "src": ["src"],
  "modulePrefix": "src/",
  "lessToCss": true,
  "skipSourcemaps": false,
  "sourcemapPath": "inline",
  "providedNodeModules": ["express"],
  "constantModules": {
    "vue": "globalThis.Vue"
  },
  "aliases": {
    "vue": "myVue", // allows import Vue from 'myVue'
    "src/path/to/module": ["myModuleAlias", "src/my/fancy/module/alias"]
  },
  "extensions": {
    ".svg": "html" // to use html compression and use as string in code
  },
  "environment": {
    "development": {
      "targets": {
        "chrome": "76"
      }
    },
    "production": {
      "targets": {
        "ie": "11",
        "edge": "17",
        "chrome": "70",
        "safari": "10",
        "firefox": "68"
      }
    }
  }
}

call possibilities

npm run exampleTask
lsbuild
lsbuild --prod
npx ls-webbuilder

index.html

<!DOCTYPE html>
<html>
    <head>
        <script src="dist/bundle.js"></script>
    </head>
    <body>
        <!-- DO SOMETHING -->
    </body>
</html>

Changelog

0.4.12 - 0.4.13

• [FIX] missing code with multiple minified included projects

0.4.11

• [FEATURE] parse tsconfig and lsbuild files as json5 to e.g. support comments
• [FIX] support scoped projects (@scope/package) as "includedProject"

0.4.10

• [FIX] wrong line endings in binary script

0.4.9

• [HOTFIX] incompatibility with babel sub-dependencies

0.4.8

• [BREAKING] useLegacyProperties default value set to false
• [FEATURE] cache build result for faster rebuild without changes
• [HOTFIX] sometimes missing linebreaks after sourcemap comment
• [FIX] broken sourcemap file names
• [FIX] find node_modules sibling dependencies

0.4.7

• [FEATURE] allow importing installed node_modules
• [FIX] sometimes not detect outdated files
• [FIX] sometimes sourcemap comment breaks result js
• [FIX] prevent duplicate "includedProjects"
• [FIX] detect config changes and rebuild files
• [FIX] remove massive alias and constant module redundancies
• [FIX] platform dependent line breaks

0.4.6

• [HOTFIX] Preserve compatibility

0.4.4 - 0.4.5

• [HOTFIX] NullPointerException

0.4.3

• [FIX] better import analysis to reduce overhead and force needed imports to initialize first
• [HINT] new "useLegacyProperties": false lsbuild.json option to use non-loose class properties (allows typescript declare usage to override property types)

0.4.2

• [POLISHING] better error messages for failed js/ts transformations
• [FIX] relocate the cache for npx usage

0.4.1

• [FIX] update babel dependencies

0.4.0

• [FEATURE] support glob for src configuration
• [FEATURE] new alias feature: alias for import paths
• [FEATURE] constant modules: import myConst from 'myConst'
• [FEATURE] include other projects: you can split your projects now but bundle them still in one file
• [FEATURE] support image files as base64 data-uri
• [FEATURE] customizable file extension - type mapping
• [FEATURE] automatically resolve url(myPath) expressions in .less files to data-uri
• [BREAKING] .svg files are now imported as base64 data-uri by default
• [FIX] handle outputDir relative to project instead of cwd (current working directory) #4

0.3.8

• [FEATURE] support /index as default import for .js .ts and .d.ts
• [FEATURE] Use all defaults for non-lsbuild projects

0.3.7

• [UPDATE] update dependencies to support new ts features optional-chaining and nullish-coalescing

0.3.6

• [FIX] issue with exported typescript enums

0.3.4 - 0.3.5

• [POLISHING] treat .js imports as extension less imports for better typescript porting

0.3.3

• [POLISHING] Prevent error if source files or folder not exist. Missing paths will be logged

0.3.2

• [FEATURE] add method "System.registerAlias" to allow different names for the same module
• [API] better backwards compatibility for typescript files

0.3.0 - 0.3.1

• [API] new configuration file lsbuild.json (instead of package.json)
• [FEATURE] set individual cache directory --cache=path/to/cache
• [FEATURE] auto detect dependencies
• [FEATURE] support .xml files
• [FEATURE] full support for different local builder versions
• [FEATURE] support .d.ts files as import
• [POLISHING] improve performance
• [CLEANUP] remove gulp as dependency

0.2.12

• [FIX] clear buffers after System.start

0.2.8 - 0.2.11

• [FEATURE] add native class properties support

0.2.7

• [FIX] allow extension-less imports in typescript also for js files

0.2.6

• [FIX] Broken TypeScript support
• [FIX] autoStart fixed
• [FEATURE] log import path of invalid imports

0.2.5

• [FEATURE] Less Files: support tilde ~ prefix for node_module imports @import '~myModule/test.less';

0.2.3 - 0.2.4:

• [FIX] error when non-node dependencies where in node_modules folder

0.2.2:

• [FIX] error when require folder node_modules, global modules worked

0.2.1:

• [FIX] error with exported functions

0.2.0:

• [FEATURE] typescript support
• [FEATURE] support svg and json compression
• [FEATURE] compile json5 to json
• [FEATURE] improve SourceMaps result
• [FEATURE] add more default configurations
• [UPDATE] update dependency versions
• [FIX] prevent dependency file processing
• [FIX] error if cached file is deleted
• [FIX] support dependencies for dependencies (node_modules)

0.1.2:

• [FIX] node_modules were not fully supported

0.1.1:

• [FIX] ModulePrefix did not work
• [FIX] System.require returned nothing
• [FIX] export function did not work correctly

0.1.0:

• first stable version with es6 import/export

Roadmap

• check imports for already cached files to prevent errors
• allow to override classes
• project bundling
• support for node_modules without lsbuild config
• check eslint on build time
• unit tests on build time

Contact

You need support or want to support my project? Please contact me: [email protected]