Ls-webbuilder NPM

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.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