Nebula build

Build a nebula visualization bundle

Usage

nebula build

Example

Build the bundle with a nebula configuration JSON file in a new path

nebula build --config config/my-nebula-config.js

Rebuild the bundle when files in /src folder change on the disk

nebula build --watch

Build the bundle without a source map file - .js.map file

nebula build --sourcemap false

Compiled bundles are not minified in the development mode

nebula build --mode development

Build a UMD module and an extra ES Module into directory /core

nebula build --core

Enable to bundle the TypeScript files

nebula build --typescript

Options

Details

Module bundler

Nebula build uses rollup.js - a module bundler to compile pieces of code into files.

Nebula build supports two formats, UMD (Universal Module Definition) and ESM (ES2015 Modules). The UMD code is used by nebula sense. to generate Qlik Sense readable files as an Extension.

Note: In your root package.json file, the main field must be set, such as 'your-dir/your-file.js'. As nebula build reads main to know where to output the UMD code.

And the peerDependencies are treated by Nebula build as external dependencies that are not bundled alongside your local JavaScript to reduce the size of the bundle.

Configuration file

Nebula build cli recognizes the 'nebula.config.js' file in your root as a config file automatically, you can set the path and filename of your preference with nebula build --config your-path/your-name.js

In the config file, build properties:

• replacementStrings
• watch
• sourcemap
• mode
• core
• typescript

replacementStrings is set to replace strings in files while bundling and the rest has the same meaning and purpose as the options preceding.

The following code in a config file demonstrates an example to set the nebula build configuration.

const path = require('path');
const targetPkg = require(path.resolve(process.cwd(), 'package.json'));
const replacementStrings = {
  'process.env.PACKAGE_VERSION': JSON.stringify(targetPkg.version),
};
const mode = process.env.NODE_ENV === 'production' ? 'production' : 'development';
const sourcemap = mode !== 'production';

module.exports = {
  build: {
    replacementStrings,
    watch: true,
    sourcemap,
    mode,
    core: 'core',
    typescript: true,
  },
};

Watch

watch function rebuilds your bundle when it detects that the files in /src folder have been changed on the disk.

Source map

A source map is a file that maps from the bundled source file to the original source files, enabling the browser to reconstruct and present the original source code in the debugger. So if there is an error in a file in the /dist directory, the source map can tell you the original source file location.

Basically, the source map is helpful for debugging and should be removed for production.

Mode

Environment settings can be specified by the --mode parameter.

Production mode minifies all compiled modules, while development mode keeps them as is. Minified output is the default, except when watch is on.

Core build

You can build an ESM bundle by adding --core parameter.

First add a package.json file in the /core directory. In the package.json file, a module field which specifies the output file from the build is required:

"module": "core/esm/index.js",

Then run the following command:

nebula build --core core

The bundled code is exported into /core directory.

To specify another directory, move the package.json file into that directory, change the string in the module field accordingly:

"module": "minimal/target/index.js",

and run the following command:

nebula build --core minimal/target

The index.js file is exported into /minimal/target directory.

Note: The package.json file can have a different list of peerDependencies compared to the root package.json file changing what dependencies are included in the ES module code.

Typescript

With this option you can enable TypeScript bundling of your code. Add a tsconfig.json file to configure TypeScript to your own preferences.

nebula build --typescript