@remotex-labs/xbuild
v1.3.6
Published
A versatile JavaScript and TypeScript toolchain build system
Downloads
869
Maintainers
Readme
@remotex-labs/xbuild
@remotex-labs/xbuild
is a versatile TypeScript toolchain build system
Installation
Install @remotex-labs/xbuild
globally using npm:
npm install -g @remotex-labs/xbuild
Or using Yarn:
yarn global add @remotex-labs/xbuild
Usage
Run 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]
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:
Example Configuration
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;
Using the ifdef Plugin
The ifdef
plugin in xBuild
helps 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");
// endif
Setting Conditions in Configuration
To 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
DEBUG
is set totrue
, theDebug mode is enabled
message is included. - When
FEATURE_X
isfalse
, theconsole.log("Feature X is active");
line is excluded.
This approach helps manage feature toggles and debug code efficiently, making it possible to build different versions of your code based on configuration.
Hooks
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;
}
/**
* 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: 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 insted
},
hooks: {
onStart: async (build) => {
console.log('Build started');
},
onEnd: async (result) => {
console.log('Build finished:', result);
}
},
define: {
'__ENV__': 'development',
}
};
export default config;