A local browser tool for building one final userscript manager userscript file from many smaller source files.
Local Userscript Builder helps split large userscript manager userscripts into manageable project files while still producing the single-file output that userscript manager requires.
It is useful when a userscript grows from a few hundred lines into several thousand lines and becomes difficult to edit directly inside the browser extension editor.
The tool runs locally in the browser. No server, Node.js, Python, build chain, package manager, or framework is required.
Local Userscript Builder loads a project folder, reads project.toml, collects source files from src/, combines them in the defined order, inserts readable include markers, and produces a final .txt userscript build.
The generated output can be copied directly from the editor area or downloaded as a text file for manual insertion into userscript manager.
- local browser-only build tool
- no installation required
- no framework dependency
- folder loading
- file loading
- drag-and-drop loading
- recursive folder reading
project.tomlmanifest support- manifest-based build order
- generated manifest helper
- output editor with copy button
.txtdownload output- include markers for every source file
- missing-file warnings
- unlisted-file visibility
- default exclusion of
dist/,distribution/,docs/,doc/,changelog/, and documentation files - per-file remove button
The final output is controlled by project.toml.
The builder does not guess the final source order for normal builds. Files are included in the order listed in:
[build]
files = [
"00-userscript-header.txt",
"01-wrapper-start.js",
"10-constants.js",
"99-wrapper-end.js"
]Recommended project structure:
Project-Build/
project.toml
src/
00-userscript-header.txt
01-wrapper-start.js
10-constants.js
20-route-detection.js
30-storage.js
40-ui.js
90-utils.js
99-wrapper-end.js
dist/
docs/
changelog/
Only files listed in project.toml are included in the generated userscript.
The builder creates a text output file, usually:
project-name-v0.1.0.txt
The .txt format is intentional. It is safer for downloading, archiving, reviewing, and manually copying into userscript manager.
Every included source file is wrapped in build markers:
// ============================================================================
// BUILD_INCLUDE_START: src/30-storage.js
// ============================================================================
// source code
// ============================================================================
// BUILD_INCLUDE_END: src/30-storage.js
// ============================================================================This makes the final generated userscript easier to inspect and debug.
If no project.toml exists yet, the tool can generate a starter manifest from the currently loaded source files.
The generated manifest is a helper, not a replacement for review. For reliable builds, project.toml should be checked and committed with the project.
- modern desktop browser
- local file access through file picker or drag-and-drop
- JavaScript enabled
- userscript manager only needed for using the generated userscript, not for running the builder
- Prepare a project folder with
project.tomlandsrc/. - Open Local Userscript Builder.
- Load the project folder.
- Check the file list and log output.
- Click
Build Script. - Copy the generated userscript or download it as
.txt. - Paste the final output into userscript manager.
Default ignored project paths:
dist/distribution/changelog/changelogs/docs/doc/Default ignored project files:project.tomlREADME*.mdREADME*.txtAGENT.mdAGENTS.mdPROJECT-MAP*.mdPROJECT-MAP*.txt
Local-Userscript-Builder-v0.1.2.txt- main local builder toolproject.toml- build manifest for a userscript projectsrc/- source files used for the final userscript builddist/- optional generated output folderdocs/- optional documentation folderchangelog/- optional changelog folderAGENTS.md- project rules for AI agents and coding assistants
Show repository structure
javascript-local-userscript-builder/ # Repository root.
├── assets/ # Static repository assets.
│ └── img/ # README and documentation images.
│ └── Screenshot-LoTeK-Local-Userscript-Builder.png # Main README screenshot.
├── examples/ # Example projects for testing and screenshots.
│ └── example-userscript-project/ # Neutral demo userscript project.
│ ├── docs/ # Documentation for the example project.
│ │ └── README-AI.txt # Short AI note for the demo project.
│ ├── src/ # Source files used by project.toml.
│ │ ├── 00-userscript-header.txt # Example userscript metadata header.
│ │ ├── 01-wrapper-start.js # IIFE wrapper start and strict mode.
│ │ ├── 10-script-info.js # Demo script metadata constant.
│ │ ├── 20-demo-banner.js # Small neutral demo feature.
│ │ ├── 90-utils.js # Minimal helper functions.
│ │ └── 99-wrapper-end.js # Final boot call and wrapper close.
│ ├── PROJECT-MAP.md # AI/human overview of demo file roles.
│ └── project.toml # Build manifest for the example project.
├── AGENTS.md # AI and coding-agent rules.
├── CHANGELOG.md # Version history in Keep a Changelog format.
├── LICENSE # MIT license.
├── Local-Userscript-Builder.html # Main local HTML builder tool.
└── README.md # Public GitHub documentation.
This tool does not modify userscript manager userscripts directly.
It only generates text output. You manually copy the final build into userscript manager or download it as a .txt file.
Always test generated builds in a separate userscript manager test script before replacing a working production script.
This project was developed with the assistance of AI tools for research, coding support, and documentation.
MIT License.