stash-plugin-builder
Build Stash plugins using React, SCSS, and other libraries with TypeScript support.
Benefits of using stash-plugin-builder:
- Supports React JSX, TypeScript, Scss, Sass, Less, Css modules and Stylus out of the box
- Live reloading
- Install npm packages and ship it with your plugins
- Cross-source dependency installer
- Cross browser theme support with Autoprefixer
- Built-in gh workflow to automatically build and publish your plugins for every commit push
Usage
1. Generate boilerplate using create-stash-plugin
npm
npx create-stash-pluginyarn
yarn create stash-plugin2. Build plugin
cd to the generated plugin folder and run
npm run buildThe plugin will be built in your stash plugins folder. Reload stash, and the plugin should be listed in the Plugins tab. If not, try clicking Reload plugins button and reload again.
3. Watch plugin
Run this npm command and reload stash just once to connect stash-plugin-builder and stash
npm run watchJust saving the source code file will auto build and reload stash.
4. Build plugin for distribution
npm run build-distThis will build the plugin and output the distributable plugin to the dist folder. You can change this folder in package.json.
Note: You don't need this if you have generated the boilerplate with npx create-stash-plugin as it comes with gh workflow that automatically builds and publishes your plugins on every commit push.
build-config.json
build.js builds your plugins for deployment based on the configuration specified in build-config.json.
{
"plugins": ["plugins/*", "themes/MyTheme"], // use this only if you have monorepo
"outDir": "dist", // if you edit this, update the workflow file too
"excludePluginFolders": "MyTestPlugin", // plugin's folder name not id
"stashPluginSubDir": "my-plugins-dev", // optional sub-dir inside your stash plugins folder
"include": ["README.md", "LICENSE", "foler-one", "foler-two/*"] // these files will be copied to dist branch
}settings.yml structure
The npx create-stash-plugin command should generate a basic settings.yml. However, if you wish to configure advanced settings, please adhere to this structure. The settings.yml follows the same structure as the stash plugin.yml but with extra configuration. See the example below:
id: MyPlugin # should be upper camel case
name: My Plugin
description: My plugin does awesome things
url: https://github.com/Tetrax-10/stash-stuffs
version: 1.0
stashPluginSubDir: my-plugins-dev # optional sub-dir inside your stash plugins folder
ui:
javascript: ./src/index.js # main js file
css: ./styles/main.css # main css file
include: # external js and css files that aren't part of main ui files
- ./lib/colors.js
- ./scripts/injectRemoteCode.js
requires:
- MyUtilsLibrary # local plugin id
- MyReactComponentsLibrary # local plugin id
- id: StashUserscriptLibrary # cross-source plugin id
source: https://stashapp.github.io/CommunityScripts/stable/index.yml # cross-source plugin source url
# the following assets and csp structure are just default plugin.yml structure
assets: # optional list of assets
urlPrefix: fsLocation
csp: # content-security policy overrides
script-src:
- http://alloweddomain.com
style-src:
- http://alloweddomain.com
connect-src:
- http://alloweddomain.com
include: # include external files
- ./assets # assets folder will be copied to the output folder
- ./python/foo.py # foo.py will be copi...
- ./configs/* # all contents inside the configs folder will be copi...
# the following are just default plugin.yml structure and they are used for plugin tasks only
exec:
- python
- "{pluginDir}/foo.py" # values with variable should be wrapped with double quotes
interface: raw
errLog: error
tasks:
- name: <operation name>
description: <optional description>
execArgs:
- <arg to add to the exec line>Cross-source dependency installer
You can simply specify the dependency plugin's id and source, the stash-plugin-builder will automatically bundle a cross-source dependency installer script with your plugin. Therefore, when users install your plugin, the cross-source dependencies will be installed automatically.
ui:
requires:
- MyUtilsLibrary # local plugin id
- MyReactComponentsLibrary # local plugin id
- id: StashUserscriptLibrary # cross-source plugin id
source: https://stashapp.github.io/CommunityScripts/stable/index.yml # cross-source plugin source url
- id: TetraxUserscriptLibrary # cross-source plugin id
source: https://tetrax-10.github.io/stash-stuffs/index.yml # cross-source plugin source urlCli Docs
| Args | Full args | Description | Default |
| -m | --minify | minifies the code | present or not |
| -w | --watch | watches for code change | present or not |
| -i | --in | your plugin folder | CWD |
| -o | --out | output folder | your stash plugins folder |
| -j | --js | main JS file path | main JS file path from settings.yml |
| -c | --css | main CSS file path | main CSS file path from settings.yml |
Credits
Inspired from spicetify-creator by @FlafyDev
Made with Love💕 by Tetrax-10