Tutorial: Custom build

Custom build


Edit this page

The build process is using Webpack, Babel and bunch of NPM tasks defined in package.json. During this process, the source files located in the src/* directory are transformed into output files:

  • ./dist/handsontable.js
  • ./dist/handsontable.css
  • ./dist/handsontable.full.js
  • ./dist/handsontable.full.css (more info about dist packages here)
  • ./dist/handsontable.full.min.js
  • ./dist/handsontable.full.min.css

It is advised that you never modify the above-mentioned files but rather make changes in the src/ directory and then run a proper build. This is especially important if you want to contribute your changes back to Handsontable using a pull request.

NPM tasks

Currently, the following tasks are available for building Handsontable:

  • npm run test - runs several tasks in this order:
    • npm run lint - check if changes applied into source code are valid with our code style (mostly we follow Airbnb JavaScript code style).
    • npm run test:unit - runs test suite in node environment. It uses Jest as a test runner.
    • npm run test:walkontable - runs a single build followed by Jasmine test suite and executes in PhantomJS.
    • npm run test:e2e - runs a single build followed by Jasmine test suite and by using generated bundle /dist/handsontable.js executes it in PhantomJS.
    • npm run test:production - runs a single build followed by Jasmine test suite and by using generated minified bundle /dist/handsontable.full.min.js executes it in PhantomJS.
  • npm run build - runs a single build but without code quality checking. It internally executes this tasks:
    • npm run build:commonjs - transpiles files into CommonJS format. These files are published into NPM repository later.
    • npm run build:es - transpiles files into import/export format. These files are published into NPM repository later.
    • npm run build:umd - creates bundles (dist/handsontable.js, dist/handsontable.css, dist/handsontable.full.js and dist/handsontable.full.css) which are compatible with UMD (Universal Module Definition).
    • npm run build:umd.min - creates minified bundles (dist/handsontable.min.js, dist/handsontable.min.css, dist/handsontable.min.full.js and dist/handsontable.min.full.css) which are compatible with UMD (Universal Module Definition).
  • npm run watch - watches for changes in source directory and runs a build when a change is observed. For faster rebuild when a change is observed watcher triggers task which builds files without minify.

Running your first build

To run your own build, follow the below steps:

  1. Install Node.js (available for Windows, Mac and Linux). This will also install NPM (Node Package Manager) that handles all the dependencies. Handsontable for building and testing requires Node.js >=5.10.* and npm >=3.
  2. Clone the Handsontable repository on your local disk and go to the directory where you cloned it.
  3. Run npm install to download all the dependencies defined in package.json. The dependencies will be downloaded into a new directory node_modules, that is ignored by Git.
  4. Run npm run build to make your first build!

Creating a custom package

This process lets you build a custom package containing only the core engine and selected plugins. It's super useful when you need only a fraction of the spreadsheet's overall functionality or when you have already built a custom plugin and want to incorporate it into the base code. For this purpose we prepared a tool called hot-builder. To install hot-builder globally, run:

npm install hot-builder -g

Then to build Handsontable run:

hot-builder build --output-dir hot-dist

Select all necessary plugins in your terminal and press Enter. If it works correctly, you should see something like this:

Creating a custom package

And after selecting modules you should see something like this:

Creating a custom package

For further details, check out the project page.