{"id":24977,"library":"balm-core","title":"Balm Core (BalmJS)","description":"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.","status":"active","version":"4.33.0","language":"javascript","source_language":"en","source_url":"https://github.com/balmjs/balm","tags":["javascript","balm","balmjs","web","app","front-end","workflow","typescript"],"install":[{"cmd":"npm install balm-core","lang":"bash","label":"npm"},{"cmd":"yarn add balm-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add balm-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core task runner used by BalmJS","package":"gulp","optional":false},{"reason":"Module bundler integrated into the workflow","package":"webpack","optional":false},{"reason":"Provides live reload and dev server","package":"browser-sync","optional":false}],"imports":[{"note":"Default import works for both ESM and CJS, but ESM is preferred for TypeScript projects.","wrong":"const balm = require('balm-core')","symbol":"balm","correct":"import balm from 'balm-core'"},{"note":"Named export for TypeScript type inference. Available since v4.","wrong":"const { Balmer } = require('balm-core')","symbol":"Balmer","correct":"import { Balmer } from 'balm-core'"},{"note":"Type import for configuration types; do not use as value.","wrong":"import { BalmConfig } from 'balm-core'","symbol":"BalmConfig","correct":"import type { BalmConfig } from 'balm-core'"},{"note":"Named functions for programmatic usage. Available since v3.","wrong":"const { init, resolve, go } = require('balm-core')","symbol":"balm API (init, resolve, go)","correct":"import { init, resolve, go } from 'balm-core'"}],"quickstart":{"code":"// Create balm.config.js\nmodule.exports = {\n  // Minimal config: specify styles and scripts entry\n  styles: {\n    extname: 'css',\n    entry: 'src/styles/main.css'\n  },\n  scripts: {\n    entry: 'src/scripts/index.js'\n  }\n}\n\n// Then in your terminal:\n// npx balm (development)\n// npx balm -p (production)\n\n// Programmatic usage (ESM):\nimport { init, go } from 'balm-core';\nconst config = {\n  // ... your config\n};\ninit(config).then(() => go('default')).catch(err => console.error(err));","lang":"typescript","description":"Shows minimal configuration file and programmatic usage of balm-core to start a build."},"warnings":[{"fix":"Update to Node 20.10+ or 22+.","message":"Balm Core v4 requires Node >=20.10.0 or >=22.0.0. Node 18 is no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update your project to use Webpack 5 and PostCSS 8+; check your configuration.","message":"Balm Core v4 drops support for Webpack 4 and PostCSS 7. Use Webpack 5 and PostCSS 8+.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Change to import balm from 'balm-core'.","message":"The 'require' style CommonJS import (const balm = require('balm-core')) is deprecated. Use ESM import instead.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Ensure init(config) is called and resolves before calling go().","message":"When using programmatic API, call init() before go(). Calling go() without init() will throw an error.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Create balm.config.js with your configuration; see docs for defaults.","message":"The balm CLI expects a balm.config.js in the project root; missing file causes silent fallback to defaults.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure your src directory follows the expected structure.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install balm-core globally: npm install -g balm-core","cause":"balm-core is not installed globally.","error":"Error: Cannot find module 'balm-core'"},{"fix":"Use import balm from 'balm-core' (default) or import { init } from 'balm-core' (named).","cause":"Using wrong import (e.g., default import but expecting named export).","error":"TypeError: balm.init is not a function"},{"fix":"Upgrade Node.js to 20.10+ or 22+.","cause":"Node version is lower than required.","error":"Error: The engine 'node' is incompatible with this module. Expected version '^20.10.0 || >=22.0.0'."},{"fix":"Run: npm install -D gulp","cause":"Gulp is not installed as a project dependency.","error":"Error: Cannot find module 'gulp'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}