πŸ“¦ zOS App Template

A template for creating zOS applications

Use this template Docs

Quick Start

1. Create Your App

Click "Use this template" above, or:

gh repo create my-app --template zos-apps/template --public --clone
cd my-app

2. Configure Your App

Edit package.json:

{
  "name": "@zos-apps/my-app",
  "version": "1.0.0",
  "description": "My awesome app",
  "zos": {
    "id": "com.yourname.myapp",
    "name": "My App",
    "icon": "πŸš€",
    "category": "utilities",
    "permissions": [],
    "shortcut": "Cmd+M"
  }
}

3. Build Your App

Edit src/index.tsx:

import React from 'react';
import type { AppProps } from './types';

const MyApp: React.FC<AppProps> = ({ className }) => {
  return (
    <div className={`h-full bg-gray-900 text-white ${className}`}>
      <h1>Hello, zOS!</h1>
    </div>
  );
};

export default MyApp;

4. Deploy

Push to GitHub and the docs will auto-deploy:

git add .
git commit -m "feat: my awesome app"
git push

App Structure

my-app/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ index.tsx      # Main app component
β”‚   └── types.ts       # Type definitions
β”œβ”€β”€ docs/
β”‚   └── index.html     # Documentation page
β”œβ”€β”€ .github/
β”‚   └── workflows/
β”‚       └── docs.yml   # Auto-deploy docs
β”œβ”€β”€ package.json       # App manifest & config
└── README.md

Configuration

package.json zos field

Property Type Description
id string Unique app ID (e.g., com.yourname.myapp)
name string Display name
icon string App icon (emoji or URL)
category string productivity, utilities, entertainment, developer, system
permissions string[] Required permissions
shortcut string Keyboard shortcut (e.g., Cmd+M)
installable boolean Can be installed via App Store
menu object Menu bar configuration
contextMenu array Right-click menu items

Permissions

Permission Description
filesystem Read/write files
shell Execute commands
storage Local storage access
network HTTP requests
system System settings

Context Menu Actions

{
  "contextMenu": [
    {"label": "Open", "action": "open"},
    {"label": "Open in New Window", "action": "openNew"},
    {"type": "separator"},
    {"label": "Get Info", "action": "getInfo"},
    {"label": "Show in Finder", "action": "showInFinder"}
  ]
}

AppProps Interface

interface AppProps {
  className?: string;       // CSS class for styling
  config?: AppConfig;       // App configuration
  onClose?: () => void;     // Called when app closes
  onFocus?: () => void;     // Called when app gains focus
}

Examples

Simple App

const SimpleApp: React.FC<AppProps> = ({ className }) => (
  <div className={className}>Hello World</div>
);

With Config

interface MyConfig {
  theme: 'light' | 'dark';
}

const ThemedApp: React.FC<AppProps & { config?: MyConfig }> = ({
  className,
  config,
}) => (
  <div className={`${className} ${config?.theme === 'dark' ? 'bg-black' : 'bg-white'}`}>
    Themed App
  </div>
);

With State

const StatefulApp: React.FC<AppProps> = ({ className }) => {
  const [count, setCount] = useState(0);

  return (
    <div className={className}>
      <p>Count: {count}</p>
      <button onClick={() => setCount(c => c + 1)}>+</button>
    </div>
  );
};

Publishing

  1. Tag a release:

    git tag v1.0.0
    git push origin v1.0.0
    
  2. Users can install via:

    npm install github:zos-apps/my-app
    
  3. Or via the zOS App Store!

License

MIT Β© Hanzo AI

S
Description
Template for creating zOS applications
Readme
34 KiB
Languages
TypeScript 100%