nextos-desktop

v1.0.2

Published

3 months ago

Transform your Next.js app into a desktop-like environment with windows, taskbar, and workspace management

Downloads

0High
0Medium
0Low

nextjs desktop window-manager workspace ui react component-library desktop-environment virtual-desktop window-management

@nextos/desktop 🖥️

Transform your Next.js application into a desktop-like environment with windows, taskbar, workspaces, and a beautiful UI.

Features ✨

🪟 Window Management - Draggable, resizable windows with minimize, maximize, and close
📱 Multiple Workspaces - Ubuntu-style virtual desktops (up to 9 workspaces)
🎯 Window Snapping - Drag to edges for split-screen and fullscreen
⌨️ Keyboard Shortcuts - Quick workspace switching (Ctrl+1-9)
💾 State Persistence - Window positions and workspaces saved across sessions
🎨 Customizable - Theme, colors, and layout options
📦 Zero Config - Works out of the box with sensible defaults
🚀 TypeScript - Full type safety

Installation 📦

npm install @nextos/desktop
# or
yarn add @nextos/desktop
# or
pnpm add @nextos/desktop

Peer Dependencies

Make sure you have these installed:

npm install next@14+ react@18+ react-dom@18+

Quick Start 🚀

1. Wrap your app with `DesktopProvider`

In your app/layout.tsx:

import { DesktopProvider } from '@nextos/desktop';
import '@nextos/desktop/styles';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <DesktopProvider>
          {children}
        </DesktopProvider>
      </body>
    </html>
  );
}

2. Register your apps

Create your app components:

// app/components/Calculator.tsx
'use client';

export function Calculator() {
  return (
    <div className="p-8 bg-gray-900 h-full">
      <h1 className="text-white text-2xl">Calculator</h1>
      {/* Your calculator UI */}
    </div>
  );
}

3. Register apps in your page

// app/page.tsx
'use client';

import { useEffect } from 'react';
import { useDesktopStore } from '@nextos/desktop';
import { Calculator } from './components/Calculator';
import { TodoApp } from './components/TodoApp';

export default function Home() {
  const { registerApp } = useDesktopStore();

  useEffect(() => {
    // Register your apps
    registerApp({
      id: 'calculator',
      name: 'Calculator',
      icon: '/icons/calculator.png',
      component: Calculator,
      window: {
        width: 400,
        height: 500,
        minWidth: 300,
        minHeight: 400,
      },
    });

    registerApp({
      id: 'todo',
      name: 'Todo List',
      icon: '/icons/todo.png',
      component: TodoApp,
      window: {
        width: 600,
        height: 700,
      },
    });
  }, [registerApp]);

  return null; // Desktop UI will render automatically
}

Advanced Usage 🔧

Custom Theme

<DesktopProvider
  config={{
    theme: {
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      taskbarColor: 'rgba(0, 0, 0, 0.8)',
    },
    workspaces: 6,
    defaultWindowSize: {
      width: 800,
      height: 600,
    },
  }}
>
  {children}
</DesktopProvider>

Programmatically Open Windows

'use client';

import { useDesktopStore } from '@nextos/desktop';

export function MyComponent() {
  const { openWindow, apps } = useDesktopStore();

  const handleOpen = () => {
    const app = apps['calculator'];
    if (app) {
      openWindow(app);
    }
  };

  return (
    <button onClick={handleOpen}>
      Open Calculator
    </button>
  );
}

Access Window State

'use client';

import { useDesktopStore } from '@nextos/desktop';

export function WindowManager() {
  const { windows, currentWorkspaceId } = useDesktopStore();

  const currentWindows = windows.filter(
    w => w.workspaceId === currentWorkspaceId
  );

  return (
    <div>
      <p>Open windows: {currentWindows.length}</p>
    </div>
  );
}

API Reference 📚

`DesktopProvider`

Main provider component that wraps your app.

Props:

config?: DesktopConfig - Optional configuration
children: ReactNode - Your app content

`useDesktopStore()`

Hook to access and control the desktop state.

Returns:

apps: Record<string, DesktopApp> - Registered apps
registerApp(app: DesktopApp): void - Register a new app
unregisterApp(appId: string): void - Remove an app
openWindow(app: DesktopApp): void - Open app window
closeWindow(windowId: string): void - Close window
minimizeWindow(windowId: string): void - Minimize window
maximizeWindow(windowId: string): void - Maximize window
windows: WindowState[] - All open windows
workspaces: Workspace[] - All workspaces
currentWorkspaceId: number - Active workspace
switchWorkspace(id: number): void - Change workspace

`DesktopApp` Type

interface DesktopApp {
  id: string;
  name: string;
  icon?: string;
  component: React.ComponentType<any>;
  window?: {
    width?: number;
    height?: number;
    minWidth?: number;
    minHeight?: number;
    resizable?: boolean;
  };
  desktopIcon?: {
    x?: number;
    y?: number;
  };
}

Keyboard Shortcuts ⌨️

Ctrl + 1-9 - Switch to workspace 1-9
Ctrl + Alt + ←/→ - Navigate between workspaces
Drag window to top edge - Fullscreen
Drag window to left edge - Split left
Drag window to right edge - Split right

Examples 📖

Check the examples/ folder for complete working examples:

Basic Setup - Minimal configuration
Custom Theme - Themed desktop
Multiple Apps - Calculator, Todo, Notes apps
Advanced - Custom components and hooks

Browser Support 🌐

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)

Contributing 🤝

Contributions are welcome! Please read our Contributing Guide.

License 📄

Support 💬

📧 Email: [email protected]
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Credits 🙏

Built with:

Made with ❤️ for the Next.js community