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

258
README.md
View file

@ -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:**
```bash
git clone https://github.com/JosunLP/UserScriptProjectTemplate.git my-userscript
cd my-userscript
```
2. **Install dependencies:**
• 🚀 **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
## Installation
### Quick Start
```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
4. **Start development:**
### Development Setup
```bash
# Install dependencies
npm install
# Start development mode with auto-rebuild
npm run dev
# Type checking
npm run type-check
# Linting and formatting
npm run validate
```
5. **Build for production:**
## Usage
```bash
npm run build:prod
```
## 📁 Project Structure
### 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<ModuleEvents> {
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_**

19
package.json
View file

@ -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 <info@josunlp.de>",
"license": "MIT",