https://github.com/tetrax-10/stash-plugin-builder
Build Stash plugins using React, SCSS, and other libraries with TypeScript support
https://github.com/tetrax-10/stash-plugin-builder
boilerplate boilerplate-generator deployer esbuild esbuild-dev-server esbuilder live-reload plugin-builder promts stash stash-plugin stash-plugin-builder watcher
Last synced: 5 months ago
JSON representation
Build Stash plugins using React, SCSS, and other libraries with TypeScript support
- Host: GitHub
- URL: https://github.com/tetrax-10/stash-plugin-builder
- Owner: Tetrax-10
- License: mit
- Created: 2024-02-01T06:44:53.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-06-18T11:52:54.000Z (11 months ago)
- Last Synced: 2024-11-14T21:42:25.652Z (6 months ago)
- Topics: boilerplate, boilerplate-generator, deployer, esbuild, esbuild-dev-server, esbuilder, live-reload, plugin-builder, promts, stash, stash-plugin, stash-plugin-builder, watcher
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/stash-plugin-builder
- Size: 232 KB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# stash-plugin-builder
Build [Stash](https://stashapp.cc/) plugins using React, SCSS, and other libraries with TypeScript support.
[](https://www.npmjs.com/package/stash-plugin-builder)
## 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](#cross-source-dependency-installer)
5. Cross browser theme support with [Autoprefixer](https://github.com/postcss/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](https://www.npmjs.com/package/create-stash-plugin)
**npm**
```sh
npx create-stash-plugin
```
**yarn**
```sh
yarn create stash-plugin
```
### 2. Build plugin
`cd` to the generated plugin folder and run
```sh
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`
```sh
npm run watch
```
_Just saving the source code file will auto build and reload stash._
### 4. Build plugin for distribution
```sh
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`.
```js
{
"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](https://docs.stashapp.cc/in-app-manual/plugins/#plugin-configuration-file-format) but with extra configuration. See the example below:
```yml
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:
description:
execArgs:
-
```
## 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.
```yml
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](https://github.com/spicetify/spicetify-creator) by [@FlafyDev](https://github.com/FlafyDev)
Made with Love💕 by [Tetrax-10](https://github.com/Tetrax-10)