Balm Core (BalmJS)

4.33.0 verified Fri May 01 auth: no javascript

Balm Core is the compiler core for BalmJS, an opinionated front-end workflow tool based on Gulp and webpack. It provides a structure-driven approach to building web apps with minimal configuration, handling tasks like PostCSS/Sass/Less compilation, CSS Autoprefixing, CSS sprites generation, ES2015+ transpilation via Babel, image optimization, and built-in BrowserSync dev server. Current stable version is 4.33.0, requiring Node >=20.10.0 or >=22.0.0. It ships with TypeScript declarations. Unlike generic task runners or bundlers, BalmJS enforces a specific project structure and convention over configuration, aiming for simplicity and consistency across projects. Release cadence is irregular. Supports both ESM and CommonJS modules.

Common errors

error Error: Cannot find module 'balm-core' ↓

cause balm-core is not installed globally.

fix

Install balm-core globally: npm install -g balm-core

error TypeError: balm.init is not a function ↓

cause Using wrong import (e.g., default import but expecting named export).

fix

Use import balm from 'balm-core' (default) or import { init } from 'balm-core' (named).

error Error: The engine 'node' is incompatible with this module. Expected version '^20.10.0 || >=22.0.0'. ↓

cause Node version is lower than required.

fix

Upgrade Node.js to 20.10+ or 22+.

error Error: Cannot find module 'gulp' ↓

cause Gulp is not installed as a project dependency.

fix

Run: npm install -D gulp

Warnings

breaking Balm Core v4 requires Node >=20.10.0 or >=22.0.0. Node 18 is no longer supported. ↓

fix Update to Node 20.10+ or 22+.

breaking Balm Core v4 drops support for Webpack 4 and PostCSS 7. Use Webpack 5 and PostCSS 8+. ↓

fix Update your project to use Webpack 5 and PostCSS 8+; check your configuration.

deprecated The 'require' style CommonJS import (const balm = require('balm-core')) is deprecated. Use ESM import instead. ↓

fix Change to import balm from 'balm-core'.

gotcha When using programmatic API, call init() before go(). Calling go() without init() will throw an error. ↓

fix Ensure init(config) is called and resolves before calling go().

gotcha The balm CLI expects a balm.config.js in the project root; missing file causes silent fallback to defaults. ↓

fix Create balm.config.js with your configuration; see docs for defaults.

gotcha Source directory must contain required files: index.html, styles entry (e.g., main.css), and scripts entry (e.g., index.js). Missing files may cause build failures. ↓

fix Ensure your src directory follows the expected structure.

Install

npm install balm-core

yarn add balm-core

pnpm add balm-core

Imports

balm
wrong
```
const balm = require('balm-core')
```
correct
```
import balm from 'balm-core'
```
Default import works for both ESM and CJS, but ESM is preferred for TypeScript projects.

Balmer

wrong

const { Balmer } = require('balm-core')

correct

import { Balmer } from 'balm-core'

Named export for TypeScript type inference. Available since v4.

BalmConfig

wrong

import { BalmConfig } from 'balm-core'

correct

import type { BalmConfig } from 'balm-core'

Type import for configuration types; do not use as value.

balm API (init, resolve, go)

wrong

const { init, resolve, go } = require('balm-core')

correct

import { init, resolve, go } from 'balm-core'

Named functions for programmatic usage. Available since v3.

Quickstart

Shows minimal configuration file and programmatic usage of balm-core to start a build.

// Create balm.config.js
module.exports = {
  // Minimal config: specify styles and scripts entry
  styles: {
    extname: 'css',
    entry: 'src/styles/main.css'
  },
  scripts: {
    entry: 'src/scripts/index.js'
  }
}

// Then in your terminal:
// npx balm (development)
// npx balm -p (production)

// Programmatic usage (ESM):
import { init, go } from 'balm-core';
const config = {
  // ... your config
};
init(config).then(() => go('default')).catch(err => console.error(err));