# Getting Started

⚡️ The simplest structure for webapp (Full structure)

project
├─┬ src
│ ├─┬ scripts
│ │ └── index.js
│ ├─┬ styles
│ │ └── main.css
│ └── index.html
├── .browserslistrc
├── babel.config.js
├── gulpfile.js
└── package.json

And you can also download the example and try it.

# Webapp directory

# 1. A HTML template

/path/to/project/src/index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Hello BalmJS</title>
    <link rel="stylesheet" href="%PUBLIC_URL%/styles/main.css" />
  </head>

  <body>
    <div id="app"><!-- Your Template --></div>
    <script src="%PUBLIC_URL%/scripts/main.js"></script>
  </body>
</html>

# 2. A CSS entry file

/path/to/project/src/styles/main.css

* {
  margin: 0;
  padding: 0;
}

# 3. A JS entry file

/path/to/project/src/scripts/index.js

document.getElementById('app').innerHTML = '<h1>Hello BalmJS</h1>';

Compiling index.js to main.js by Balm.

Please refer to the Project settings - 3. Configure balm below.

# Project settings

# 1. Autoprefixer uses Browserslist

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

> 0.5%
last 2 versions
Firefox ESR
not dead

# 2. Configure babel

enable ES2015 features by using Babel

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

module.exports = {
  presets: ['@babel/preset-env'],
  plugins: ['@babel/plugin-transform-runtime']
};

Balm has the latest @babel/preset-env and @babel/plugin-transform-runtime built-in.

# 3. Configure balm by gulpfile.js

  • A simple gulpfile.js example (/path/to/project/gulpfile.js)
// 1. Import balm
const balm = require('balm');

// 2. Config balm
balm.config = {
  server: {
    open: true,
    proxyConfig: {
      context: '/api',
      options: {
        target: 'http://your.project.dev', // Target host
        changeOrigin: true // Needed for virtual hosted sites
      }
    }
  },
  roots: {
    source: 'src', // Source code root (Create a directory named 'src' in project)
    target: 'dist' // The production build
  },
  paths: {
    source: {
      css: 'styles', //   CSS dir = ./src/styles
      js: 'scripts', //    JS dir = ./src/scripts
      img: 'images', // Image dir = ./src/images
      font: 'fonts' //   Font dir = ./src/fonts
    }
  },
  styles: {
    extname: 'css', // Main style extension: css,scss,less
    sprites: ['icons'] // Icons path: ['./src/images/icons']
  },
  scripts: {
    entry: {
      // HTML: <script src="%PUBLIC_URL%/scripts/vendor/mylib.js"></script>
      // mylib: [
      //   'your-project-library-1',
      //   'your-project-library-2',
      //   'your-project-plugin-A',
      //   'your-project-plugin-B'
      // ],
      // Entry
      main: './src/scripts/index.js'
    }
  },
  assets: {
    root: '/path/to/your_remote_project', // Remote project root path
    mainDir: 'public', // '/path/to/your_remote_project/public'
    subDir: '', // `/path/to/your_remote_project/public/${subDir}`
    cache: false
  }
};

// 3. Run balm
balm.go(mix => {
  if (balm.config.env.isProd) {
    // Publish assets(styles,scripts,images,fonts,media)
    // from local `${roots.target}/{css,js,img,font,media}`
    // to remote `${assets.root}/${assets.mainDir}/${assets.subDir}`
    mix.publish();

    // Publish html templates
    // from local `${roots.target}/index.html`
    // to remote `${assets.root}/views/new-filename.blade.php`
    mix.publish('index.html', 'views', {
      basename: 'new-filename',
      suffix: '.blade',
      extname: '.php'
    });
  }
});

Tips: If you refer to balm's standard project structure, you can develop your project with almost zero configuration.

🌰 For example:

const balm = require('balm');

balm.config = {
  server: {
    // For debugging apis in development
  },
  assets: {
    // For building in production
  }
};

balm.go();
Last Updated: 8 days ago