Skip to content


Repository files navigation


NPM version License Coverage Percentage


An universal Front-End workflow for webapps

balm@3(v3) supports for node@10.13.0+, postcss@7, webpack@4


BalmJS prescribes best practices and tools to help you stay productive.

  • Naturally: Make web development simple, natural and pleasant.
  • Structure-Based: One configuration file can manage webapp projects with at least 90% use cases.
  • Learn Once, Run Any Webapps: Any front-end technology stack will be developed and built in the same way.


  • Based on gulp + webpack for webapp projects
  • Automagically compile PostCSS/Sass/Less
  • CSS Autoprefixing
  • Automagically generate CSS Image Sprites
  • enable ES2015+ features using Babel
  • Awesome images optimization
  • Built-in preview server with BrowserSync
  • Custom publish assets to remote (Front-end to Back-end) project
  • ZIP/FTP/PWA supported
  • Easily define and extend your own tasks


๐Ÿš€ We recommend using Balm CLI to scaffold out a front-end web app.

โ”œโ”€โ”€ .tmp         // Scaffolds out a temporary directory for development
โ”œโ”€โ”€ dist         // Scaffolds out the production build
โ”œโ”€โ”ฌ src          // Source code in here (Create a directory in project)
โ”‚ โ”œโ”€โ”€ fonts
โ”‚ โ”œโ”€โ”€ images
โ”‚ โ”œโ”€โ”€ media
โ”‚ โ”œโ”€โ”ฌ scripts
โ”‚ โ”‚ โ””โ”€โ”€ index.js // Required. A entry file for JS.
โ”‚ โ”œโ”€โ”ฌ styles
โ”‚ โ”‚ โ””โ”€โ”€ main.css // Required. A entry file for CSS.
โ”‚ โ””โ”€โ”€ index.html // Required. A entry file for HTML.
โ”œโ”€โ”€ .dotfile     // (e.g. .gitignore, .browserslistrc, etc...)
โ”œโ”€โ”€ babel.config.js
โ”œโ”€โ”€ balm.config.js // Required. A configuration file for Balm.
โ”œโ”€โ”€ package.json   // Required.
โ””โ”€โ”€ ...


0. Requirements

You need to set up your development environment before you can do anything.

Install Node.jsยฎ and npm if they are not already on your machine.

Verify that you are running at least node 18.12.0 by running node -v in a terminal/console window. Older versions maybe produce errors, but newer versions are fine.

You develop apps in the context of an Balm workspace.

To create a new workspace and initial starter app:

mkdir -p my-project/src/{styles,scripts}
echo "Hello World" > my-project/src/index.html

cd my-project
npm init -y

1. Installing balm

yarn global add balm-core
yarn add -D balm


npm install -g balm-core
npm install -D balm

We currently recommend using Yarn instead of npm.

2. Configuration

In your project directory, create a file named balm.config.js in your project root with these contents:

module.exports = {
  // Your project config

๐Ÿ“ƒ Refer to configuration docs to learn more about config balm.

3. Usage

Edit package.json in your project directory:

  "scripts": {
    "dev": "balm",
    "prod": "balm -p"

Run the command in your project directory:

# For development
npm run dev

# For production
npm run prod



To download example and try it, visit


Project Status Description
balm-core NPM version ๐Ÿƒ BalmJS compiler core (required for balm 3.0+)
balm NPM version ๐Ÿƒ BalmJS runtime core
balm-cli NPM version โ™ ๏ธ BalmJS scaffolding tool
balm-gui N/A โ™ฃ๏ธ GUI for BalmJS
balm-ui-lite NPM version โ™ฅ๏ธ Material Design Lite + Vue
balm-ui NPM version โ™ฆ๏ธ Next Generation Material UI for Vue.js
balm-scroll NPM version ๐Ÿ“œ Smooth scrolling for Vue.js
balm-ui-pro NPM version More configuration definition, less code implementation for Vue.js
balm-git-flow NPM version The best practices for front-end git flow


We'd love for you to contribute and make BalmJS even better than it is today! Please make sure to read the Contributing Guide before making a pull request. You can submit any ideas as pull requests or as GitHub issues.



ยฉ 2016-present, Elf-mousE