JosunLP/UserScriptProjectTemplate
1
0
Fork 0
mirror of https://github.com/JosunLP/UserScriptProjectTemplate.git synced 2025-10-14 09:00:11 +00:00
Code Issues Projects Releases Wiki Activity Actions

feat: Add .editorconfig and update package.json for improved project structure and versioning

Browse source
This commit is contained in:
JonasPfalzgraf 2025-07-11 18:15:19 +02:00
parent ca60f67d37
commit 884aed648f
3 changed files with 193 additions and 112 deletions
Download patch file Download diff file Expand all files Collapse all files

24
.editorconfig Normal file
View file

@ -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

262
README.md
View file

@ -1,88 +1,81 @@
# UserScript Project Template # 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 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.
- 🚀 **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
## 🚀 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 ## Installation
git clone https://github.com/JosunLP/UserScriptProjectTemplate.git my-userscript
cd my-userscript
```
2. **Install dependencies:** ### Quick Start
```bash ```bash
npm install git clone https://github.com/JosunLP/UserScriptProjectTemplate.git
``` cd UserScriptProjectTemplate
npm install
```
3. **Configure your script:** ### Development Setup
- Edit `header.config.json` to set your target domains
- Update `package.json` with your script details
4. **Start development:** ```bash
# Install dependencies
npm install
```bash # Start development mode with auto-rebuild
npm run dev npm run dev
```
5. **Build for production:** # Type checking
npm run type-check
```bash # Linting and formatting
npm run build:prod npm run validate
``` ```
## 📁 Project Structure ## Usage
### Project Structure
```bash ```bash
src/ src/
├── index.ts # Main application entry point ├── types/ # TypeScript type definitions
├── types/ # TypeScript definitions ├── utils/ # Utility functions (Storage, DOM, Events)
│ └── userscript.d.ts
├── utils/ # Utility functions
│ ├── storage.ts # Persistent storage helpers
│ ├── dom.ts # DOM manipulation utilities
│ └── events.ts # Event system
├── core/ # Core application logic ├── 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 The main configuration is in `header.config.json`. This file controls UserScript metadata generation:
- `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:
```json ```json
{ {
"environments": { "environments": {
"development": { "development": {
"includes": ["http://localhost:*/*"], "includes": ["http://localhost:*/*", "https://localhost:*/*"],
"grants": ["GM_setValue", "GM_getValue", "GM_log"] "grants": ["GM_setValue", "GM_getValue", "GM_log", "GM_notification"]
}, },
"production": { "production": {
"includes": ["https://your-domain.com/*"], "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 # Production
- `NODE_ENV=production` for production builds 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 ```typescript
import { Storage } from '@/utils/storage'; import { Storage } from '@/utils/storage';
// Store data // Save data
Storage.set('key', { some: 'data' }); Storage.set('userData', { name: 'John', visits: 5 });
// Retrieve data // Get data with default value
const data = Storage.get('key', defaultValue); const userData = Storage.get('userData', { name: '', visits: 0 });
// Check existence // Check if key exists
if (Storage.has('key')) { if (Storage.has('userData')) {
// Key exists // Key exists
} }
// Remove data
Storage.remove('userData');
``` ```
### DOM Utilities ### DOM Utilities
Helper functions for DOM manipulation:
```typescript ```typescript
import { DOMUtils } from '@/utils/dom'; import { DOMUtils } from '@/utils/dom';
// Wait for element // Wait for element to appear
const element = await DOMUtils.waitForElement('.my-selector'); const element = await DOMUtils.waitForElement('.my-selector');
// Add styles // Add custom styles
DOMUtils.addStyles(` DOMUtils.addStyles(`
.my-class { color: red; } .my-class { color: red; }
`); `);
// Create element // Create element with attributes
const button = DOMUtils.createElement('button', { const button = DOMUtils.createElement('button', {
textContent: 'Click me', textContent: 'Click me',
onclick: () => console.log('Clicked!') onclick: () => console.log('Clicked!'),
}); });
``` ```
### Events ### Event System
Type-safe communication between modules:
```typescript ```typescript
import { EventEmitter } from '@/utils/events'; import { EventEmitter } from '@/utils/events';
@ -159,48 +182,77 @@ emitter.on('userAction', ({ userId }) => {
emitter.emit('userAction', { userId: '123' }); emitter.emit('userAction', { userId: '123' });
``` ```
## 🎯 Extending the Template ### Module System
1. **Add new modules** in `src/modules/` Create reusable, event-driven 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:
```typescript ```typescript
// src/modules/example.ts
import { EventEmitter } from '@/utils/events'; import { EventEmitter } from '@/utils/events';
import { Storage } from '@/utils/storage';
export class ExampleModule extends EventEmitter { interface ModuleEvents {
initialize() { initialized: void;
console.log('Example module initialized'); actionPerformed: { action: string };
// Your module logic here }
export class MyModule extends EventEmitter<ModuleEvents> {
async initialize() {
// Module initialization logic
this.emit('initialized', undefined);
} }
} }
``` ```
## 🔧 Development Tips ## UserScript Compatibility
- Use `console.log()` freely - it's enabled in UserScripts • **Tampermonkey:** Full support with all GM\_\* APIs
- Test in development mode with localhost includes • **Greasemonkey:** Compatible with standard UserScript APIs
- Use TypeScript strict mode for better code quality • **Violentmonkey:** Full compatibility
- Leverage the storage utilities for persistent data • **Safari:** Works with userscript managers
- Use the event system for loose coupling between modules
## 📝 License ## Contributing
MIT License - see [LICENSE](LICENSE) file for details.
## 🤝 Contributing
1. Fork the repository 1. Fork the repository
2. Create a feature branch 2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes 3. Make your changes and ensure tests pass: `npm run validate`
4. Run tests and linting 4. Commit your changes: `git commit -m 'Add amazing feature'`
5. Submit a pull request 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_**

19
package.json
View file

@ -1,7 +1,7 @@
{ {
"name": "userscript-project-template", "name": "userscript-project-template",
"version": "0.0.1", "version": "1.0.0",
"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.", "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", "main": "index.ts",
"module": "node", "module": "node",
"scripts": { "scripts": {
@ -12,6 +12,7 @@
"build:prod": "vite build --mode production && npm run build-userScriptHeader", "build:prod": "vite build --mode production && npm run build-userScriptHeader",
"build-tooling": "tsc ./tools/userScriptHeader.ts --resolveJsonModule --esModuleInterop", "build-tooling": "tsc ./tools/userScriptHeader.ts --resolveJsonModule --esModuleInterop",
"build-userScriptHeader": "npm run build-tooling && node ./tools/userScriptHeader.js", "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": "eslint src/ --ext .ts,.tsx",
"lint:fix": "eslint src/ --ext .ts,.tsx --fix", "lint:fix": "eslint src/ --ext .ts,.tsx --fix",
"format": "prettier --write \"src/**/*.{ts,tsx,json}\"", "format": "prettier --write \"src/**/*.{ts,tsx,json}\"",
@ -23,11 +24,15 @@
"url": "git+https://github.com/JosunLP/UserScriptProjectTemplate.git" "url": "git+https://github.com/JosunLP/UserScriptProjectTemplate.git"
}, },
"keywords": [ "keywords": [
"User", "userscript",
"Script", "tampermonkey",
"TypeScript", "greasemonkey",
"Webpack", "typescript",
"Ingress" "template",
"vite",
"browser-automation",
"web-enhancement",
"browser-scripting"
], ],
"author": "Jonas Pfalzgraf <info@josunlp.de>", "author": "Jonas Pfalzgraf <info@josunlp.de>",
"license": "MIT", "license": "MIT",