Web UI Development
Front End Technologies
The NetBox UI is built on languages and frameworks:
Styling & HTML Elements
The majority of the NetBox UI is made up of stock Bootstrap components, with some styling modifications and custom components added on an as-needed basis. Bootstrap uses Sass, and NetBox extends Bootstrap's core Sass files for theming and customization.
NetBox is jQuery-free
Following the Bootstrap team's deprecation of jQuery in Bootstrap 5, NetBox also no longer uses jQuery in front-end code.
NetBox generally follows the following guidelines for front-end code:
- Bootstrap utility classes may be used to solve one-off issues or to implement singular components, as long as the class list does not exceed 4-5 classes. If an element needs more than 5 utility classes, a custom SCSS class should be added that contains the required style properties.
- Custom classes must be commented, explaining the general purpose of the class and where it is used.
- Reuse SCSS variables whenever possible. CSS values should (almost) never be hard-coded.
- All TypeScript functions must have, at a minimum, a basic JSDoc description of what the function is for and where it is used. If possible, document all function arguments via
@paramJSDoc block tags.
- NetBox aligns with Bootstrap's supported Browsers and Devices list.
To contribute to the NetBox UI, you'll need to review the main Getting Started guide in order to set up your base environment.
Once you have a working NetBox development environment, you'll need to install a few more tools to work with the NetBox UI:
After Node and Yarn are installed on your system, you'll need to install all the NetBox UI dependencies:
$ cd netbox/project-static $ yarn
Check Your Working Directory
You need to be in the
netbox/project-static directory to run the below
yarn bundle is a wrapper around the following subcommands, any of which can be run individually:
||Bundle TypeScript and Sass (SCSS) source files.|
||Bundle Sass (SCSS) source files only.|
||Bundle TypeScript source files only.|
All output files will be written to
netbox/project-static/dist, where Django will pick them up when
manage.py collectstatic is run.
Remember to re-run
If you're running the development web server —
manage.py runserver — you'll need to run
manage.py collectstatic to see your changes.
Linting, Formatting & Type Checking
Before committing any changes to TypeScript files, and periodically throughout the development process, you should run
yarn validate to catch formatting, code quality, or type errors.
If you're using an IDE, it is strongly recommended to install ESLint, TypeScript, and Prettier integrations, if available. Most of them will automatically check and/or correct issues in the code as you develop, which can significantly increase your productivity as a contributor.
yarn validate is a wrapper around the following subcommands, any of which can be run individually:
||Run all validation.|
||Validate TypeScript code via ESLint only.|
||Validate TypeScript code compilation only.|
||Validate code formatting Sass/SCSS only.|
||Validate code formatting TypeScript only.|
You can also run the following commands to automatically fix formatting issues:
||Format TypeScript and Sass (SCSS) source files.|
||Format Sass (SCSS) source files only.|
||Format TypeScript source files only.|