balm-core

library4.33.0jsnpmunverified

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.

devops web-framework

npm install balm-core

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BALM-CORE

balm-core

devopsjavascriptv4.33.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

balm

✓ import balm from 'balm-core'

✗ const balm = require('balm-core')

Default import works for both ESM and CJS, but ESM is preferred for TypeScript projects.

Balmer

✓ import { Balmer } from 'balm-core'

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

Named export for TypeScript type inference. Available since v4.

BalmConfig

✓ import type { BalmConfig } from 'balm-core'

✗ import { BalmConfig } from 'balm-core'

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

balm API (init, resolve, go)

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

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

Named functions for programmatic usage. Available since v3.

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));

balm --version

Debug

Known issues

breakingBalm 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+.

affects: >=4.0.0

breakingBalm 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.

affects: >=4.0.0

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

fix

Change to import balm from 'balm-core'.

affects: >=4.0.0

gotchaWhen 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().

affects: >=3.0.0

gotchaThe 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.

affects: >=3.0.0

gotchaSource 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.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'balm-core'

balm-core is not installed globally.

fix

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

TypeError: balm.init is not a function

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: The engine 'node' is incompatible with this module. Expected version '^20.10.0 || >=22.0.0'.

Node version is lower than required.

fix

Upgrade Node.js to 20.10+ or 22+.

Error: Cannot find module 'gulp'

Gulp is not installed as a project dependency.

fix

Run: npm install -D gulp

Upgrade

Version history

4.33.0latest on npm

Audit

Dependencies

gulprequiredCore task runner used by BalmJS

webpackrequiredModule bundler integrated into the workflow

browser-syncrequiredProvides live reload and dev server

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/balmjs/balm ↗

packagehttps://www.npmjs.com/package/balm-core ↗

homepagehttps://balmjs.com ↗