diff --git a/docs/development/release-checklist.md b/docs/development/release-checklist.md index 2af640546fc..48f72aa9f8d 100644 --- a/docs/development/release-checklist.md +++ b/docs/development/release-checklist.md @@ -59,7 +59,7 @@ Notify the [`netbox-docker`](https://github.com/netbox-community/netbox-docker) * Increases in minimum versions for service dependencies (PostgreSQL, Redis, etc.) * Any changes to the reference installation -### Update Requirements +### Update Python Dependencies Before each release, update each of NetBox's Python dependencies to its most recent stable version. These are defined in `requirements.txt`, which is updated from `base_requirements.txt` using `pip`. To do this: @@ -70,6 +70,10 @@ Before each release, update each of NetBox's Python dependencies to its most rec In cases where upgrading a dependency to its most recent release is breaking, it should be constrained to its current minor version in `base_requirements.txt` with an explanatory comment and revisited for the next major NetBox release (see the [Address Constrained Dependencies](#address-constrained-dependencies) section above). +### Update UI Dependencies + +Check whether any UI dependencies (JavaScript packages, fonts, etc.) need to be updated by running `yarn outdated` from within the `project-static/` directory. [Upgrade these dependencies](http://0.0.0.0:9000/development/web-ui/#updating-dependencies) as necessary, then run `yarn bundle` to generate the necessary files for distribution. + ### Rebuild the Device Type Definition Schema Run the following command to update the device type definition validation schema: diff --git a/docs/development/web-ui.md b/docs/development/web-ui.md index 8afbd96c10c..b3b94bd06e4 100644 --- a/docs/development/web-ui.md +++ b/docs/development/web-ui.md @@ -1,25 +1,37 @@ # Web UI Development -## Front End Technologies - -The NetBox UI is built on languages and frameworks: +## Code Structure -### Styling & HTML Elements +Most static resources for the NetBox UI are housed within the `netbox/project-static/` directory. -#### [Bootstrap](https://getbootstrap.com/) 5 +| Path | Description | +|-----------|----------------------------------------------------| +| `dist/` | Destination path for installed dependencies | +| `docs/` | Local build path for documentation | +| `img/` | Image files | +| `js/` | Miscellaneous JavaScript resources served directly | +| `src/` | TypeScript resources (to be compiled into JS) | +| `styles/` | Sass resources (to be compiled into CSS) | -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](https://sass-lang.com/), and NetBox extends Bootstrap's core Sass files for theming and customization. +## Front End Technologies -### Client-side Scripting +Front end scripting is written in [TypeScript](https://www.typescriptlang.org/), which is a strongly-typed extension to JavaScript. TypeScript is "transpiled" into JavaScript resources which are served to and executed by the client web browser. -#### [TypeScript](https://www.typescriptlang.org/) +All UI styling is written in [Sass](https://sass-lang.com/), which is an extension to browser-native [Cascading Stylesheets (CSS)](https://developer.mozilla.org/en-US/docs/Web/CSS). Similar to how TypeScript content is transpiled to JavaScript, Sass resources (`.scss` files) are compiled to CSS. -All client-side scripting is transpiled from TypeScript to JavaScript and served by Django. In development, TypeScript is 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. +## Dependencies -As part of the [bundling](#bundling) process, Bootstrap's JavaScript plugins are imported and bundled alongside NetBox's front-end code. +The following software is employed by the NetBox user interface. -!!! danger "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. +* [Bootstrap 5](https://getbootstrap.com/) - A popular CSS & JS framework +* [clipboard.js](https://clipboardjs.com/) - A lightweight package for enabling copy-to-clipboard functionality +* [flatpickr](https://flatpickr.js.org/) - A lightweight date & time selection widget +* [gridstack.js](https://gridstackjs.com/) - Enables interactive grid layouts (for the dashboard) +* [HTMX](https://htmx.org/) - Enables dynamic web interfaces through the use of HTML element attributes +* [Material Design Icons](https://pictogrammers.com/library/mdi/) - An extensive open source collection of graphical icons, delivered as a web font +* [query-string](https://www.npmjs.com/package/query-string) - Assists with parsing URL query strings +* [Tabler](https://tabler.io/) - A web application UI toolkit & theme based on Bootstrap 5 +* [Tom Select](https://tom-select.js.org/) - Provides dynamic selection form fields ## Guidance @@ -54,6 +66,41 @@ $ yarn !!! warning "Check Your Working Directory" You need to be in the `netbox/project-static` directory to run the below `yarn` commands. +### Updating Dependencies + +Run `yarn outdated` to identify outdated dependencies. + +``` +$ yarn outdated +yarn outdated v1.22.19 +info Color legend : + "" : Major Update backward-incompatible updates + "" : Minor Update backward-compatible features + "" : Patch Update backward-compatible bug fixes +Package Current Wanted Latest Workspace Package Type URL +bootstrap 5.3.1 5.3.1 5.3.3 netbox dependencies https://getbootstrap.com/ +``` + +Run `yarn upgrade --latest` to automatically upgrade these packages to their most recent versions. + +``` +$ yarn upgrade bootstrap --latest +yarn upgrade v1.22.19 +[1/4] Resolving packages... +[2/4] Fetching packages... +[3/4] Linking dependencies... +[4/4] Rebuilding all packages... +success Saved lockfile. +success Saved 1 new dependency. +info Direct dependencies +└─ bootstrap@5.3.3 +info All dependencies +└─ bootstrap@5.3.3 +Done in 0.95s. +``` + +`package.json` will be updated to reflect the new package versions automatically. + ### Bundling In order for the TypeScript and Sass (SCSS) source files to be usable by a browser, they must first be transpiled (TypeScript → JavaScript, Sass → CSS), bundled, and minified. After making changes to TypeScript or Sass source files, run `yarn bundle`.