UserScript Project Template

Description

Features

Installation

Quick Start

git clone https://github.com/JosunLP/UserScriptProjectTemplate.git
cd UserScriptProjectTemplate
npm install

Development Setup

# 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

Usage

Project Structure

src/
├── types/ # TypeScript type definitions
├── utils/ # Utility functions (Storage, DOM, Events)
├── core/ # Core application logic
├── modules/ # Feature modules
└── index.ts # Main application entry point
tools/
├── userScriptHeader.ts # UserScript header generator
assets/ # Icons and static resources
└── icon.afdesign

Configuration

{
 "environments": {
 "development": {
 "includes": ["http://localhost:*/*", "https://localhost:*/*"],
 "grants": ["GM_setValue", "GM_getValue", "GM_log", "GM_notification"]
 },
 "production": {
 "includes": ["https://your-domain.com/*"],
 "grants": ["GM_setValue", "GM_getValue"]
 }
 }
}

Build Commands

# 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
# Production
npm run build # Build for production
npm run build:prod # Explicit production build
# Quality Assurance
npm run validate # Type check + lint
npm run lint # ESLint with auto-fix
npm run format # Prettier formatting
# Utilities
npm run clean # Clean dist folder
npm run type-check # TypeScript type checking

Build Optimization

Development Workflow

Storage Management

import { Storage } from '@/utils/storage';
// Save data
Storage.set('userData', { name: 'John', visits: 5 });
// Get data with default value
const userData = Storage.get('userData', { name: '', visits: 0 });
// Check if key exists
if (Storage.has('userData')) {
 // Key exists
}
// Remove data
Storage.remove('userData');

DOM Utilities

import { DOMUtils } from '@/utils/dom';
// Wait for element to appear
const element = await DOMUtils.waitForElement('.my-selector');
// Add custom styles
DOMUtils.addStyles(`
 .my-class { color: red; }
`);
// Create element with attributes
const button = DOMUtils.createElement('button', {
 textContent: 'Click me',
 onclick: () => console.log('Clicked!'),
});

Event System

import { EventEmitter } from '@/utils/events';
interface MyEvents {
 userAction: { userId: string };
 dataLoaded: { count: number };
}
const emitter = new EventEmitter<MyEvents>();
// Listen for events
emitter.on('userAction', ({ userId }) => {
 console.log(`User ${userId} performed an action`);
});
// Emit events
emitter.emit('userAction', { userId: '123' });

Module System

import { EventEmitter } from '@/utils/events';
interface ModuleEvents {
 initialized: void;
 actionPerformed: { action: string };
}
export class MyModule extends EventEmitter<ModuleEvents> {
 async initialize() {
 // Module initialization logic
 this.emit('initialized', undefined);
 }
}

Mobile Utilities

import { MobileUtils } from '@/utils/mobile';
// Detect mobile browser and capabilities
const detection = MobileUtils.detect();
console.log('Is Mobile:', detection.isMobile);
console.log('Has Touch:', detection.hasTouch);
console.log('Browser:', detection.browser);
// Add mobile-optimized styles
if (detection.isMobile) {
 MobileUtils.addMobileStyles();
}
// Unified touch/mouse event handling
MobileUtils.addUnifiedEventListener(element, 'start', event => {
 const position = MobileUtils.getEventPosition(event);
 console.log('Touch/click at:', position);
});
// Create mobile-friendly buttons
const button = mobileModule.createMobileButton('Action', () => {
 console.log('Button pressed');
});
// Orientation detection
console.log('Portrait mode:', MobileUtils.isPortrait());

UserScript Compatibility

Mobile Browser Support

Mobile Features

Contributing

Development Guidelines

License

Author