@remotex-labs/xbuild is a versatile TypeScript toolchain build system
Install @remotex-labs/xbuild globally using npm:
npm install -g @remotex-labs/xbuildOr using Yarn:
yarn global add @remotex-labs/xbuildRun the xBuild -h CLI tool with various options to build your typeScript projects.
Command-Line Options
______ _ _ _
| ___ \ (_) | | |
__ _| |_/ /_ _ _| | __| |
\ \/ / ___ \ | | | | |/ _` |
> <| |_/ / |_| | | | (_| |
/_/\_\____/ \__,_|_|_|\__,_|
Version: <xBuild version>
index.js [file]
A versatile JavaScript and TypeScript toolchain build system.
Positionals:
entryPoints The file entryPoints to build [string]
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]
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:
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:
/**
* Import will remove at compile time
*/
import type { xBuildConfig } from '@remotex-labs/xbuild';
/**
* Imports
*/
import { version } from 'process';
import pkg from './package.json' with { type: 'json' };
/**
* Config build
*/
const config: Array<xBuildConfig> = [
{
declaration: true,
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' ]
}
},
{
declaration: false,
noTypeChecker: true,
esbuild: {
bundle: true,
format: 'cjs',
outdir: 'dist/cjs'
}
}
];
export default config;The ifdef plugin in xBuild allows to conditionally include or exclude code based on defined variables. Here’s an example:
// main.ts
console.log("This code always runs");
// If the `DEBUG` flag is set in your build config, this block will be included
// ifdef DEBUG
console.log("Debug mode is enabled");
// endif
// ifdef FEATURE_X
console.log("Feature X is active");
// endifTo enable these blocks during the build, define your conditions in the xBuild configuration file:
export default {
esbuild: {
entryPoints: ['./src/main.ts'],
outdir: 'dist',
minify: false,
format: 'esm',
bundle: true,
},
ifdef: {
DEBUG: true, // Enables the DEBUG section
FEATURE_X: false, // Excludes the FEATURE_X section
}
};In this example:
- When
DEBUGis set totrue, theDebug mode is enabledmessage is included. - When
FEATURE_Xisfalse, theconsole.log("Feature X is active");line is excluded.
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.
The hooks interface provides a structure for lifecycle hooks to customize the build process.
export interface hooks {
onEnd: OnEndType;
onLoad: OnLoadType;
onStart: OnStartType;
onResolve: OnResolveType;
}/**
* Imports will be remove at compile time
*/
import type { xBuildConfig } from '@remotex-labs/xbuild';
/**
* Imports
*/
import { version } from 'process';
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');
},
onEnd: async (result) => {
console.log('Build finished:', result);
}
},
define: {
'__ENV__': 'development',
}
};
export default config;// main.ts
console.log("This code always runs");
// 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);
}
// endif
// ifdef FEATURE_X
console.log("Feature X is active");
// endif
$$logger('data'); // will be deleted if $$logger does not exist