From 884aed648fb225a4fa0ac96b1047540a49770bdc Mon Sep 17 00:00:00 2001 From: JonasPfalzgraf <20913954+JosunLP@users.noreply.github.com> Date: Fri, 11 Jul 2025 18:15:19 +0200 Subject: [PATCH] feat: Add .editorconfig and update package.json for improved project structure and versioning --- .editorconfig | 24 +++++ README.md | 262 ++++++++++++++++++++++++++++++-------------------- package.json | 19 ++-- 3 files changed, 193 insertions(+), 112 deletions(-) create mode 100644 .editorconfig diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..de37750 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,24 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[*.{yml,yaml}] +indent_size = 2 + +[*.json] +indent_size = 2 + +[*.ts] +indent_size = 2 + +[*.js] +indent_size = 2 diff --git a/README.md b/README.md index e4dcd8a..93b27ce 100644 --- a/README.md +++ b/README.md @@ -1,88 +1,81 @@ # UserScript Project Template -A modern, scalable UserScript project template for building large and structured TypeScript projects for Tampermonkey or Greasemonkey. Originally designed for the Ingress community, but adaptable for any web-based project. +[![GitHub license](https://img.shields.io/github/license/JosunLP/UserScriptProjectTemplate)](https://github.com/JosunLP/UserScriptProjectTemplate/blob/main/LICENSE) +[![GitHub issues](https://img.shields.io/github/issues/JosunLP/UserScriptProjectTemplate)](https://github.com/JosunLP/UserScriptProjectTemplate/issues) +[![GitHub stars](https://img.shields.io/github/stars/JosunLP/UserScriptProjectTemplate)](https://github.com/JosunLP/UserScriptProjectTemplate/stargazers) -## โœจ Features +## Description -- ๐Ÿ”ง **Modern TypeScript** with strict type checking -- ๐Ÿš€ **Vite** for fast builds and development -- ๐Ÿ“ฆ **Modular Architecture** with utilities and event system -- ๐ŸŽฏ **Environment-specific** configurations (dev/prod) -- ๐Ÿงน **ESLint + Prettier** for code quality -- ๐Ÿ’พ **Storage utilities** for persistent data -- ๐ŸŽจ **DOM utilities** for easier manipulation -- ๐Ÿ“ก **Event system** for modular communication -- ๐Ÿ”’ **TypeScript definitions** for UserScript APIs +A modern, production-ready template for building UserScripts using TypeScript and Vite. This template provides a solid foundation with best practices, type safety, and modern development tools for creating sophisticated Tampermonkey and Greasemonkey scripts. -## ๐Ÿš€ Quick Start +## Features -1. **Clone or use this template:** +โ€ข ๐Ÿš€ **Modern Tech Stack:** TypeScript, Vite, ESLint, Prettier +โ€ข ๐Ÿ›ก๏ธ **Type Safety:** Strict TypeScript configuration with comprehensive UserScript API definitions +โ€ข ๐Ÿ”ง **Development Tools:** ESLint, Prettier, automated build pipeline +โ€ข ๐ŸŽฏ **Environment Support:** Separate development and production configurations +โ€ข ๐Ÿ“ฆ **Modular Architecture:** Component system with reusable utilities +โ€ข ๐Ÿ’พ **Storage Management:** Type-safe wrapper for GM_setValue/GM_getValue +โ€ข ๐Ÿ› ๏ธ **Build System:** Optimized Vite configuration with automatic header generation +โ€ข ๐ŸŽจ **DOM Utilities:** Helper functions for element manipulation and waiting +โ€ข ๐Ÿ”’ **Error Handling:** Comprehensive error boundary system +โ€ข โšก **Event System:** Type-safe event emitter for module communication - ```bash - git clone https://github.com/JosunLP/UserScriptProjectTemplate.git my-userscript - cd my-userscript - ``` +## Installation -2. **Install dependencies:** +### Quick Start - ```bash - npm install - ``` +```bash +git clone https://github.com/JosunLP/UserScriptProjectTemplate.git +cd UserScriptProjectTemplate +npm install +``` -3. **Configure your script:** - - Edit `header.config.json` to set your target domains - - Update `package.json` with your script details +### Development Setup -4. **Start development:** +```bash +# Install dependencies +npm install - ```bash - npm run dev - ``` +# Start development mode with auto-rebuild +npm run dev -5. **Build for production:** +# Type checking +npm run type-check - ```bash - npm run build:prod - ``` +# Linting and formatting +npm run validate +``` -## ๐Ÿ“ Project Structure +## Usage + +### Project Structure ```bash src/ -โ”œโ”€โ”€ index.ts # Main application entry point -โ”œโ”€โ”€ types/ # TypeScript definitions -โ”‚ โ””โ”€โ”€ userscript.d.ts -โ”œโ”€โ”€ utils/ # Utility functions -โ”‚ โ”œโ”€โ”€ storage.ts # Persistent storage helpers -โ”‚ โ”œโ”€โ”€ dom.ts # DOM manipulation utilities -โ”‚ โ””โ”€โ”€ events.ts # Event system +โ”œโ”€โ”€ types/ # TypeScript type definitions +โ”œโ”€โ”€ utils/ # Utility functions (Storage, DOM, Events) โ”œโ”€โ”€ core/ # Core application logic -โ””โ”€โ”€ modules/ # Feature modules +โ”œโ”€โ”€ modules/ # Feature modules +โ””โ”€โ”€ index.ts # Main application entry point + +tools/ +โ”œโ”€โ”€ userScriptHeader.ts # UserScript header generator +โ””โ”€โ”€ userScriptHeader.js # Compiled header generator + +assets/ # Icons and static resources ``` -## ๐Ÿ› ๏ธ Available Scripts +### Configuration -- `npm run dev` - Build with watch mode for development -- `npm run build` - Build for production -- `npm run build:prod` - Build for production (explicit) -- `npm run lint` - Run ESLint -- `npm run lint:fix` - Fix ESLint issues -- `npm run format` - Format code with Prettier -- `npm run type-check` - Run TypeScript type checking -- `npm run clean` - Clean dist folder - -## โš™๏ธ Configuration - -### Header Configuration - -Edit `header.config.json` to configure your UserScript metadata: +The main configuration is in `header.config.json`. This file controls UserScript metadata generation: ```json { "environments": { "development": { - "includes": ["http://localhost:*/*"], - "grants": ["GM_setValue", "GM_getValue", "GM_log"] + "includes": ["http://localhost:*/*", "https://localhost:*/*"], + "grants": ["GM_setValue", "GM_getValue", "GM_log", "GM_notification"] }, "production": { "includes": ["https://your-domain.com/*"], @@ -92,53 +85,83 @@ Edit `header.config.json` to configure your UserScript metadata: } ``` -### Environment Variables +### Build Commands -The build system automatically detects the environment: +```bash +# Development +npm run dev # Start development with watch mode +npm run dev:build # Single development build with header +npm run dev:header # Generate header for existing dev build -- `NODE_ENV=development` for development builds -- `NODE_ENV=production` for production builds +# Production +npm run build # Build for production +npm run build:prod # Explicit production build -## ๐Ÿงฐ Utilities +# Quality Assurance +npm run validate # Type check + lint +npm run lint # ESLint with auto-fix +npm run format # Prettier formatting -### Storage +# Utilities +npm run clean # Clean dist folder +npm run type-check # TypeScript type checking +``` + +### Development Workflow + +1. **Configure your script** in `header.config.json` +2. **Start development:** `npm run dev` +3. **Write your code** in the `src/` directory +4. **Build for production:** `npm run build` +5. **Install the UserScript** from `dist/` folder in Tampermonkey/Greasemonkey + +### Storage Management + +The template includes a type-safe storage system: ```typescript import { Storage } from '@/utils/storage'; -// Store data -Storage.set('key', { some: 'data' }); +// Save data +Storage.set('userData', { name: 'John', visits: 5 }); -// Retrieve data -const data = Storage.get('key', defaultValue); +// Get data with default value +const userData = Storage.get('userData', { name: '', visits: 0 }); -// Check existence -if (Storage.has('key')) { +// Check if key exists +if (Storage.has('userData')) { // Key exists } + +// Remove data +Storage.remove('userData'); ``` ### DOM Utilities +Helper functions for DOM manipulation: + ```typescript import { DOMUtils } from '@/utils/dom'; -// Wait for element +// Wait for element to appear const element = await DOMUtils.waitForElement('.my-selector'); -// Add styles +// Add custom styles DOMUtils.addStyles(` .my-class { color: red; } `); -// Create element +// Create element with attributes const button = DOMUtils.createElement('button', { textContent: 'Click me', - onclick: () => console.log('Clicked!') + onclick: () => console.log('Clicked!'), }); ``` -### Events +### Event System + +Type-safe communication between modules: ```typescript import { EventEmitter } from '@/utils/events'; @@ -159,48 +182,77 @@ emitter.on('userAction', ({ userId }) => { emitter.emit('userAction', { userId: '123' }); ``` -## ๐ŸŽฏ Extending the Template +### Module System -1. **Add new modules** in `src/modules/` -2. **Register modules** in your main App class -3. **Use the event system** for module communication -4. **Add utilities** in `src/utils/` for reusable functionality - -Example module: +Create reusable, event-driven modules: ```typescript -// src/modules/example.ts import { EventEmitter } from '@/utils/events'; -import { Storage } from '@/utils/storage'; -export class ExampleModule extends EventEmitter { - initialize() { - console.log('Example module initialized'); - // Your module logic here +interface ModuleEvents { + initialized: void; + actionPerformed: { action: string }; +} + +export class MyModule extends EventEmitter { + async initialize() { + // Module initialization logic + this.emit('initialized', undefined); } } ``` -## ๐Ÿ”ง Development Tips +## UserScript Compatibility -- Use `console.log()` freely - it's enabled in UserScripts -- Test in development mode with localhost includes -- Use TypeScript strict mode for better code quality -- Leverage the storage utilities for persistent data -- Use the event system for loose coupling between modules +โ€ข **Tampermonkey:** Full support with all GM\_\* APIs +โ€ข **Greasemonkey:** Compatible with standard UserScript APIs +โ€ข **Violentmonkey:** Full compatibility +โ€ข **Safari:** Works with userscript managers -## ๐Ÿ“ License - -MIT License - see [LICENSE](LICENSE) file for details. - -## ๐Ÿค Contributing +## Contributing 1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Run tests and linting -5. Submit a pull request +2. Create a feature branch: `git checkout -b feature/amazing-feature` +3. Make your changes and ensure tests pass: `npm run validate` +4. Commit your changes: `git commit -m 'Add amazing feature'` +5. Push to the branch: `git push origin feature/amazing-feature` +6. Open a Pull Request -## ๐Ÿ’ก Originally for Ingress +## Development Guidelines -This template was originally designed for the Ingress community but is versatile enough for any web-based UserScript project. The modular architecture makes it easy to build complex scripts while maintaining code quality and organization. +โ€ข Follow TypeScript best practices +โ€ข Use meaningful variable and function names +โ€ข Add proper error handling +โ€ข Write self-documenting code +โ€ข Follow the established project structure +โ€ข Run `npm run validate` before committing + +## License + +This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). + +## Author + +**_Jonas Pfalzgraf_** + +โ€ข Email: [info@josunlp.de](mailto:info@josunlp.de) +โ€ข GitHub: [@JosunLP](https://github.com/JosunLP) + +## Changelog + +### v0.0.1 (Current) + +โ€ข โœจ Modern TypeScript setup with strict type checking +โ€ข ๐Ÿ›ก๏ธ Comprehensive UserScript API definitions +โ€ข ๐ŸŽจ Modular architecture with utilities and components +โ€ข ๐Ÿ”ง ESLint and Prettier configuration +โ€ข ๐Ÿ“ฆ Optimized Vite build system +โ€ข ๐Ÿš€ Environment-based configuration +โ€ข ๐Ÿ’พ Type-safe storage management +โ€ข ๐ŸŽฏ Event-driven module system +โ€ข โšก DOM manipulation utilities +โ€ข ๐Ÿ› ๏ธ Automated header generation + +--- + +**_Built with โค๏ธ for the UserScript community_** diff --git a/package.json b/package.json index 8c5599d..0277e41 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "userscript-project-template", - "version": "0.0.1", - "description": "A user script project template to create large and structured TypeScript projects for Tampermonkey or Greasemonkey. It is intended to form a scalable base and is primarily aimed at the Ingress community.", + "version": "1.0.0", + "description": "A modern, production-ready template for building UserScripts using TypeScript and Vite. This template provides a solid foundation with best practices, type safety, and modern development tools for Tampermonkey and Greasemonkey scripts.", "main": "index.ts", "module": "node", "scripts": { @@ -12,6 +12,7 @@ "build:prod": "vite build --mode production && npm run build-userScriptHeader", "build-tooling": "tsc ./tools/userScriptHeader.ts --resolveJsonModule --esModuleInterop", "build-userScriptHeader": "npm run build-tooling && node ./tools/userScriptHeader.js", + "validate": "npm run type-check && npm run lint", "lint": "eslint src/ --ext .ts,.tsx", "lint:fix": "eslint src/ --ext .ts,.tsx --fix", "format": "prettier --write \"src/**/*.{ts,tsx,json}\"", @@ -23,11 +24,15 @@ "url": "git+https://github.com/JosunLP/UserScriptProjectTemplate.git" }, "keywords": [ - "User", - "Script", - "TypeScript", - "Webpack", - "Ingress" + "userscript", + "tampermonkey", + "greasemonkey", + "typescript", + "template", + "vite", + "browser-automation", + "web-enhancement", + "browser-scripting" ], "author": "Jonas Pfalzgraf ", "license": "MIT",