Esbuild Flex

https://github.com/zoliszabo/esbuild-flex
Admin
Esbuild Flex is a thin wrapper around esbuild that manages multiple build configurations in a single...
Tokens:7,629
Snippets:45
Trust Score:6.1
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Create esbuild-flex.config.js with multiple groups

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Example configuration file with global defaults and four groups using different entryPoints formats: string array, {in, out} array, Record, and entryNames.

```javascript
/** @type {import('esbuild-flex').FlexConfig} */
module.exports = {
    // Global defaults (apply to all groups)
    target: 'es2018',
    sourcemap: false,
    minify: true,

    groups: [
        // Group 1: Simple string array with globs
        {
            name: 'Main scripts',
            entryPoints: [
                'src/app.js',
                'src/components/*.js',
            ],
            outdir: 'dist/js',
        },

        // Group 2: Using {in, out} for explicit names
        {
            name: 'Pages',
            entryPoints: [
                { in: 'src/home.ts', out: 'home-page' },
                { in: 'src/about.ts', out: 'about-page' },
            ],
            outdir: 'dist/js',
            bundle: true,  // Override global setting
        },

        // Group 3: Record format
        {
            name: 'Admin',
            entryPoints: {
                'admin-app': 'src/admin/app.js',
                'admin-dashboard': 'src/admin/dashboard.js',
            },
            outdir: 'dist/admin',
        },

        // Group 4: Using esbuild's entryNames
        {
            name: 'Utilities',
            entryPoints: ['src/utils/**/*.js'],
            outdir: 'dist/utils',
            outbase: 'src/utils',
            entryNames: '[dir]/[name].min',
        },
    ]
};
```

--------------------------------

### Install esbuild-flex with npm

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Install esbuild-flex as a dev dependency using npm.

```bash
npm install --save-dev esbuild-flex
```

--------------------------------

### Watch Mode Programmatically

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Starts esbuild-flex in watch mode using the build() function with the watch option set to true. Requires a config file at the specified path.

```javascript
const { build } = require('esbuild-flex');

async function startWatching() {
    await build({
        configFile: './esbuild-flex.config.js',
        watch: true
    });
    console.log('Watching for changes...');
}

startWatching();
```

--------------------------------

### Using Callbacks

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Demonstrates using callbacks to track build progress: onBuildStart, onBuildEnd, and onAllBuildsComplete. Note that onAllBuildsComplete is only called in non-watch mode.

```javascript
const { build } = require('esbuild-flex');

await build({
    configFile: './esbuild-flex.config.js',

    // Called before each group starts building
    onBuildStart: (group) => {
        console.log(`Building: ${group.name}`);
    },

    // Called after each group finishes
    onBuildEnd: (group, result) => {
        if (result.errors.length > 0) {
            console.error(`Failed: ${group.name}`);
        } else {
            console.log(`Success: ${group.name}`);
        }
    },

    // Called after all groups finish (non-watch mode only)
    onAllBuildsComplete: (results) => {
        console.log(`Built ${results.length} groups`);
    }
});
```

--------------------------------

### build()

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

The build() function is the main entry point for the esbuild-flex programmatic API. It accepts an options object to configure and run builds, supporting watch mode, tag filtering, dynamic configuration, and callbacks for build lifecycle events.

```APIDOC
## build()

### Description
The `build()` function is the main entry point for the esbuild-flex programmatic API. It accepts an options object to configure and run builds, supporting watch mode, tag filtering, dynamic configuration, and callbacks for build lifecycle events.

### Method
Function call

### Endpoint
`build(options)`

### Parameters
#### Options Object
- **config** (FlexConfig) - Optional - Inline configuration object (alternative to `configFile`)
- **configFile** (string) - Optional - Path to config file (default: `'esbuild-flex.config.js'`)
- **watch** (boolean) - Optional - Enable watch mode (default: `false`)
- **tags** (string[]) - Optional - Filter groups by tags
- **onBuildStart** ((group) => void) - Optional - Callback invoked before each group starts building
- **onBuildEnd** ((group, result) => void) - Optional - Callback invoked after each group finishes building
- **onAllBuildsComplete** ((results) => void) - Optional - Callback invoked after all groups finish (non-watch mode only)

**Note:** You must provide either `config` or `configFile`, but not both.

### Request Example
```javascript
const { build } = require('esbuild-flex');

