@nex-os/sdk

Official SDK for building community apps inside NEX OS — a browser-based desktop environment with windows, taskbar, Start menu, and a full app runtime.

Register an app once. It shows up in Search, Start, the taskbar, and Run (Ctrl+Alt+R). No shell patches required.

Install

npm install @nex-os/sdk

Peer dependency: react >= 18

Full guide (Spanish): docs/SDK.md · Issues: github.com/shadownrx/windows

How it works

defineApp / defineHtmlApp
          │
          ▼
   runtime registry  ──►  AppRegistry · Taskbar · Start · Search · Run

| Path | API | Best for | | --- | --- | --- | | React | defineApp | Full apps with host hooks (useOpenApp, settings, FS…) | | HTML / CSS / JS | defineHtmlApp | Static web apps, prototypes, no React required |

Quick start (React)

import { defineApp } from '@nex-os/sdk';

type Props = { mode?: string };

function MyApp({ mode = 'demo' }: Props) {
  return (
    <div
      style={{
        height: '100%',
        padding: 24,
        color: '#e8f0ff',
        background: 'linear-gradient(160deg, #0b1220, #0f1a14)',
        fontFamily: 'Segoe UI, system-ui, sans-serif',
      }}
    >
      <h1 style={{ margin: 0 }}>Hello NEX</h1>
      <p style={{ opacity: 0.7 }}>Mode: {mode}</p>
    </div>
  );
}

export default defineApp<Props>({
  id: 'my-app',
  appId: 'my-app',
  title: 'My App',
  icon: <span style={{ fontSize: 18 }}>⚡</span>,
  component: MyApp,
  description: 'My first NEX community app',
  author: '@you',
  version: '0.1.0',
  pinToTaskbar: true,
  category: 'tools',
  permissions: ['windows', 'settings'],
  defaultProps: { mode: 'demo' },
  aliases: ['myapp', 'mia'],
});

In the NEX OS monorepo

1. Save as src/community-apps/MyApp.tsx
2. Add import './MyApp' to src/community-apps/index.ts
3. npm run dev → Search My App or Run → mia

HTML apps (no React UI)

import { defineHtmlApp } from '@nex-os/sdk';

export default defineHtmlApp({
  id: 'my-html',
  appId: 'my-html',
  title: 'My HTML App',
  icon: <span style={{ fontFamily: 'monospace', fontWeight: 700 }}>{'</>'}</span>,
  aliases: ['html'],
  category: 'dev',
  source: {
    html: `<main><h1>Hello NEX</h1><button id="b">Click</button></main>`,
    css: `body{margin:0;padding:24px;background:#0b1220;color:#e8f0ff;font-family:system-ui}
          button{margin-top:12px;padding:8px 14px;border-radius:8px;cursor:pointer}`,
    js: `document.getElementById('b').onclick=()=>alert('NEX OS')`,
  },
});

Runs in a sandboxed iframe (allow-scripts by default). Host hooks (useOpenApp, etc.) are React-only for now.

In-OS demo: HTML Playground · Run → html

Manifest

| Field | Type | Required | Description | | --- | --- | :---: | --- | | id | string | ✓ | Window id (unique per virtual desktop) | | appId | string | ✓ | Key resolved by the host AppRegistry | | title | string | ✓ | Title bar / Start / taskbar label | | icon | ReactNode | ✓ | Fluent icon, SVG, or emoji wrapper | | component | ComponentType | ✓* | Root UI (height: 100%) — React path | | source | HtmlAppSource | ✓* | { html, css?, js?, sandbox? } — HTML path | | aliases | string[] | | Run / Search aliases (case-insensitive) | | description | string | | Catalog blurb | | author | string | | Creator handle | | version | string | | Informational semver | | defaultProps | object | | Merged when the window opens | | pinToTaskbar | boolean | | Show on dock even when closed | | category | union | | tools · media · games · dev · social · other | | permissions | NexAppPermission[] | | Documented contract (windows, settings, fs, …) |

* Use component with defineApp, or source with defineHtmlApp.

API reference

import {
  defineApp,
  defineHtmlApp,
  registerApp,
  unregisterApp,
  getRegisteredApp,
  resolveRegisteredApp,
  listRegisteredApps,
  getAppsByCategory,
  getCommunityLauncherItems,
  subscribeRegistry,
  createOpenApp,
} from '@nex-os/sdk';

| Export | Purpose | | --- | --- | | defineApp(manifest) | Register a typed React app | | defineHtmlApp(manifest) | Register an HTML/CSS/JS app | | registerApp / unregisterApp | Manual registry control | | getRegisteredApp(appId) | Direct lookup | | resolveRegisteredApp(query) | Resolve by id, alias, or title | | listRegisteredApps() | Unique manifests | | getAppsByCategory(cat) | Filter by category | | getCommunityLauncherItems() | Dock / Search items | | createOpenApp(openWindow) | Pure helper to open from the registry | | subscribeRegistry(fn) | Listen for register/unregister |

Types: NexAppManifest, NexAppProps, NexAppPermission, NexAppCategory, NexLauncherItem, NexTrack, HtmlAppSource, HtmlAppManifest

Host hooks (inside NEX OS)

Community apps run under the OS provider tree. From src/community-apps/:

import { useOpenApp, useSettings, useWindowManager } from '../sdk/host';

const openApp = useOpenApp();
const { addNotification, accentColor } = useSettings();

openApp('hello');
openApp('my-app', { mode: 'pro' });
addNotification('My App', 'Ready');

Also available: useFileSystem, useDesktop, useUI, useMusicPlayer.

These hooks are part of the host, not this npm package. The SDK owns registration + types; the shell owns window chrome and system services.

Shortcuts (browser-safe)

NEX avoids Win+* / Alt+Tab (captured by the host OS). Use:

| Action | Shortcut | | --- | --- | | Run | Ctrl+Alt+R | | Clipboard history | Ctrl+Alt+V | | Screen snip | Ctrl+Alt+S |

Versioning

| Version | Highlights | | --- | --- | | 0.2.2 | Professional docs · clearer HTML + React paths | | 0.2.1 | defineHtmlApp — HTML/CSS/JS community apps | | 0.2.0 | defineApp<TProps>, resolveRegisteredApp, createOpenApp, permissions, categories | | 0.1.x | Initial registry + launcher integration |

Links

• Repository: shadownrx/windows
• Package source: packages/nex-os-sdk
• Architecture: docs/ARCHITECTURE.md
• Runtime (FS / shell / git): docs/RUNTIME.md
• In-OS demos: Hello NEX · SDK Docs · HTML Playground

License

MIT © NEX OS