create-tampermonkey-typescript 1.0.8

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 neth392
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# create-tampermonkey-typescript
+
+> A CLI scaffolding tool for creating minimal TamperMonkey userscript projects written in TypeScript.
+
+Write your userscripts in TypeScript, organize code across multiple files, and let the toolchain handle the rest 
+— bundling, CSS injection, and userscript header generation are all taken care of. The result is a single `.user.js` 
+file ready to install in TamperMonkey.
+
+---
+
+## Features
+
+📦 **TypeScript with multi-file support** — Structure your project however you like. All source files are bundled into 
+a single IIFE-format JavaScript file via [Vite](https://vite.dev/), fully compatible with TamperMonkey.
+
+🏷️ **Automatic userscript header** — The `// ==UserScript==` block is generated from a template (`userscript.txt`) and
+prepended to every build. Metadata fields such as name, version, and description are pulled directly from `package.json`, 
+keeping a single source of truth.
+
+🎨 **CSS injection** — Import `.css` files from TypeScript as you normally would. At build time, styles are extracted 
+and bundled into the output script, then injected into the page at runtime — no manual DOM manipulation required.
+
+⚛️ **Optional React support** — Scaffold the project with React pre-configured, including type declarations for 
+`unsafeWindow.React` and `unsafeWindow.ReactDOM`, and utility functions for accessing them at runtime.
+
+🚀 **GitHub Actions workflows** — Optionally include CI/CD workflows that automatically create Git tags when 
+`package.json` version changes, and publish GitHub Releases with the built script attached.
+
+🔧 **Package manager agnostic** — Generated projects are standard Node.js projects. Use npm, yarn, or pnpm — 
+whichever you prefer.
+
+---
+
+## Quick Start
+
+### npm
+
+```bash
+npx create-tampermonkey-typescript
+```
+
+### yarn
+
+```bash
+yarn create tampermonkey-typescript
+```
+
+### pnpm
+
+```bash
+pnpm create tampermonkey-typescript
+```
+
+The CLI will walk you through the project configuration — name, version, description, author — and let you 
+select optional features (React, Git). The output is your new project folder containing its own `README.md`
+to get you started. You can preview that file here: [Generated Project README](templates/base/README.md)
+
+---
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import prompts from 'prompts';
+import kleur from 'kleur';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'url';
+const __FILENAME = fileURLToPath(import.meta.url);
+const __DIRNAME = path.dirname(__FILENAME);
+const TEMPLATES_DIR = path.join(__DIRNAME, '../templates');
+const defaultDevDeps = [
+    'typescript', //
+    'vite',
+    'vite-plugin-banner',
+    'vite-plugin-css-injected-by-js',
+    'ts-node',
+    '@types/tampermonkey',
+];
+const defaultDeps = [];
+const baseTsConfig = {
+    compilerOptions: {
+        types: ['vite/client', 'node'],
+        target: 'ES2022',
+        module: 'ESNext',
+        moduleResolution: 'NodeNext',
+        strict: true,
+        esModuleInterop: true,
+        forceConsistentCasingInFileNames: true,
+        skipLibCheck: true,
+        resolveJsonModule: true,
+        outDir: 'dist',
+        baseUrl: '.',
+        paths: {
+            '@/*': ['src/*'],
+        },
+        lib: ['ES2022', 'dom', 'dom.iterable'],
+    },
+    include: ['src'],
+};
+const availableFeatures = [
+    {
+        name: 'React',
+        description: 'Adds react support to the project',
+        directory: path.join(TEMPLATES_DIR, 'react'),
+        tsConfigModifier: (config) => (config.compilerOptions.jsx = 'react-jsx'),
+        devDependencies: ['react', 'react-dom', '@types/react', '@types/react-dom'],
+    },
+    {
+        name: 'Git',
+        description: 'Initializes the new project as a git repository',
+        directory: path.join(TEMPLATES_DIR, 'git'),
+        hook: (params) => execInProjectDir(`git init && git add . && git commit -m "Initial commit"`, params),
+    },
+    {
+        name: 'Github Workflows',
+        description: 'Includes 2 workflows; one for tagging releases with current version, and another for building & creating a release',
+        directory: path.join(TEMPLATES_DIR, 'github-workflows'),
+    },
+];
+const availablePackageManagers = [
+    {
+        name: 'npm',
+        exists: () => commandExists('npm --version'),
+        installCmd: 'npm install',
+        addDependencyCmd: 'npm install',
+        runCmd: 'npm run',
+    },
+    {
+        name: 'yarn',
+        exists: () => commandExists('yarn --version'),
+        installCmd: 'yarn install',
+        addDependencyCmd: 'yarn add',
+        runCmd: 'yarn run',
+    },
+    {
+        name: 'pnpm',
+        exists: () => commandExists('pnpm --version'),
+        installCmd: 'pnpm install',
+        addDependencyCmd: 'pnpm add',
+        runCmd: 'pnpm run',
+    },
+];
+async function main() {
+    console.log(kleur.green('create-tampermonkey-typescript'));
+    if (!checkCwdAccess())
+        return;
+    if (!findValidPackageManager())
+        return;
+    // Prompt for project parameters
+    const promptResults = await promptForParams();
+    const params = {
+        ...promptResults,
+        projectPath: path.join(process.cwd(), promptResults.projectName),
+        features: promptResults.featureNames.map((featureName) => availableFeatures.find((a) => a.name === featureName)),
+        packageManager: availablePackageManagers.find((pm) => pm.name === promptResults.packageManagerName),
+    };
+    // Create the directory
+    logWithPrefix(`Creating directory ${kleur.yellow(params.projectPath)}`);
+    const createDirResult = await createProjectDirectory(params.projectPath);
+    if (typeof createDirResult === 'string') {
+        console.log(kleur.red('An occurred while attempting to create the project directory:'));
+        console.log(kleur.red(createDirResult));
+        return;
+    }
+    // Initialize package.json
+    logWithPrefix(`Creating ${kleur.yellow('package.json')}`);
+    const packageJson = createPackageJson(params);
+    writeObjectToFile(packageJson, 'package.json', params);
+    // Initialize the lock file
+    logWithPrefix(`Initializing lock file`);
+    execInProjectDir(`${params.packageManager.installCmd}`, params);
+    // Gather dependencies
+    const devDeps = [...defaultDevDeps, ...params.features.flatMap((f) => f.devDependencies ?? [])];
+    const deps = [...defaultDeps, ...params.features.flatMap((f) => f.dependencies ?? [])];
+    // Install dev dependencies
+    if (devDeps.length > 0) {
+        logWithPrefix('Installing dev dependencies');
+        console.log(`    ${kleur.dim(devDeps.join(', '))}`);
+        execInProjectDir(`${params.packageManager.addDependencyCmd} -D ${devDeps.join(' ')}`, params);
+    }
+    // Install dependencies
+    if (deps.length > 0) {
+        logWithPrefix('Installing dependencies');
+        console.log(`    ${kleur.dim(deps.join(', '))}`);
+        execInProjectDir(`${params.packageManager.addDependencyCmd}  ${deps.join(' ')}`, params);
+    }
+    // Handle tsconfig.json
+    const tsConfig = { ...baseTsConfig };
+    for (const feature of params.features) {
+        if (feature.tsConfigModifier) {
+            feature.tsConfigModifier(tsConfig);
+        }
+    }
+    logWithPrefix(`Creating ${kleur.yellow('tsconfig.json')}`);
+    writeObjectToFile(tsConfig, 'tsconfig.json', params);
+    // Copy files
+    logWithPrefix('Copying project files');
+    // Base files
+    fs.cpSync(path.join(TEMPLATES_DIR, 'base'), params.projectPath, { recursive: true, force: true });
+    // README.md replacements
+    const readmePath = path.join(params.projectPath, 'README.md');
+    let content = fs.readFileSync(readmePath, 'utf-8');
+    content = content.replaceAll('{{PROJECT_NAME}}', params.projectName);
+    content = content.replaceAll('{{PROJECT_PATH}}', params.projectPath);
+    content = content.replaceAll('{{PM_ADD_DEPENDENCY}}', params.packageManager.addDependencyCmd);
+    content = content.replaceAll('{{PM_RUN_SCRIPT}}', params.packageManager.runCmd);
+    fs.writeFileSync(readmePath, content);
+    // Feature files
+    params.features
+        .filter((f) => f.directory)
+        .forEach((f) => fs.cpSync(f.directory, params.projectPath, { recursive: true, force: true }));
+    // Handle feature hooks
+    params.features
+        .filter((f) => f.hook)
+        .forEach((f) => {
+        logWithPrefix(`Running feature hook: ${kleur.yellow(f.name)}`);
+        f.hook(params);
+    });
+    console.log(`${kleur.green('Done!')} Project created at ${kleur.yellow(params.projectPath)}`);
+}
+function logWithPrefix(message) {
+    console.log(`${kleur.cyan('-')} ${kleur.white(message)}`);
+}
+function commandExists(cmd) {
+    try {
+        execSync(cmd, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function checkCwdAccess() {
+    try {
+        fs.accessSync(process.cwd(), fs.constants.W_OK | fs.constants.R_OK);
+    }
+    catch {
+        console.log(kleur.red('Read & write access to current working directory is required.'));
+        return false;
+    }
+    return true;
+}
+function findValidPackageManager() {
+    if (!availablePackageManagers.find((pm) => pm.exists())) {
+        console.log(kleur.red('Could not find any valid package manager: '));
+        console.log(kleur.yellow(`(${availablePackageManagers.map((pm) => pm.name).join(', ')})`));
+        return false;
+    }
+    return true;
+}
+function validateProjectName(projectName) {
+    if (!projectName || projectName.length === 0)
+        return 'Project name cannot be empty';
+    if (projectName.includes(' '))
+        return 'Project name cannot contain spaces';
+    const projectPath = path.join(process.cwd(), projectName);
+    try {
+        const stats = fs.statSync(projectPath);
+        if (!stats.isDirectory()) {
+            return `Path ${projectPath} already exists and is not a directory.`;
+        }
+        const files = fs.readdirSync(projectPath);
+        if (files.length > 0)
+            return `Directory ${projectPath} already exists and is not empty.`;
+    }
+    catch { }
+    return true;
+}
+async function promptForParams() {
+    return await prompts([
+        {
+            type: 'text',
+            name: 'projectName',
+            message: 'Project name:',
+            format: (s) => s.trim(),
+            validate: (s) => validateProjectName(s.trim()),
+        },
+        {
+            type: 'text',
+            name: 'version',
+            message: 'Version:',
+        },
+        {
+            type: 'text',
+            name: 'description',
+            message: 'Description:',
+        },
+        {
+            type: 'text',
+            name: 'author',
+            message: 'Author:',
+        },
+        {
+            type: 'select',
+            name: 'packageManagerName',
+            message: 'Package manager:',
+            choices: availablePackageManagers.filter((pm) => pm.exists()).map((pm) => ({ title: pm.name, value: pm.name })),
+        },
+        {
+            type: 'multiselect',
+            name: 'featureNames',
+            message: 'Select features:',
+            choices: availableFeatures.map((f) => ({ title: f.name, value: f.name, description: f.description })),
+        },
+    ], {
+        onCancel: () => process.exit(0),
+    });
+}
+async function createProjectDirectory(path) {
+    try {
+        fs.mkdirSync(path, { recursive: true });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        return 'Unknown error.';
+    }
+}
+function createPackageJson(params) {
+    return {
+        name: params.projectName,
+        description: params.description,
+        version: params.version,
+        author: params.author,
+        main: 'dist/script.user.js',
+        type: 'module',
+        scripts: {
+            build: 'vite build',
+        },
+    };
+}
+function writeObjectToFile(object, fileName, params) {
+    const filePath = path.join(params.projectPath, fileName);
+    const jsonString = JSON.stringify(object, null, 2);
+    fs.writeFileSync(filePath, jsonString);
+}
+function execInProjectDir(command, params) {
+    execSync(command, { stdio: 'inherit', cwd: params.projectPath });
+}
+main().then(() => { }, (e) => console.error(kleur.red(e.message || e)));

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "create-tampermonkey-typescript",
+  "version": "1.0.8",
+  "description": "CLI tool for generating a TamperMonkey script project written in typescript which is transpiled to JavaScript to be ran in the browser",
+  "license": "MIT",
+  "homepage": "https://github.com/neth392/create-tampermonkey-typescript",
+  "author": "neth392",
+  "keywords": [
+    "tampermonkey",
+    "typescript",
+    "template"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "type": "module",
+  "bin": {
+    "create-tampermonkey-typescript": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/cli.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.10",
+    "@types/prompts": "^2.4.9",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@types/tampermonkey": "^5.0.4",
+    "prettier": "^3.6.1",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "ts-node": "^10.9.2",
+    "type-fest": "^5.4.4",
+    "typescript": "^5.8.3",
+    "vite": "^7.0.0",
+    "vite-plugin-banner": "^0.8.1",
+    "vite-plugin-css-injected-by-js": "^3.5.2"
+  },
+  "dependencies": {
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  }
+}

package/templates/base/README.md

@@ -0,0 +1,213 @@
+# {{PROJECT_NAME}}
+
+## Table of Contents
+
+- 🚀 [Quick Start](#quick-start)
+- 📁 [Project Structure](#project-structure)
+- 🏷️ [Userscript Header](#userscript-header)
+- 📦 [Build Output](#build-output)
+- 🎨 [CSS](#css)
+- 🔗 [Module Resolution](#module-resolution)
+- 📚 [Dependencies](#dependencies)
+- 🐒 [TamperMonkey API](#tampermonkey-api)
+- ⚛️ [React](#react)
+- ⚙️ [GitHub Workflows](#github-workflows)
+
+
+## Quick Start
+
+```bash
+{{PM_RUN_SCRIPT}} build
+```
+
+The built script is output to `dist/script.user.js`
+
+---
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── src/
+│   ├── script.ts          # Entry point
+│   ├── styles.css         # Stylesheet (imported by script.ts)
+│   └── ...                # Your source files
+├── userscript.txt          # TamperMonkey header template
+├── vite.config.ts          # Vite build configuration
+├── tsconfig.json
+└── package.json
+```
+
+#### Added With React
+
+```
+src/
+├── global.d.ts             # Type declarations for unsafeWindow.React / ReactDOM
+└── util/
+    └── react-util.ts       # getReact() and getReactDOM() helpers
+```
+
+#### Added With Git / GitHub Workflows
+
+```
+.github/workflows/
+├── auto-tag.yml            # Creates a Git tag when package.json version changes
+└── release.yml             # Builds and publishes a GitHub Release
+.gitignore
+```
+
+---
+
+## Userscript Header
+
+The file `userscript.txt` defines your script's TamperMonkey metadata. It is automatically prepended to the built script, with placeholders replaced from `package.json` to maintain a single source of truth:
+
+```
+// ==UserScript==
+// @name           <name>           ← package.json "name"
+// @version        <version>        ← package.json "version"
+// @description    <description>    ← package.json "description"
+// @author         <author>         ← package.json "author"
+// @homepage       <homepage>       ← package.json "homepage"
+// ==/UserScript==
+```
+
+You should customize this file to include directives specific to your script, such as `@match`, `@grant`, `@require`, and so on. See the [TamperMonkey documentation](https://www.tampermonkey.net/documentation.php) for the full list of supported tags.
+
+---
+
+## Build Output
+
+[Vite](https://vitejs.dev/) bundles everything into a single IIFE-format JavaScript file:
+
+- All TypeScript is compiled to JavaScript
+- All imported CSS is combined and injected as an inline `<style>` element at runtime
+- The userscript header from `userscript.txt` is prepended
+
+---
+
+## CSS
+
+Import `.css` files from anywhere in your source. All stylesheets are combined into a single style node and injected into the page at runtime — no manual DOM manipulation needed.
+
+```typescript
+import '@/styles.css'
+import './MyComponent.css'
+```
+
+---
+
+## Module Resolution
+
+The `@/` path alias points to `src/`, giving you cleaner imports:
+
+```typescript
+import { helper } from '@/utils/helper'  // → src/utils/helper.ts
+```
+
+---
+
+## Dependencies
+
+Any imported dependency will be included in the bundled script. To keep the output small, the recommended approach is to load libraries via TamperMonkey's [`@require`](https://www.tampermonkey.net/documentation.php?locale=en#meta:require) tag and install them as dev dependencies so they aren't bundled.
+
+**Example with jQuery:**
+
+Install as a dev dependency:
+
+```bash
+{{PM_ADD_DEPENDENCY}} -D jquery
+```
+
+Then add the `@require` tag to `userscript.txt`:
+
+```
+// @require        https://code.jquery.com/jquery-2.1.4.min.js
+```
+
+jQuery is now available at runtime without being bundled into your script.
+
+---
+
+## TamperMonkey API
+
+TypeScript types for `GM_` functions are included out of the box. Use them directly:
+
+```typescript
+GM_getValue('key', defaultValue)
+GM_setValue('key', value)
+
+GM_xmlhttpRequest({
+  method: 'GET',
+  url: 'https://api.example.com',
+  onload: (res) => console.log(res.responseText),
+})
+
+GM_notification('Hello!')
+GM_addStyle('body { color: red; }')
+```
+
+Remember to declare each function you use as a grant in `userscript.txt`:
+
+```
+// @grant          GM_getValue
+// @grant          GM_setValue
+// @grant          GM_xmlhttpRequest
+// @grant          GM_notification
+// @grant          GM_addStyle
+```
+
+---
+
+## React
+
+> This section only applies if React was enabled during project creation.
+
+React and ReactDOM are **not bundled** into the output script. They are expected to be available on the host page via `unsafeWindow`. The generated project includes type declarations (`src/global.d.ts`) and helper functions for accessing them at runtime:
+
+```tsx
+import { getReact, getReactDOM } from '@/util/react-util'
+
+const React = getReact()
+const ReactDOM = getReactDOM()
+
+const App = () => <div>Hello World</div>
+
+const container = document.createElement('div')
+document.body.appendChild(container)
+
+const root = ReactDOM.createRoot(container)
+root.render(<App />)
+```
+
+---
+
+## GitHub Workflows
+
+> This section only applies if Git was enabled during project creation.
+
+Two GitHub Actions workflows are included to automate your release process.
+
+### Auto-Tagging (`auto-tag.yml`)
+
+Runs on every push to `master`. Reads the version from `package.json` and creates a Git tag (e.g., `v1.2.3`) if one doesn't already exist.
+
+### Release (`release.yml`)
+
+Triggers when the auto-tag workflow completes successfully. Runs the build, then creates a GitHub Release with `dist/script.user.js` attached.
+
+### Publishing Workflow
+
+1. Update `version` in `package.json`
+2. Commit and push to `master`
+3. The auto-tag workflow creates a new tag
+4. The release workflow builds and publishes the script
+
+Users can install directly from your releases by adding these tags to `userscript.txt`:
+
+```
+// @updateURL      https://github.com/user/repo/releases/latest/download/script.user.js
+// @downloadURL    https://github.com/user/repo/releases/latest/download/script.user.js
+```
+
+

package/templates/base/src/script.ts

@@ -0,0 +1,6 @@
+/**
+This file is the entry point to your script.
+ */
+
+// Imports your styles. Can be removed if no CSS is used.
+import '@/styles.css'

package/templates/base/src/styles.css

@@ -0,0 +1 @@
+/* Add all styles here */

package/templates/base/userscript.txt

@@ -0,0 +1,7 @@
+// ==UserScript==
+// @name           <name>
+// @version        <version>
+// @description    <description>
+// @author         <author>
+// @homepage       <homepage>
+// ==/UserScript==

package/templates/base/vite.config.ts

@@ -0,0 +1,55 @@
+/**
+ * Configured by create-tampermonkey-typescript to combine your entire codebase into a single TamperMonkey-ready script.
+ * You can modify it as you like.
+ */
+
+import { defineConfig } from 'vite'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import fs from 'fs'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+import banner from 'vite-plugin-banner'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const pkg = JSON.parse(fs.readFileSync(resolve(__dirname, 'package.json'), 'utf8'))
+const hasReact = pkg.devDependencies?.react || pkg.dependencies?.react
+
+// Replaced in the script's header to keep package.json as the source of truth.
+const metaTags = {
+  '<name>': pkg.name,
+  '<version>': pkg.version,
+  '<description>': pkg.description,
+  '<author>': pkg.author,
+  '<homepage>': pkg.homepage,
+}
+
+let meta = fs.readFileSync(resolve(__dirname, 'userscript.txt'), 'utf8')
+
+for (const [tagName, tagValue] of Object.entries(metaTags).filter(([_, v]) => v)) {
+  meta = meta.replace(tagName, tagValue)
+}
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+  plugins: [cssInjectedByJsPlugin({ topExecutionPriority: true }), banner({ content: meta, verify: false })],
+  build: {
+    cssCodeSplit: false,
+    lib: {
+      entry: resolve(__dirname, 'src/script.ts'),
+      name: pkg.name.replace(/[^a-zA-Z0-9]/g, '_'),
+      formats: ['iife'],
+      fileName: () => `script.user.js`,
+    },
+    rollupOptions: {
+      ...(hasReact ? { external: ['react', 'react-dom/client'] } : {}),
+    },
+    outDir: 'dist',
+    minify: false,
+  },
+})

package/templates/github-workflows/.github/workflows/auto-tag.yml

@@ -0,0 +1,42 @@
+# .github/workflows/auto-tag.yml
+name: Auto Tag from package.json
+
+permissions:
+  contents: write
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required to push tags
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Read version from package.json
+        id: pkg
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "PACKAGE_VERSION=$VERSION" >> $GITHUB_ENV
+          echo "TAG_NAME=v$VERSION" >> $GITHUB_ENV
+
+      - name: Create tag if not exists
+        run: |
+          if git rev-parse "$TAG_NAME" >/dev/null 2>&1; then
+            echo "Tag $TAG_NAME already exists. Skipping."
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git tag $TAG_NAME
+            git push origin $TAG_NAME
+          fi

package/templates/github-workflows/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Build & Release Tampermonkey Script
+
+permissions:
+  contents: write
+
+on:
+  workflow_run:
+    workflows: ["Auto Tag from package.json"]
+    types:
+      - completed
+
+jobs:
+  release:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          check-latest: true
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build script
+        run: npm run build
+
+      - name: Get package name
+        id: pkg
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          echo "PACKAGE_NAME=$NAME" >> $GITHUB_ENV
+
+      - name: Get latest tag from Git
+        id: tag
+        run: |
+          git fetch --tags
+          TAG=$(git describe --tags --abbrev=0)
+          echo "TAG_NAME=$TAG" >> $GITHUB_ENV
+          echo "Latest tag: $TAG"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ env.PACKAGE_NAME }}  ${{ env.TAG_NAME }}
+          tag_name: ${{ env.TAG_NAME }}
+          files: dist/script.user.js
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/templates/react/src/global.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A reference to the global `window` object, extended with additional properties
+ * for React and ReactDOM.
+ *
+ * @type {Window & {React: typeof import('react'), ReactDOM: typeof import('react-dom/client')}}
+ * @property {typeof import('react')} React - The React library, providing tools
+ *     for building user interfaces.
+ * @property {typeof import('react-dom/client')} ReactDOM - The ReactDOM library,
+ *     allowing React components to be rendered into the DOM.
+ */
+declare const unsafeWindow: Window & {
+  React: typeof import('react')
+  ReactDOM: typeof import('react-dom/client')
+}

package/templates/react/src/util/react-util.ts

@@ -0,0 +1,24 @@
+/**
+ * Optional utility file for easily accessing the React & ReactDOM objects at runtime.
+ */
+
+import type React from 'react'
+import type ReactDOM from 'react-dom/client'
+
+/**
+ * Retrieves the React object from the global `unsafeWindow` scope.
+ *
+ * @return {typeof React} The React object from the global scope.
+ */
+export function getReact(): typeof React {
+  return unsafeWindow.React
+}
+
+/**
+ * Retrieves the ReactDOM object from the global `unsafeWindow` object.
+ *
+ * @return {typeof ReactDOM} The ReactDOM reference from the global scope.
+ */
+export function getReactDOM(): typeof ReactDOM {
+  return unsafeWindow.ReactDOM
+}

package/templates/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "types": ["vite/client", "node"],
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "lib": ["ES2022", "dom", "dom.iterable"]
+  },
+  "include": ["template/src", "react"]
+}