netbox/netbox/project-static

NetBox UI Development

Introduction

The following tools and languages are used during the build process:

Languages

Sass

Sass is similar to CSS, but has variables, functions, utilities, mixins, and other nice syntax additions. With Sass, we can import Bootstrap's Sass files, override or extend variables, and add classes of our own using Bootstrap's variables (as well as other CSS libraries used).

TypeScript

TypeScript is a strict static-typed superset of JavaScript. In development, it's an extremely effective tool for accurately describing and checking the code, which leads to significantly fewer bugs, a better development experience, and more predictable/readable code.

Tools

esbuild

esbuild is a bundling tool that takes given input files of most front-end languages (Sass and TypeScript, in our case), follows each of their dependencies (via import statements), and bundles them into a single minified file.

For JavaScript, every .ts file in netbox/project-static/src is:

1. Transpiled from TypeScript to JavaScript
2. Minified
3. Combined into a single output file at netbox/project-static/dist/netbox.js (this includes any dependant libraries imported in a file)

Likewise, with Sass, every .scss file in netbox/project-static/styles is:

1. Transpiled from Sass to CSS
2. Minified
3. Combined into a single output file at netbox/project-static/dist/netbox.css (this includes any dependant libraries imported in file)

For pre v4 releases, this process will be run in development, and the files in netbox/project-static/dist checked into change control. This is because running Parcel (and installing dependencies via NPM/Yarn, as described below) requires other system dependencies like NodeJS and Yarn, which aren't part of the current v2 dependency list.

Yarn

Yarn is a package manager (think pip in the Python world) for JavaScript packages on the NPM registry (think PyPI in the Python world). Technically, one could simply use NPM's own npm tool as well, however, yarn is widely used because it tends to be significantly faster than npm (and has other cool features, which we aren't using in NetBox).

Installation

NodeJS

If you don't already have it, install NodeJS (the LTS release should be fine).

Yarn

Next, install Yarn:

npm install -g yarn

NetBox Dependencies

From netbox/project-static, run the command yarn — this will install all production and development dependencies to netbox/project-static/node_modules.

Creating dist files

After any changes to TypeScript or Sass files, you'll need to recompile/bundle the dist files.

To bundle only CSS files, run:

# netbox/project-static
yarn bundle:styles

To bundle only JS files, run:

# netbox/project-static
yarn bundle:scripts

Or, to bundle both, run:

# netbox/project-static
yarn bundle

Note: if you're running the development web server — manage.py runserver — you'll need to run manage.py collectstatic to see your changes.