Installation

Prerequisites

ArchitectUI requires Node.js LTS (v18 or higher) and npm (bundled with Node). Verify your versions before installing:

node --version    # should print v18.x.x or higher
                npm --version     # should print v9.x.x or higher

If Node is missing or out of date, download the LTS installer from nodejs.org/en/download. We recommend using nvm (Linux/macOS) or nvm-windows if you maintain multiple Node versions.

Install Dependencies

Unzip the template archive into a working directory, then install:

cd architectui-html-pro-webpack
                npm install

First-time installation downloads roughly 775 packages and takes 30–60 seconds on a fast connection. The result is a node_modules/ directory of ~600 MB. Webpack, Babel, Sass, all UI libraries, and their transitive dependencies are now in place.

Audit Output

At the end of npm install you should see 0 vulnerabilities. If npm warns about deprecated transitive dependencies (e.g. rimraf@2, glob@7, inflight@1), those come from upstream packages and are safe to ignore — they cannot be remediated without waiting for the upstream maintainers to update.

Start the Dev Server

ArchitectUI ships with webpack-dev-server configured for Hot Module Replacement. The default port is 8080:

npm start

After a few seconds you should see:

webpack 5.106.2 compiled successfully in 4033 ms

Open http://localhost:8080. The Analytics dashboard renders as index.html. SCSS, JavaScript, and Handlebars template changes hot-reload without a manual refresh.

Alternative Ports

If port 8080 is busy or you want to run two instances side-by-side:

For ad-hoc ports, set the PORT env var directly: PORT=9999 npm start.

Without the Page Loader

ArchitectUI ships with an optional FOUC-prevention loader (off by default in the current build). To run the dev server with the loader explicitly disabled regardless of loader.config.js:

npm run start:no-loader

See Page Loader for the full configuration guide.

Production Build

When you're ready to ship, run a production build:

npm run build

The build emits 86 static HTML pages (74 dashboard + 12 docs) plus hashed asset bundles into architectui-html-pro/:

architectui-html-pro/
                ├── index.html                          # 86 HTML files in total
                ├── ...
                └── assets/
                    ├── scripts/main.[hash].js
                    ├── scripts/vendors.[hash].js       # All node_modules in one bundle
                    ├── scripts/[feature].[hash].js     # Per-feature JS bundles
                    ├── styles/main.[hash].css
                    ├── styles/vendors.[hash].css
                    ├── images/                         # Copied verbatim
                    └── fonts/                          # Copied verbatim

Production builds use splitChunks with cache groups for vendors and styles, generating cacheable bundles with content-hashed filenames. The build cleans the output directory each time, so no stale files accumulate.

Without the Page Loader

npm run build:no-loader

Same as npm run build but with the loader stripped from the output HTML.

Verifying Your Build

ArchitectUI does not ship with a built-in production server. To preview the production output locally, use any static-file server. Two quick options:

Python (built-in)

cd architectui-html-pro
                python3 -m http.server 8000

Node serve

npx serve architectui-html-pro -l 8000

Open http://localhost:8000 and click through a representative sample of pages — especially anything dynamic (charts, tables, calendars, forms) to catch differences between dev and prod builds.

Troubleshooting

EADDRINUSE: address already in use :::8080

Another process holds port 8080. Either kill it (lsof -ti:8080 | xargs kill -9 on macOS/Linux) or pick a different port with npm run start:3010.

Module not found: Can't resolve '...'

Usually means a page is registered in src/pages.js but its template file is missing, or vice versa. Re-check both. After adding new pages or removing old ones, restart the dev server — pages.js is read once at startup, not on HMR.

node-sass / sass-loader compile errors

ArchitectUI uses Dart Sass (the sass package), not the deprecated node-sass. If your error mentions Python or C++ compilers, you probably have a stale node-sass install somewhere — delete node_modules/ and package-lock.json and reinstall.

Dart Sass deprecation warnings flooding the terminal

Bootstrap's bundled SCSS still uses legacy @import and /-as-division syntax. The build suppresses these in the user-facing output via warnRuleAsWarning: false in webpack.config.js. They are expected and harmless.

HMR not picking up new pages

New entries in src/pages.js require a dev server restart — HMR only tracks files that were already part of the bundle graph at server startup.