stash-plugin-builder

Build Stash plugins using React, SCSS, and other libraries with TypeScript support.

Benefits of using stash-plugin-builder:

1. Supports React JSX, TypeScript, Scss, Sass, Less, Css modules and Stylus out of the box
2. Live reloading
3. Install npm packages and ship it with your plugins
4. Cross-source dependency installer
5. Cross browser theme support with Autoprefixer
6. 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-plugin

yarn

yarn create stash-plugin

2. Build plugin

cd to the generated plugin folder and run

npm run build

The 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 watch

Just saving the source code file will auto build and reload stash.

4. Build plugin for distribution

npm run build-dist

This 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: TetraxUserscriptLibrary # cross-source plugin id
          source: https://tetrax-10.github.io/stash-stuffs/index.yml # cross-source plugin source url
    # the following assets and csp structure are just default plugin.yml structure
    assets: # optional list of assets
        /: assets
    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...
externalPath:
    - /plugin/MyPlugin/assets/background.png # tell esbuild, its a external path and not a file path
# 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: TetraxUserscriptLibrary # cross-source plugin id
          source: https://tetrax-10.github.io/stash-stuffs/index.yml # cross-source plugin source url

Cli 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