@remotex-labs/xbuild 2.1.4 → 2.1.6

package/README.md

@@ -1,8 +1,11 @@
 # xBuild
-[![npm version](https://img.shields.io/badge/Documentation-orange?logo=typescript&logoColor=f5f5f5)](https://remotex-labs.github.io/xBuild/)
+
+[![Documentation](https://img.shields.io/badge/Documentation-orange?logo=typescript&logoColor=f5f5f5)](https://remotex-labs.github.io/xBuild/)
 [![npm version](https://img.shields.io/npm/v/@remotex-labs/xbuild.svg)](https://www.npmjs.com/package/@remotex-labs/xbuild)
 [![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
-[![Node.js CI](https://github.com/remotex-labs/xBuild/actions/workflows/test.yml/badge.svg)](https://github.com/remotex-labs/xBuild/actions/workflows/test.yml)
+[![Node.js CI](https://github.com/remotex-labs/xbuild/actions/workflows/test.yml/badge.svg)](https://github.com/remotex-labs/xBuild/actions/workflows/test.yml)
+[![Discord](https://img.shields.io/discord/1364348850696884234?logo=Discord&label=Discord)](https://discord.gg/psV9grS9th)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/remotex-labs/xBuild)
 
 `@remotex-labs/xbuild` is a versatile TypeScript toolchain build system
 
@@ -26,8 +29,6 @@ Run the `xBuild -h` CLI tool with various options to build your typeScript proje
 Command-Line Options
 
 ```bash
-
-
      ______       _ _     _
      | ___ \     (_) |   | |
 __  _| |_/ /_   _ _| | __| |
@@ -37,70 +38,69 @@ __  _| |_/ /_   _ _| | __| |
 
 Version: <xBuild version>
 
-index.js [file]
+Usage: xBuild [files..] [options]
 
-A versatile JavaScript and TypeScript toolchain build system.
+xBuild Options:
+      --entryPoints         Specific files to build (supports glob patterns)
+                                                                         [array]
+      --typeCheck, --tc     Perform type checking without building output
+                                                                       [boolean]
+  -p, --platform            Target platform for the build output
+                                [string] [choices: "browser", "node", "neutral"]
+  -s, --serve               Start server to the <folder>                [string]
+  -o, --outdir              Directory for build output files            [string]
+      --declaration, --de   Generate TypeScript declaration files (.d.ts)
+                                                                       [boolean]
+  -w, --watch               Watch mode - rebuild on file changes       [boolean]
+  -c, --config              Path to build configuration file
+                                          [string] [default: "config.xbuild.ts"]
+      --tsconfig, --tsc     Path to TypeScript configuration file       [string]
+  -m, --minify              Minify the build output                    [boolean]
+  -b, --bundle              Bundle dependencies into output files      [boolean]
+      --types, --btc        Enable type checking during build process  [boolean]
+      --failOnError, --foe  Fail build when TypeScript errors are detected
+                                                                       [boolean]
+  -f, --format              Output module format
+                                        [string] [choices: "cjs", "esm", "iife"]
+  -v, --verbose             Verbose error stack traces                 [boolean]
+      --build, --xb         Select an build configuration variant by names (as
+                            defined in your config file)                 [array]
 
 Positionals:
-  entryPoints  The file entryPoints to build                            [string]
+  entryPoints  Specific files to build (supports glob patterns)          [array]
 
 Options:
-  -h, --help                  Show help                                [boolean]
-      --typeCheck, --tc       Perform type checking                    [boolean]
-  -n, --node                  Build for node platform                  [boolean]
-  -d, --dev                   Array entryPoints to run as development in Node.js
-                                                                         [array]
-      --debug, --db           Array entryPoints to run in Node.js with debug sta
-                              te                                         [array]
-  -s, --serve                 Serve the build folder over HTTP         [boolean]
-  -o, --outdir                Output directory                          [string]
-      --declaration, --de     Add TypeScript declarations              [boolean]
-  -w, --watch                 Watch for file changes                   [boolean]
-  -c, --config                Build configuration file (js/ts)
-                                          [string] [default: "xbuild.config.ts"]
-      --tsconfig, --tsc       Set TypeScript configuration file to use
-                                             [string] [default: "tsconfig.json"]
-  -m, --minify                Minify the code                          [boolean]
-  -b, --bundle                Bundle the code                          [boolean]
-      --noTypeChecker, --ntc  Skip TypeScript type checking            [boolean]
-      --buildOnError, --boe   Continue building even if there are TypeScript typ
-                              e errors                                 [boolean]
-  -f, --format                Defines the format for the build output ('cjs' | '
-                              esm' | 'iif').                            [string]
-  -v, --version               Show version number     [boolean] [default: false]
-
+  -h, --help     Show help                                             [boolean]
+      --version  Show version number                                   [boolean]
+
+Examples:
+  xBuild src/index.ts                       Build a single file with default
+                                            settings
+  xBuild src/**/*.ts --bundle --minify      Bundle and minify all TypeScript
+                                            files
+  xBuild src/app.ts -s                      Development mode with watch and dev
+                                            server
+  xBuild src/app.ts -s dist                 Development mode with watch and dev
+                                            server from dist folder
+  xBuild src/lib.ts --format esm            Build ESM library with type
+  --declaration                             definitions
+  xBuild src/server.ts --platform node      Build Node.js application to dist
+  --outdir dist                             folder
+  xBuild --typeCheck                        Type check only without generating
+                                            output
+  xBuild --config custom.xbuild.ts          Use custom configuration file
+
+For more information, check the documentation
+https://remotex-labs.github.io/xBuild/
 ```
 
 ## Configuration
 
 The `xBuild` configuration file allows you to customize various settings for the build and development process.
-By default, xbuild uses `xbuild.config.ts` (`--config` change it). Here’s how you can configure it:
+By default, xbuild uses `config.xbuild.ts` (`--config` change it). Here's how you can configure it:
 
 ### Example Configuration
-```ts
-const config: ConfigurationInterface = {
-    declaration: true,
-    buildOnError: false,
-    noTypeChecker: false,
-    esbuild: {
-        entryPoints: ['./src/index.ts'],
-        bundle: true,
-        minify: true,
-        format: 'esm',
-    },
-    serve: {
-        active: true,
-        port: 8080,
-        host: 'localhost',
-        onRequest: (req, res, next) => {
-            console.log('Server request received');
-            next();
-        }
-    }
-};
-```
 
-You can also define multiple configurations as an array:
 ```ts
 /**
  * Import will remove at compile time
@@ -119,90 +119,85 @@ import pkg from './package.json' with { type: 'json' };
  * Config build
  */
 
-const config: Array<xBuildConfig> = [
-    {
-        declaration: true,
+export const config: xBuildConfig = {
+    common: {
+        define: {
+            __VERSION: pkg.version
+        },
         esbuild: {
             bundle: true,
             minify: true,
             format: 'esm',
-            outdir: 'dist/esm',
             target: [ `node${ version.slice(1) }` ],
             platform: 'node',
             packages: 'external',
             sourcemap: true,
-            sourceRoot: `https://github.com/remotex-lab/xmap/tree/v${ pkg.version }/`,
-            entryPoints: [ 'src/index.ts' ]
+            external: [ './index.js' ],
+            sourceRoot: `https://github.com/remotex-lab/xBuild/tree/v${ pkg.version }/`,
+            loader: {
+                '.html': 'text'
+            }
+        },
+        lifecycle: {
+            onStart(): void {
+                console.log('starting build...');
+            }
         }
     },
-    {
-        declaration: false,
-        noTypeChecker: true,
-        esbuild: {
-            bundle: true,
-            format: 'cjs',
-            outdir: 'dist/cjs'
+    variants: {
+        bash: {
+            esbuild: {
+                entryPoints: {
+                    bash: 'src/bash.ts'
+                }
+            }
+        },
+        index: {
+            esbuild: {
+                entryPoints: {
+                    index: 'src/index.ts'
+                }
+            }
         }
     }
-];
-
-export default config;
+};
 ```
 
 ## Using the ifdef Plugin
-The `ifdef` plugin in `xBuild` allows to conditionally include or exclude code based on defined variables. Here’s an example:
+
+The `ifdef` in `xBuild` allows to conditionally include or exclude code based on defined variables. Here's an example:
+
 ```ts
-// main.ts
+$$ifdef('DEBUG', () => {
+    console.log('Debug mode is enabled');
+});
 
-console.log("This code always runs");
+$$ifndef('FEATURE_X', () => {
+    console.log('Feature X is not active');
+});
 
-// If the `DEBUG` flag is set in your build config, this block will be included
-// ifdef DEBUG
-console.log("Debug mode is enabled");
-// endif
+const $$logger = $$ifdef('DEBUG', (...args: Array<unknown>) => {
+    console.debug(...args);
+});
 
-// ifdef FEATURE_X
-console.log("Feature X is active");
-// endif
-```
+$$logger('some log that will be in debug mode only');
 
-### Setting Conditions in Configuration
-To enable these blocks during the build, define your conditions in the `xBuild` configuration file:
-```ts
-export default {
-    esbuild: {
-        entryPoints: ['./src/main.ts'],
-        outdir: 'dist',
-        minify: false,
-        format: 'esm',
-        bundle: true,
-    },
-    define: {
-        DEBUG: true,        // Enables the DEBUG section
-        FEATURE_X: false,    // Excludes the FEATURE_X section
-    }
-};
-```
-In this example:
-* When `DEBUG` is set to `true`, the `Debug mode is enabled` message is included.
-* When `FEATURE_X` is `false`, the `console.log("Feature X is active");` line is excluded.
+const result = $$inline(() => {
+    console.log('compile time log');
 
-This approach helps to manage feature toggles and debug code efficiently, making it possible to build different versions of your code based on a configuration.
+    return 'run in compile time and retrun string result';
+});
 
-## Hooks 
-The `HooksInterface` interface provides a structure for lifecycle hooks to customize the build process.
-```ts
-export interface HooksInterface {
-    onEnd: OnEndType;
-    onLoad: OnLoadType;
-    onStart: OnStartType;
-    onResolve: OnResolveType;
-}
+console.log(result);
 ```
 
+### Setting Conditions in Configuration
+
+To enable these blocks during the build, define your conditions in the `xBuild` configuration file:
+
 ```ts
 /**
- * Imports will be remove at compile time
+ * Import will remove at compile time
  */
 
 import type { xBuildConfig } from '@remotex-labs/xbuild';
@@ -218,61 +213,70 @@ import pkg from './package.json' with { type: 'json' };
  * Config build
  */
 
-const config: xBuildConfig = {
-    dev: true,
-    watch: true,
-    declaration: true,
-    buildOnError: false,
-    noTypeChecker: false,
-    esbuild: {
-        entryPoints: ['./src/index.ts'],
-        bundle: true,
-        minify: true,
-        target: 'es2020'
-    },
-    serve: {
-        port: 8080,
-        host: 'localhost',
-        active: true // can be activeate using -s instead 
-    },
-    hooks: {
-        onStart: async (build) => {
-            console.log('Build started');
+export const config: xBuildConfig = {
+    common: {
+        define: {
+            __VERSION: pkg.version,
+        },
+        esbuild: {
+            bundle: true,
+            minify: true,
+            format: 'esm',
+            target: [ `node${ version.slice(1) }` ],
+            platform: 'node',
+            packages: 'external',
+            sourcemap: true,
+            external: [ './index.js' ],
+            sourceRoot: `https://github.com/remotex-lab/xBuild/tree/v${ pkg.version }/`,
+            loader: {
+                '.html': 'text'
+            }
         },
-        onEnd: async (result) => {
-            console.log('Build finished:', result);
+        lifecycle: {
+            onStart(): void {
+                console.log('starting build...');
+            }
         }
     },
-    define: {
-        '__ENV__': 'development',
+    variants: {
+        bash: {
+            define: {
+                DEBUG: true,        // Enables the DEBUG section
+                FEATURE_X: false,    // Excludes the FEATURE_X section
+            },
+            esbuild: {
+                entryPoints: {
+                    bash: 'src/bash.ts'
+                }
+            }
+        },
+        index: {
+            esbuild: {
+                entryPoints: {
+                    index: 'src/index.ts'
+                }
+            }
+        }
     }
 };
-
-export default config;
 ```
 
-## Using the ifdef and macros
-```ts
-// main.ts
+## Hooks
 
-console.log("This code always runs");
+The `LifecycleHooksInterface` interface provides a structure for lifecycle hooks to customize the build process.
 
-// If the `DEBUG` flag is set in your build config, this block will be included
-// ifdef DEBUG
-export function $$logger(...args: Array<unknown>): void {
-    console.log(...args);
+```ts
+export interface LifecycleHooksInterface {
+    onEnd?: OnEndType;
+    onLoad?: OnLoadType;
+    onStart?: OnStartType;
+    onSuccess?: OnEndType;
+    onResolve?: OnResolveType;
 }
-// endif
-
-// ifdef FEATURE_X
-console.log("Feature X is active");
-// endif
-
-
-$$logger('data'); // will be deleted if $$logger does not exist
 ```
 
 ## Links
+
 - [Documentation](https://remotex-labs.github.io/xBuild/)
 - [GitHub Repository](https://github.com/remotex-labs/xBuild)
 - [Issue Tracker](https://github.com/remotex-labs/xBuild/issues)