ls-webbuilder/README.md

Can be used by projects to build a full standalone web application. Orders, concats, uglifies and transpiles the js or ts source and append some other assets like referenced html and css/less files

# 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

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

src/FileB.js

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

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

package.json

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

lsbuild.json 
```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
```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: webbuilder@lseawalker.de