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.

Browser security prevents any web application from reading or writing to the user’s real file system without explicit permission dialogs. NEX OS takes a different approach entirely: it implements a complete Virtual File System (VFS) that lives entirely in React state, managed by FileSystemProvider and consumed through the useFileSystem() hook. From the perspective of every application running inside NEX OS — File Explorer, Notepad, the Terminal, the NEX Runtime package manager — this in-memory tree behaves identically to a real disk. Files can be created, read, updated, and deleted, folders can be navigated, and recursive deletions correctly clean up all descendants.

​
The VirtualFile Interface

Every item stored in the VFS is represented by a VirtualFile object. The location field acts as the directory path, and the combination of location + name + extension forms the full virtual path. 
interface VirtualFile {
  id: string;        // Unique identifier (used for all mutations)
  name: string;      // Filename without extension
  location: string;  // Parent directory path, e.g. "C:/Users/Default/Documents"
  extension: string; // File extension without the dot, e.g. "txt", "nex", "json"
  content: string;   // File body — plain text, JSON strings, nexPayload metadata
  createdAt: Date;   // Creation timestamp
}
There is no separate “folder” type in the VirtualFile interface. Folders are represented implicitly by the path segments in location. The createFolder method creates a sentinel entry that File Explorer uses to display the directory, but actual content lives in files.

​
FileSystemContextType Methods

useFileSystem() exposes the following API surface. All mutations trigger a React state update, causing subscribed components to re-render with the new file tree.
MethodParametersDescription
createFilelocation, name, extCreates a new VirtualFile at the given path and returns its generated id. Used by Notepad on Save, by NEX Runtime when scaffolding package.json, and by File Explorer’s New File context menu.
updateFileContentid, contentReplaces the content field of the file with the given id. The only mutation that modifies an existing file’s body — used by Notepad, VS Code, and the NEX Runtime installer.
navigatepath: stringUpdates currentPath in context, causing File Explorer to display the contents of the new directory.
openFilefile: VirtualFileReads the file’s extension and content, then calls openWindow from WindowManagerContext with the appropriate application (e.g., .txt → Notepad, .nex → NEX Runtime launcher).
createFoldername: stringCreates a new folder entry at the current path. Subsequent files created inside it reference this path in their location field.
deleteFilepath: stringRemoves the file or folder at the given path. If the target is a folder, all files and subfolders beneath it are deleted recursively — no orphaned entries remain in the files array.
getFileContentpath: stringResolves a full virtual path and returns the file’s content string, or a Buffer equivalent for binary representations. Used by the NEX Runtime to read package.json before installing dependencies.

​
Reactive Properties

PropertyTypeDescription
filesVirtualFile[]The complete flat array of all virtual files. Components filter this array by location to display directory contents.
currentPathstringThe path currently open in File Explorer, updated by navigate().

​
Default Directory Tree

FileSystemProvider initialises with a pre-populated directory tree that mirrors a standard Windows file system layout. This tree is created in React state at provider mount time — no disk reads occur. 
C:/
├── Users/
│   └── Default/
│       ├── Documents/    — default save location for Notepad, WordPad
│       ├── Downloads/    — target for browser-initiated file saves
│       └── Pictures/     — source for the Photos and Image Viewer apps
├── Program Files/
│   └── NEX/             — .nex executables resolved by Win+R and the Terminal
└── Windows/             — system files (read by Windows Defender simulation)
Applications that create user data write into C:/Users/Default/ by default. The NEX Runtime places scaffolded projects under whatever path the Terminal’s current working directory points to.

​
.nex Executables

.nex files are the virtual equivalent of .exe binaries on Windows. They are stored in the VFS as regular VirtualFile entries with extension: 'nex', but their content field carries a JSON metadata block called nexPayload that tells the OS which application to launch and with what initial props. 
{
  "appId": "vscode",
  "label": "VS Code",
  "icon": "Code20Regular",
  "defaultProps": {}
}
When a .nex file is encountered, the system reads this payload and calls openWindow with the resolved app component from the app registry — no network request, no binary execution. Three entry points can trigger a .nex launch:
1

Double-click in File Explorer

FileExplorer.tsx calls openFile(file) from useFileSystem(). The context detects the .nex extension, parses nexPayload from content, and calls openWindow on WindowManagerContext with the correct app id, title, icon, and content component.
2

Win+R Run Dialog

The Run dialog calls resolveNex(input) from NexRuntimeContext. This method accepts both explicit names (notepad.nex) and implicit names (notepad), appending .nex automatically and searching C:/Program Files/NEX/ to find and launch the matching executable.
3

Terminal Command

Typing ./vscode.nex or vscode.nex in Terminal.tsx or Cmd.tsx triggers the same resolveNex path, first checking the terminal’s current working directory, then falling back to the system Program Files/NEX/ path.

​
Using the VFS in an Application — Notepad Example

The following example is the canonical pattern for an app that reads and writes VFS files. The component is completely decoupled from the file system implementation — it receives a fileId prop and uses useFileSystem() to resolve the content. 
import { useFileSystem } from '../../context/FileSystemContext';

export const Notepad = ({ fileId }: { fileId?: string }) => {
  const { files, updateFileContent } = useFileSystem();

  // Resolve the file from the flat files array using its unique ID
  const file = files.find(f => f.id === fileId);

  const handleSave = (text: string) => {
    if (fileId) {
      // Mutates only the content field — location, name, and metadata are unchanged
      updateFileContent(fileId, text);
    }
  };

  return (
    <textarea
      defaultValue={file?.content}
      onBlur={e => handleSave(e.target.value)}
    />
  );
};
Use defaultValue rather than value for text editors inside NEX OS windows to avoid re-rendering the textarea on every keystroke. Call updateFileContent only on blur or on explicit Save — this keeps the VFS state update count minimal and prevents janky re-renders across all subscribed components.

​
Security Model

The VFS is fully sandboxed within the browser tab’s JavaScript heap.
NEX OS has zero access to the user’s real file system. No File System Access API calls are made, no <input type="file"> dialogs are opened implicitly, and no data is sent to any server. All “files” exist only in React state for the duration of the browser session. Closing or refreshing the tab clears the VFS entirely.
This sandboxing is a security feature, not a limitation. It means:
  • Applications cannot read sensitive files from the user’s machine
  • Malicious .nex executables cannot escape the browser sandbox
  • The OS can be safely embedded in any web page or iframe
  • TypeScript’s strict mode catches type mismatches in file paths at compile time, before any runtime errors can occur

Build docs developers (and LLMs) love

Get started for freeTalk to us