The Simple WoltLab Plugin Manager is a command-line toolkit for the full WoltLab Suite plugin lifecycle: setup, development, build, validation, and release. A central text menu runs everything; optional VS Code/Cursor integration adds sidebar buttons.
- Environment setup — Downloads WoltLab Core, clones official docs and WCF source, installs TypeScript typings (d.ts), sets paths to your local WoltLab install.
- Development — TypeScript compile (with watch), unpack packages for inspection, centralized debug logging.
- Build — Creates distributable
.tar.gzpackages with semantic version bumping (patch/minor/major). - Quality assurance — Validates plugins with 13+ checks: security (SQL, XSS), translations (DE/EN), minimum version, WoltLab Cloud compatibility, store requirements.
- Release — Git commit, push, version tagging, GitHub release creation and asset upload.
- Optional — DDEV integration for a local WoltLab dev server; Build Button extension for VS Code/Cursor.
Aligned with the official WoltLab Plugin Store guidelines. TypeScript typings come from the official WoltLab d.ts repo and are cloned during setup.
- Git — required for cloning, building, and pushing your plugins.
- Node.js and npm (optional) — needed if you use TypeScript or the build scripts that compile JavaScript.
- VS Code or Cursor (optional but recommended) — you can open the included workspace file for a tidy project layout; the tools also work from any terminal.
No prior knowledge of WoltLab plugin structure is required. The menu and tools documentation guide you step by step.
-
Open the workspace
Open the filesimple-woltlab-plugin-manager.code-workspacein VS Code or Cursor. This loads the correct folders (e.g. your plugins and the tools). -
Run the tools
Open a terminal and, from the repo root (the folder that containstools.sh), run:./tools.sh
You can also run
./tools/tools.shfrom the same place. The first time you run it, you will be asked whether to run Setup. Say yes if you want to download WoltLab Core, docs, GitHub clone, TypeScript typings, and set an optional path to your local WoltLab install. After that you see the main menu with options for Build, Git Push, TypeScript, Unpack, Help, Validation, and Setup. -
Use the menu
Type the number of the option you want (e.g.1for Build,2for Git Push) and follow the prompts. Type0to exit. Details and a description of each tool are in tools/README.md.
Tip: You can run setup later anytime via menu option "Setup / Vorbereitung" or by running
./tools/setup-minimal.sh. If you set a path to a local WoltLab installation, the workspace file and editor paths are updated automatically.
| Folder | Purpose |
|---|---|
basis-plugin |
Your main or base plugin project. |
mein-plugin |
Additional plugin projects (e.g. that depend on the base plugin). |
plugins-integrieren |
External or reference plugins you want to keep in the workspace. |
woltlab-core |
Where setup stores WoltLab Core files (e.g. WCFSetup) after download. |
woltlab-docs |
WoltLab documentation (Git clone, optional during setup). |
woltlab-github |
WoltLab WCF source code (Git clone, optional during setup). |
woltlab-d-ts |
WoltLab TypeScript typings (d.ts) for use in your plugin’s TypeScript code. |
tools |
All scripts, setup, and the Build Button extension live here. |
| Tool | What it does | Command |
|---|---|---|
| Main menu | Starts the interactive menu. | ./tools.sh or ./tools/tools.sh |
| Setup | Downloads Core, docs, typings; sets paths and optional MCP template. | ./tools/setup-minimal.sh |
| Build | Builds your plugin and can bump version (patch/minor/major). | ./tools/build.sh patch |
| Git Push | Commits, pushes, and creates a GitHub release for your plugin. | ./tools/gitpush.sh |
| TypeScript | Compiles TypeScript to JavaScript (and optional watch mode). | ./tools/typescript.sh |
| Unpack | Unpacks a plugin package into temp_edit/. |
./tools/unpack.sh |
| Validation | Checks your plugin for security issues and store compliance. | ./tools/validate-plugin.sh |
| Help | Opens the tools documentation. | ./tools/help.sh |
Full description of each tool, including options and when to use them: tools/README.md.
In the folder tools/woltlab-build-button you’ll find a VS Code / Cursor extension. It adds a "WoltLab" entry in the sidebar with buttons for Build, Git Push, TypeScript, Unpack, Help, Validation, and the full tools menu so you don’t have to type commands. Load it as a Development extension from that folder. See tools/README.md for how to install and use it.
If you use TypeScript in your plugin, run setup and accept "d.ts klonen" (default: yes). That clones the WoltLab d.ts typings into woltlab-d-ts. In your plugin’s temp_edit/tsconfig.json you can then point to them, for example:
"typeRoots": ["../../woltlab-d-ts"]Details and other options are in tools/README.md.
If you use Cursor with MCP (e.g. DeepWiki), configuration goes in .cursor/ per project (e.g. basis-plugin/.cursor/mcp.json). The setup script can optionally copy a template into basis-plugin/.cursor/ so you don’t have to create it by hand.
Settings like the path to your local WoltLab installation or your GitHub repo URL are stored in tools/.env. That file is not committed to Git (it may contain secrets). Use tools/.env.example as a template: copy it to tools/.env and fill in the values. The setup script can create or update tools/.env for you.