An all-in-one macOS plugin featuring customizable widgets to enhance your desktop experience.

✨ Features

• 🎯 Custom Widgets - Beautiful, customizable widgets for your macOS desktop
• ⚡ Lightning Fast - Built with Vite for optimal performance
• 🎨 Modern UI - Styled with Tailwind CSS and shadcn-ui components
• 🔧 TypeScript - Fully typed for a better development experience
• 🌙 Dark Mode Ready - Seamless theme support
• 📱 Responsive Design - Adapts to different screen sizes

🚀 Quick Start

Prerequisites

Before you begin, make sure you have the following installed on your macOS system:

Required Software

• macOS: Version 10.15 (Catalina) or higher
• Node.js: v16 or higher (Download)
• npm: v7 or higher (comes bundled with Node.js)
• Git: Pre-installed on macOS, or download here

Verify Your Installation

Check if you have the required tools installed by running these commands in your Terminal:

# Check Node.js version
node --version
# Should output: v16.x.x or higher

# Check npm version
npm --version
# Should output: 7.x.x or higher

# Check Git version
git --version
# Should output: git version 2.x.x or higher

If any of these commands don't work, you'll need to install the missing software.

Installation Methods

Method 1: Standard Installation (Recommended for Beginners)

1. Open Terminal

   • Press Cmd + Space to open Spotlight
   • Type "Terminal" and press Enter

2. Clone the repository

   git clone https://github.com/SYOP200/macwidget-studio.git
   cd macwidget-studio

3. Switch to the dev branch

   git checkout dev

4. Install dependencies

   This will download all the packages needed for the project:

   npm install

   This may take 2-5 minutes depending on your internet connection.

5. Start the development server

   npm run dev

   You should see output like:

   VITE v5.x.x  ready in xxx ms
   
   ➜  Local:   http://localhost:5173/
   ➜  Network: use --host to expose
   

6. Open in your browser

   • The app will automatically open, or
   • Manually navigate to http://localhost:5173 in your web browser

Method 2: Using Bun (Faster Alternative)

If you want faster installation and builds, you can use Bun:

1. Install Bun

   curl -fsSL https://bun.sh/install | bash

2. Clone and navigate to the repository

   git clone https://github.com/SYOP200/macwidget-studio.git
   cd macwidget-studio
   git checkout dev

3. Install dependencies with Bun

   bun install

4. Start the development server

   bun run dev

Method 3: GitHub Desktop (For Non-Command Line Users)

1. Install GitHub Desktop

   • Download from desktop.github.com
   • Install and sign in with your GitHub account

2. Clone the repository

   • Click "File" → "Clone Repository"
   • Go to the "URL" tab
   • Enter: https://github.com/SYOP200/macwidget-studio.git
   • Choose a local path and click "Clone"

3. Switch to dev branch

   • In GitHub Desktop, click "Current Branch"
   • Select "dev" from the list

4. Open in Terminal

   • Click "Repository" → "Open in Terminal"
   • Run the following commands:

   npm install
   npm run dev

Troubleshooting Installation

Common Issues and Solutions

Problem: command not found: node

# Solution: Install Node.js from https://nodejs.org/
# Choose the LTS (Long Term Support) version

Problem: permission denied errors during npm install

# Solution: Don't use sudo! Instead, fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Problem: Port 5173 already in use

# Solution: The dev server will automatically use the next available port
# Or you can manually kill the process using that port:
lsof -ti:5173 | xargs kill -9

Problem: ERR_OSSL_EVP_UNSUPPORTED error

# Solution: This is a Node.js 17+ OpenSSL issue. Add this to your terminal:
export NODE_OPTIONS=--openssl-legacy-provider
# Then run npm run dev again

Problem: Slow installation on macOS

# Solution: Clear npm cache and try again
npm cache clean --force
npm install

First-Time Setup Checklist

• Node.js and npm installed and verified
• Git installed and verified
• Repository cloned successfully
• On the dev branch
• Dependencies installed without errors
• Development server running
• App opens in browser at http://localhost:5173

Next Steps After Installation

Once you have the app running:

1. Explore the interface - Familiarize yourself with the widgets
2. Check the code - Look at src/ directory to see how it works
3. Make a small change - Try editing a component and see it update live
4. Read the documentation - Continue reading this README for more details

Screenshots

Main Dashboard:

Settings Tab:

Custom Widget Tab:

📖 Usage

Development Mode

To run the project in development mode with hot-reload:

npm run dev

This will start a local development server where you can see your changes in real-time.

Building for Production

To create a production-ready build:

npm run build

The optimized files will be generated in the dist directory.

Preview Production Build

To preview the production build locally:

npm run preview

Linting

To check your code for potential issues:

npm run lint

🛠️ Tech Stack

• Framework: React 18
• Build Tool: Vite
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: shadcn-ui
• Linting: ESLint

📁 Project Structure

macwidget-studio/
├── .github/              # GitHub workflows and configurations
├── public/               # Static assets
├── src/                  # Source code
│   ├── components/       # React components
│   ├── lib/             # Utility functions and helpers
│   └── ...              # Other source files
├── index.html           # HTML entry point
├── package.json         # Project dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── vite.config.ts       # Vite configuration
└── tailwind.config.ts   # Tailwind CSS configuration

🎯 Available Scripts

Script	Description
npm run dev	Start development server with hot-reload
npm run build	Build for production
npm run preview	Preview production build locally
npm run lint	Run ESLint to check code quality

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a new branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Please make sure to update tests as appropriate and follow the existing code style.

🐛 Bug Reports

If you find a bug, please open an issue with:

• A clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Screenshots (if applicable)
• Your environment (OS, Node version, etc.)

📝 License

This project is licensed under the MIT license specified in the LICENSE file.

🔒 Security

For security concerns, please review our Security Policy.

📞 Support

• 📧 Open an issue for bug reports or feature requests
• 💬 Start a discussion for questions or ideas
• ⭐ Star this repository if you find it helpful!

🙏 Acknowledgments

• Built with Lovable
• UI components from shadcn-ui
• Icons from Lucide

---

Made with ❤️ by SYOP200