Negligent Parachute Maintainers

    buildozer

    0.5.1 • Public • Published

    Buildozer logo

    npm version Actions status Dependencies

    Buildozer is a simple build system to compile Sass, minify images or SVGs and compile javascript. It's a wrapper built around Gulp which frees you from configuring and maintaining packages.

    Installation

    # With npm
    npm i buildozer
    
    # Or install with yarn
    yarn add buildozer

    Commands

    Both the build and watch commands output the files to the same directory.

    Build

    buildozer build

    The build task can be used for production environments. The build command:

    • Copy files if needed
    • Lint source code if configured
    • Compiles Sass to CSS
    • Use autoprefixer for vendor prefixing
    • Minifies the CSS output
    • Minifies images and svg
    • Transpiles ES6 to ES5
    • Minifies javascript
    • Concatenate .js files in the concat folder

    Watch

    buildozer watch

    The watch task will watch the source files for changes and rebuild a task when a change is detected:

    • Copy files if needed
    • Clean all dest folders
    • Lint source code if configured
    • Compiles Sass to CSS
    • Use autoprefixer for vendor prefixing
    • Add scss sourcemaps
    • Minifies images and svg
    • Transpiles ES6 to ES5
    • Concatenate .js files in the concat folder
    • Run browsersync if configured

    Separate tasks

    buildozer clean is run to clear all dest folders. buildozer copy, buildozer css, buildozer js, buildozer js-concat , buildozer svg-sprite and buildozer img can be used to run the subtasks of buildozer build.

    Order of script execution

    • Set environment: Set the environment to production for the build task. This way, the assets are minified on production.
    • Clean: Remove all files from destination folders.
    • Copy: Copy all files defined in copy array.
    • CSS: Compile CSS.
    • JS: Compile javascript files and concat if configured.
    • Image: Minify images & generate svg sprite if configured.

    Default folder structure

    Buildozer knows what files it needs to compile because it uses a predefined folder structure:

    project/
    ├── scss/
    │   ├── main.scss
    │   └── …
    ├── js/
    │   ├── concat
    │   │   └── …
    │   ├── main.js
    │   └── …
    └── img/
        ├── loading.gif
        ├── image.jpg
        ├── logo.svg
        └── …
    

    … which compiles to:

    project/
    └── dest/
        ├── css/
        │   ├── main.css
        │   └── …
        ├── js/
        │   ├── all.js
        │   ├── main.js
        │   └── …
        └── img/
            ├── loading.gif
            ├── image.jpg
            ├── logo.svg
            └── …
    

    Customizing the folder structure

    Buildozer uses a .buildozerrc configuration file which uses the yaml syntax and defines which paths are used. By default, this file looks like this:

    src_base_path: ./
    dest_base_path: ./
    scss:
      - src: scss/**/*.css
        dest: dest/css
      - src: scss/**/*.scss
        dest: dest/css
      - src: scss/**/*.sass
        dest: dest/css
    img:
      - src: img/**/*.png
        dest: dest/img
      - src: img/**/*.jpg
        dest: dest/img
      - src: img/**/*.jpeg
        dest: dest/img
      - src: img/**/*.gif
        dest: dest/img
      - src: img/**/*.svg
        dest: dest/img
    js:
      - src: js/**/*.js
        dest: dest/js
    js-concat:
      - src: js/concat/*.js
        name: all.js
        dest: dest/js
    svg-sprite:
      - src: img/sprite/*.svg
        name: sprite.svg
        dest: dest/img/sprite
    browsersync:
      server: null # Static sites
      proxy: null # Dynamic sites
      reload: null # Glob to watch for reload

    If you want to configure your own paths, you can run buildozer config to generate a .buildozerrc in your folder and change the paths however you like. All src paths are prefixed src_base_path, the dest paths are prefixed with dest_base_path.

    Concat

    If you want to combine multiple .js files into one file, you can drop the files in js/concat and Buildozer will generate a single all.js file. The files themselves are also compiled to the destination folder for whenever they need to be used stand alone.

    SVG sprites

    You can combine multiple <svg>s you use into one sprite. Just drop the files in the img/sprite folder and the sprite will be generated as dest/img/sprite/sprite.svg.

    Browser sync

    Browsersync can be enabled for as well serving static sites (server option) or dynamic sites (proxy option). With the reload option, you can define a glob to watch for. Browsersync will then reload the page if one of the matching files is changed. For example, use **/*.html to watch for changes in HTML files.

    Browserslist

    Browserslist is a single configuration for all tools that need to know what browsers you support. Just create a Browserslist compatible configuration and define the browsers you want to support.

    For example you could place a .browserslistrc in your document root.

    # Browsers that we support
    
    last 1 version
    > 1%
    IE 10 # sorry
    

    Tools like Autoprefixer will compile according to the Browserslist configuration you defined.

    RFS

    The RFS PostCSS plugin is included by default which allows you to use the rfs() function in your Sass.

    PostCSS plugins

    Loading extra PostCSS plugins can be done by overriding the default config. This can be done in multiple ways documented on the postcss-load-config repository.

    For example you could place a postcss.config.js in your document root.

    module.exports = () => {
      return {
            plugins: {
              'rfs': {},
              'autoprefixer': {},
              'cssnano': {}
            }
        }
    };

    Copy

    Additionally files can be copied before if needed. Useful whenever you need some files from the node_modules folder which you don't have available on production.

    copy:
      - src: node_modules/jquery/dist/jquery.min.js
        dest: js/vendor
      - src: node_modules/bootstrap/dist/js/bootstrap.min.js
        dest: js/vendor

    Config search

    In your .buildozerrc configuration file, it is possible to enable config search. With this feature you can drop .buildozerrc in sub folders within your project which will be detected by Buildozer. This way you can bundle your CSS, JS or images in a folder they belong to without the need of a seperate setup. Make sure to exclude folders in which you do not want to look for configuration files with the ignore option.

    config_search:
      enabled: true
      ignore:
        - '**/vendor/**'
        - '**/node_modules/**'

    The following structure represents a simplified Drupal folder structure in which .buildozerrc files are used to create a modular setup:

    drupal_project/
    ├── modules/
    |   └── custom/
    |       ├── custom_module_1/
    |       |   ├── js/
    |       |   │   └── module-js.js
    |       |   └── .buildozerrc
    |       └── custom_module_2/
    |           ├── img/
    |           │   └── module-img.svg
    |           └── .buildozerrc
    ├── themes/
    |   └── custom/
    |     └── custom_theme/
    |         ├── scss/
    |         │   └── main.scss
    |         ├── js/
    |         │   └── main.js
    |         └── .buildozerrc
    └── .buildozerrc # In this file `config_search` is enabled
    

    Linting

    As soon as Buildozer detects a linting configuration file, linting will be enabled. Buildozer takes a pretty aggressive approach when the linting rules are not followed: if the linting fails, no CSS or JS will be build.

    ESLint

    ESLint is JavaScript linter which can easily be enabled by dropping your cosmiconfig configuration in the folder which you want to be linted.

    project/
    ├── scss/
    │   └── …
    ├── js/
    │   └── …
    ├── img/
    │   └── …
    ├── .buildozer
    ├── .eslintignore # Optional ignore file
    └── .eslintrc
    

    Stylelint

    Apart from just javascript linting, Buildozer also provides CSS linting with stylelint. Just drop the configuration file to get started:

    project/
    ├── scss/
    │   └── …
    ├── js/
    │   └── …
    ├── img/
    │   └── …
    ├── .buildozer
    └── .stylelint
    

    Options

    verbose

    Use buildozer build --verbose (or watch) to output more details. With this option all files which are copied are logged. You'll also see some more information about the images which are compressed.

    fix

    Use buildozer watch --fix (or build) to fix linting issues that can be fixed automatically.

    env

    The environment variable env determines whether files need to be minified. Minification will be enabled whenever this variable is set to production. If anything else is set, minification will be disabled. By default, the build command uses production, unless the variable is overridden by something else like buildozer build --env=development.

    Gulp options (watch)

    All gulp options defined on the watch page can be passed via cli, eg. buildozer watch --usePolling=true

    Contributing to Buildozer

    Looking to contribute something to Buildozer? Just have a look at the open issues to check if there's anything interesting. You can also just have a look at the source code to see if there's anything which can be improved.

    Getting started

    These are the steps you'll need to take to create a new PR.

    • Make sure you have the latest node and npm version installed
    • Fork the buildozer repository
    • Clone your fork
    • Make a new branch describing what you want to fix/add
    • Develop your excellent code
      • Make sure to add tests if needed
      • Some tests are meant to fail, these tests are checked in test/fail-tests.js
    • Run npm test to check every test passes
    • Commit, push & create a PR
    • Describe what is changed in your PR description

    Thanks

    Thanks Intracto for development maintenance & icons8 for providing a logo.

    Keywords

    none

    Install

    npm i buildozer

    DownloadsWeekly Downloads

    265

    Version

    0.5.1

    License

    MIT

    Unpacked Size

    39.8 kB

    Total Files

    16

    Last publish

    Collaborators

    • avatar
    • avatar