Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shadownrx/windows/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through everything needed to get NEX OS running on your local machine — from cloning the repository to seeing the animated UEFI boot screen in your browser. The full installation takes under five minutes on a standard internet connection, and no special tooling beyond Node.js and npm is required to start developing.

​
Prerequisites

Before you begin, make sure the following are available in your environment:
  • Node.js 18.0.0 or higher (20.x LTS recommended) — Download
  • npm 9.0.0 or higher (bundled with Node.js 18+)
Verify your versions before proceeding: 
node --version   # Should output v18.x.x or higher
npm --version    # Should output 9.x.x or higher

​
Installation

1

Clone the Repository

Clone the NEX OS repository from GitHub and navigate into the project directory.
git clone https://github.com/shadownrx/windows.git
cd windows
2

Install Dependencies

Install all project dependencies. NEX OS supports npm, yarn, and pnpm — use whichever you prefer.
npm install
This installs all runtime and dev dependencies declared in package.json, including React 19, Vite 8, Framer Motion 12, Three.js, AssemblyScript, and all Fluent UI icon packages.
3

Start the Development Server

Launch the Vite development server with Hot Module Replacement enabled.
npm run dev
The terminal will output:
VITE v8.x.x  ready in xxx ms

➜  Local:   http://localhost:5173/
➜  press h + enter to show help
Open http://localhost:5173 in your browser. You will be greeted by the animated UEFI boot screen — the entry point to the NEX OS lifecycle. From there, the sequence proceeds automatically through POST, Windows Boot, and the Login screen before landing on the desktop.
NEX OS defaults to the Windows 11 desktop mode after login. To switch to the alternative NEX OS desktop, select it from the UEFI boot selector at startup.
4

(Optional) Compile WASM Modules

If you plan to modify the WebAssembly performance layer, compile the AssemblyScript source to WASM before starting the dev server.
npm run build:as
This command runs the AssemblyScript compiler (asc) against assembly/index.ts and outputs the compiled binary to public/process_utils.wasm along with its JavaScript glue file public/process_utils.js, as configured in asconfig.json.
You only need to run build:as if you modify files inside the assembly/ directory. The pre-compiled WASM artifacts are already included in the repository and work out of the box for all built-in features, including the real-time Task Manager.

​
Production Build

When you are ready to deploy or benchmark the production bundle, run the full build pipeline followed by the local preview server. 
npm run build
npm run preview
The build script chains three steps automatically: npm run build:as (AssemblyScript → WASM), tsc -b (TypeScript type check), and vite build (bundle and optimize). Output lands in the dist/ directory.
ArtifactUncompressedGzip
dist/assets/index.js~1,863 KB~499 KB
dist/assets/index.css~27.6 KB~6.4 KB
dist/index.html~1.2 KB~0.6 KB
Enable Brotli compression on your hosting provider for maximum transfer performance. Brotli typically achieves 15–20% better compression than gzip on JavaScript bundles.

​
Available npm Scripts

ScriptDescription
npm run devStart the Vite dev server with instant HMR on localhost:5173
npm run buildFull production pipeline: WASM compile → TypeScript check → Vite bundle
npm run build:asCompile assembly/index.ts → WASM only (skips TypeScript and Vite)
npm run previewServe the dist/ folder locally for production preview
npm run lintRun ESLint across all source files using the project’s flat config
npm run music:serverStart the Nex Music backend server (runs npm run dev inside server/)

​
Troubleshooting

Another process is occupying the default Vite port. Start the dev server on a different port by passing the --port flag:
npm run dev -- --port 3000
Vite will start on http://localhost:3000 instead. You can use any available port number.
This error appears when the pre-compiled WebAssembly artifacts are missing from public/. Recompile them and then rebuild:
npm run build:as
npm run build
After running these commands, restart the dev server with npm run dev. The useWasmEngine hook automatically falls back to a JavaScript implementation if the WASM binary cannot be loaded, so the Task Manager will still function — but with reduced performance.
If you encounter missing module errors or corrupted installs, perform a clean reinstall by removing the node_modules directory and the lock file, then reinstalling from scratch:
rm -rf node_modules package-lock.json
npm install
On Windows (PowerShell), use:
Remove-Item -Recurse -Force node_modules, package-lock.json
npm install
If you are using Node.js 22+ and see peer dependency warnings related to React 19, they are expected and safe to ignore — all packages in NEX OS have been verified compatible with React 19.

Build docs developers (and LLMs) love

Get started for freeTalk to us