await build({
    configFile: './esbuild-flex.config.js',
    watch: true
});
```

### Response
#### Success Response
- **result** (object) - The build result object, containing information about the build groups and any errors.

#### Response Example
```javascript
// The build() function returns a promise that resolves when the build completes.
// In watch mode, it resolves immediately after starting the watcher.
```

### Error Handling
- If both `config` and `configFile` are provided, an error is thrown.
- If neither `config` nor `configFile` is provided, an error is thrown.
- Build errors are reported through the `onBuildEnd` callback's `result.errors` array.
```

--------------------------------

### Run esbuild-flex CLI commands

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Commands for one-time build, watch mode, custom config, verbose, silent, and combined options.

```bash
# One-time build
npx esbuild-flex

# Watch mode
npx esbuild-flex --watch

# Custom config file
npx esbuild-flex --config=custom.config.js

# Watch with custom config
npx esbuild-flex --watch --config=custom.config.js

# Verbose mode (shows debug logs)
npx esbuild-flex --verbose

# Silent mode (only errors and warnings)
npx esbuild-flex --silent

# Combine options
npx esbuild-flex --watch --verbose --config=custom.config.js
```

--------------------------------

### Basic programmatic usage with config file

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Use the build function from esbuild-flex with a config file, handling success and error cases.

```javascript
const { build } = require('esbuild-flex');

// Using a config file
async function runBuild() {
    try {
        await build({
            configFile: './esbuild-flex.config.js'
        });
        console.log('Build completed successfully!');
    } catch (error) {
        console.error('Build failed:', error);
        process.exit(1);
    }
}

runBuild();
```

--------------------------------

### Group Configuration with Tags

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Define groups with entryPoints, optional name, tags, and esbuild options. Tags allow selective building with the --tags flag.

```javascript
module.exports = {
    groups: [
        {
            name: 'JavaScript',
            tags: ['dev', 'js'],
            entryPoints: ['src/**/*.js'],
            outdir: 'dist/js',
        },
        {
            name: 'Stylesheets',
            tags: ['dev', 'css'],
            entryPoints: ['src/**/*.css'],
            outdir: 'dist/css',
        },
        {
            name: 'Production bundle',
            tags: ['production'],
            entryPoints: ['src/app.js'],
            outdir: 'dist',
            bundle: true,
            minify: true,
        }
    ]
};
```

--------------------------------

### Dynamic Configuration

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Generates build configuration dynamically based on the environment variable. Adjusts target, sourcemap, minify, and output directory accordingly.

```javascript
const { build } = require('esbuild-flex');

async function buildForEnvironment(env) {
    const isDev = env === 'development';
    
    await build({
        config: {
            target: isDev ? 'es2020' : 'es2015',
            sourcemap: isDev,
            minify: !isDev,
            groups: [
                {
                    name: `${env} build`,
                    entryPoints: ['src/app.js'],
                    outdir: `dist/${env}`,
                    bundle: true,
                    define: {
                        'process.env.NODE_ENV': JSON.stringify(env)
                    }
                }
            ]
        }
    });
}

// Usage
buildForEnvironment(process.env.NODE_ENV || 'development');
```

--------------------------------

### With plugins (e.g., SCSS)

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Shows how to use plugins with esbuild-flex. Imports the sassPlugin from esbuild-sass-plugin and adds it to a group named 'Styles' that processes SCSS files from src/styles and outputs to dist/css.

```javascript
const { sassPlugin } = require('esbuild-sass-plugin');

module.exports = {
    groups: [
        {
            name: 'Styles',
            entryPoints: ['src/styles/*.scss'],
            outdir: 'dist/css',
            plugins: [sassPlugin()],
        }
    ]
};
```

--------------------------------

### Integration with Custom Build Scripts

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Shows a custom build pipeline with pre-build, build, and post-build steps using esbuild-flex and Node.js fs module. Includes error handling and process exit on failure.

```javascript
const { build } = require('esbuild-flex');
const fs = require('fs').promises;

async function customBuildPipeline() {
    // Pre-build tasks
    console.log('Running pre-build tasks...');
    await fs.mkdir('dist', { recursive: true });
    
    // Run esbuild-flex
    console.log('Building with esbuild-flex...');
    await build({
        configFile: './esbuild-flex.config.js'
    });
    
    // Post-build tasks
    console.log('Running post-build tasks...');
    await fs.copyFile('public/index.html', 'dist/index.html');
    
    console.log('Build pipeline completed!');
}

customBuildPipeline().catch(error => {
    console.error('Build pipeline failed:', error);
    process.exit(1);
});
```

--------------------------------

### Add esbuild-flex to package.json scripts

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Define build and dev scripts in package.json to run esbuild-flex.

```json
{
  "scripts": {
    "build": "esbuild-flex",
    "dev": "esbuild-flex --watch"
  }
}
```

--------------------------------

### Inline configuration programmatic usage

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Pass configuration directly to the build function without a config file.

```javascript
const { build } = require('esbuild-flex');

async function runBuild() {
    await build({
        config: {
            target: 'es2020',
            sourcemap: true,
            groups: [
                {
                    name: 'App',
                    entryPoints: ['src/app.js'],
                    outdir: 'dist',
                    bundle: true,
                }
            ]
        }
    });
}

runBuild();
```

--------------------------------

### Multiple targets

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Defines two groups targeting different ECMAScript versions: 'Modern browsers' targets es2020 and 'Legacy browsers' targets es2015. Both use the same entry point src/app.js but output to separate directories.

```javascript
module.exports = {
    groups: [
        {
            name: 'Modern browsers',
            entryPoints: ['src/app.js'],
            outdir: 'dist/modern',
            target: 'es2020',
        },
        {
            name: 'Legacy browsers',
            entryPoints: ['src/app.js'],
            outdir: 'dist/legacy',
            target: 'es2015',
        }
    ]
};
```

--------------------------------

### Bundled app with source maps

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Configures esbuild-flex to bundle an application and generate source maps. Sets bundle and sourcemap to true, with a group named 'App bundle' that takes src/index.js and outputs to dist.

```javascript
module.exports = {
    bundle: true,
    sourcemap: true,
    groups: [
        {
            name: 'App bundle',
            entryPoints: ['src/index.js'],
            outdir: 'dist',
        }
    ]
};
```

--------------------------------

### Root Level Options Configuration

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Set global esbuild options at the root level. Any esbuild option can be used as a default, and groups can override them.

```javascript
module.exports = {
    target: 'es2020',
    sourcemap: true,
    minify: false,
    bundle: false,
    // ... any esbuild option

    groups: [ /* ... */ ]
};
```

--------------------------------

### Selective Building with --tags Flag

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Build only groups matching specified tags. Use --tags with comma-separated tags to match any of them. Groups without tags are only built when no --tags filter is specified.

```bash
# Build only JavaScript groups
npx esbuild-flex --tags=js

# Build only CSS groups
npx esbuild-flex --tags=css

# Build groups tagged with 'dev' (both JS and CSS)
npx esbuild-flex --tags=dev

# Build multiple tags (groups matching ANY of these tags)
npx esbuild-flex --tags=js,css

# Watch only production builds
npx esbuild-flex --watch --tags=production
```

--------------------------------

### Non-bundled scripts with minification

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Configures esbuild-flex to minify scripts without bundling. Sets minify to true and defines a group named 'Legacy scripts' that processes all JavaScript files in public/js and outputs to public/dist/js.

```javascript
module.exports = {
    minify: true,
    groups: [
        {
            name: 'Legacy scripts',
            entryPoints: ['public/js/*.js'],
            outdir: 'public/dist/js',
        }
    ]
};
```

--------------------------------

### Filtering by Tags Programmatically

Source: https://github.com/zoliszabo/esbuild-flex/blob/main/README.md

Builds only groups with the 'production' tag using the tags option. Useful for conditional builds based on tags.

```javascript
const { build } = require('esbuild-flex');

async function buildProduction() {
    await build({
        configFile: './esbuild-flex.config.js',
        tags: ['production']
    });
}

buildProduction();
```
Tokens:
Raw