SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillstavern-ui

tavern-ui

Frontend & websites

View repository

Updated 10-15 16:43

About this skill

SillyTavern frontend development

SillyTavern itself does not provide customized frontend interface rendering capabilities. The frontend development in this skill relies on the third-party extensionTavern Helper（Tavern-Helper, formerly named JS-Slash-Runner): it renders HTML code blocks in message floors and pre-injects global variables such as Vue, jQuery, lodash, and zod into the frontend. Interfaces such as status bars use placeholders (e.g., <StatusPlaceHolderImpl/>) to let regex replace them with HTML code blocks, which are then rendered by Tavern Helper.

Design principles

  • ICON first: The frontend version targets complex interfaces. ICONs behave consistently across different themes/sizes, support CSS coloring, and maintain a visual style consistent with status bars
  • Low coupling: Each component is responsible for only one thing, variable reading is centralized in the store, and business logic is extracted into independent modules, ensuring components are reusable and can be tested individually

Common resources

  • Icons (ICON): FontAwesome free icons, used directly in the frontend interface via the fa-* class
  • Fonts: ZeoSeven Fonts (such as Sarasa Gothic); simply copy its CSS import link
  • CDN（jsdelivr）：Must use a domestically accessible testingcf.jsdelivr.net mirror, rather than cdn.jsdelivr.net
  • Third-party libraries: Use pnpm add to add them. During template packaging they are automatically converted to jsdelivr links, avoiding repeated packaging across multiple interfaces
  • Readability: Use the Adobe color contrast checker to ensure sufficient contrast between background color and text color

Security boundaries

Frontend development is based on the tavern_helper_template shared infrastructure repository. This repository also serves multiple character card projects; everythingsrc/ outside it is shared configuration. Clarify the permission scope to avoid affecting other projects when modifying one project.

Handling process when problems are encountered：

  1. First look for a solution within src/{ProjectName}/ (most problems can be solved within the project)
  2. If it cannot be solved within the project, first check the update notes for tavern_helper_template on GitHub to confirm whether there is an update that can solve the problem; if so, resolve it by pulling the update
  3. If it is confirmed that a shared file must be modified, first inform the user of the impact scope and reason, and execute only after confirmation

Regex for frontend interfaces: locate only, do not parse

This principle applies only to regex for "frontend interfaces".

Regex for frontend interfaces is only responsible forlocating where the interface should be(e.g., replacing <StatusPlaceHolderImpl/> with an HTML code block),and does not process output data—do not use $1 in the regex replacement string to extract fields. The data needed by the interface should be obtained by the frontend code itself:

  • MVU variables: read via defineMvuDataStore . Regex only needs to replace pure placeholders (such as the <StatusPlaceHolderImpl/>used by the status bar), without capture groups
  • Message raw text: obtain the entire message via getChatMessages(getCurrentMessageId())[0] , then in the code .match() analyze it

The simpler the regex, the higher the fault tolerance: as long as it can locate this text, there is no need to care about its internal specific format.

Note: MVU's "variable update" type regex (parsing <update>...</update> content, capturing $2 to update variables) normally relies on capture group extraction, which is unrelated to the above principles.

Development approach

Use tavern_helper_template to develop the frontend interface rendered within message floors. Common interface types:Status bar(persistent interface, placeholder <StatusPlaceHolderImpl/>) andopening form(interactive form opening, custom placeholder, see references/interactive-opening-form.md）。

Development workflow

1. Prepare the development environment

First ask the user whether they have already cloned the tavern_helper_template repository. If so, confirm the repository location and use it directly; if not, perform the following steps:

# 克隆模板仓库
git clone https://github.com/StageDog/tavern_helper_template.git
cd tavern_helper_template

# 安装依赖
pnpm install

After cloning, first read the template root directory's README.md, which contains the tutorial link, CI workflow configuration, jsdelivr auto-update, clone conflict handling, and other complete workflow instructions.

It is recommended to install chrome-devtools-mcp (the template is already configured but each agent tool configuration may differ), to make it convenient for the AI to check browser console errors.

2. Design concept

This step translates the story into visual and component decisions, appending a UI design section to the existing design-spec.md for subsequent coding (developing the status bar interface, CSS color variables) to consume. For complete guidance, see references/design-thinking.md。

If any of the following conditions is met, you must follow：

  • The interface carries dual-line narrative (light line/dark line switching)
  • There is non-standard interaction (collapse, threshold trigger, contextual override, etc.)
  • The user has clear expectations for the visual style
  • The user specified a reference character card

Only when the status bar displays just a few values, you may skip directly to importing the variable structure.

3. Import the variable structure

Copy the project's schema.ts to the template repository's src/{ProjectName}/schema.ts。

Note: the schema.ts structures of the two repositories are interoperable and can be reused directly.

4. Develop the frontend interface

Consume design-spec.md(tavern-design's narrative section + the UI design section appended at this stage):Visual tone(sensory words/interaction persona/semantic color scheme) lands on CSS and interaction feedback,component tree sketchlands on Vue child component splitting and components/ directory planning,information prioritydetermines which blocks go into the title bar and which go into the expanded area.

Prepare assets

According to design-spec.md 's visual tone, select specific assets from "Common Resources" and confirm the integration position:

  • Icons: select the fa-* category by the block semantics in the component tree sketch (e.g., affection→heart, erosion→eye/crack)
  • Fonts: select the font family from ZeoSeven Fonts by tone (soft and rounded series choose Sarasa, sharp tech series choose monospace font)
  • Images (optional): if integrating image generation functionality, generate background/decorative images according to design-spec.md 's semantic color scheme and sensory words; reference the produced images via HTTPS URL, avoiding inline base64 that increases code block size

Start coding only after assets are selected, avoiding interrupting the component splitting rhythm by selecting while writing.

Directory skeleton

Develop in src/{ProjectName}/界面/状态栏/ :

界面/状态栏/
├── index.ts        # 入口文件，等待 MVU 初始化
├── index.html      # HTML 模板
├── App.vue         # 主组件
├── store.ts        # 数据存储，使用 defineMvuDataStore
├── global.css      # 全局样式
└── components/     # 子组件

Key Code：

// store.ts - 连接 MVU 变量
import { defineMvuDataStore } from '@util/mvu';
import { Schema } from '../../schema';

export const useDataStore = defineMvuDataStore(Schema, {
  type: 'message',
  message_id: getCurrentMessageId()
});

<!-- App.vue - 读取变量 -->
<script setup lang="ts">
import { useDataStore } from './store';

const store = useDataStore();
// store.data 即为 schema.ts 定义的 stat_data 变量结构
</script>

Variable Access Methods: There are three equivalent ways to read/write MVU stat_data (recommended: useDataStore, reactive + zod validation). For the relationship among the three, the synchronization mechanism, and migration notes, see references/mvu-variables.md。

5. CSS Color Variable Naming Convention

CSS color variables must usefunctional semanticsnaming; naming by visual description is prohibited.

/* ✓ 正确：功能语义 */
:root {
  --c-primary: #4a90d9;
  --c-danger: #e74c3c;
  --c-surface: #f5f5f5;
  --c-text-muted: #888;
  --c-border: #ddd;
}

/* ✗ 错误：视觉描述 */
:root {
  --c-blue: #4a90d9;
  --c-red: #e74c3c;
  --c-light-gray: #f5f5f5;
  --c-gray: #888;
  --c-light-border: #ddd;
}

6. Local Testing

Static Type Checking

After coding is complete, before starting preview and building, run vue-tsc static type checking once; only after it passes should you proceed to local preview and building (for commands and noise handling, see references/environments/tavern-helper-template.md "8.4 vue-tsc Static Type Checking"):

npx vue-tsc --noEmit 2>&1 | grep "error TS" | grep -E "^src/"

When an error of the type "the frontend references a field that does not exist in the schema" is reported, first determine whether the field is designed state (add a schema field) or temporary internal frontend state (change the frontend reference). If it cannot be determined, ask the user which side should be authoritative, and modify only after confirmation.

schema.ts modifications are performed according to the tavern-cards skill's references/mvu/guide.md#修改流程 , and keep the two copies in the template repository and the user project consistent.

Start Local Preview

First ask the user whether the VS Code Live Server extension is installed.

If installed, guide the user to open it with tavern_helper_template as the VS Code workspace (the root directory must be fixed as the current workspace directory）。

New versions of Live Server do not inject CORS headers by default. For symptom details and the .vscode/settings.json configuration, see references/environments/tavern-helper-template.md "Cross-Port CORS".

If not installed, start a static file server with CORS headers yourself, with the working directory set to the tavern_helper_template root directory.

WSL environment: When the development server runs on WSL2 and the browser/SillyTavern runs on Windows, using localhost directly may load a blank page. You need to bind Live Server to 0.0.0.0 and replace localhostwith the WSL IP. For the handling steps, see references/environments/tavern-helper-template.md "Port Forwarding in the WSL Environment".

At the same time, run the following command to watch for file changes and automatically recompile:

pnpm watch

Configure Preview Regex

Temporarily change 正则/状态栏界面.html in the project to load the local server. This file has one line consisting of pure triple backticks (```, without a language tag) at both the beginning and the end as code block markers; these two lines must be preserved when modifying.

```
<body>
<script>
$('body').load('http://localhost:5500/dist/{ProjectName}/界面/状态栏/index.html')
</script>
</body>
```

dist/{ProjectName}/ is the compilation output path of pnpm watch . Adjust the port number according to the server port actually used.

After modifying the preview regex, follow references/packaging.md 's packaging process to generate a preview version character card, then guide the user to import it into SillyTavern and check 开发 in the SillyTavern Helper's 允许监听option to preview modifications in real time.

In the WSL environment, the socket.io auto-reload port (6621) likewise needs to be accessible from the Windows side; the handling steps are the same as "Port Forwarding in the WSL Environment" above.

Development/Production Switching: During local testing, use the above localhost address; before deployment, change 正则/状态栏界面.html back to the CDN address (see step 8).

For runtime errors such as preview not refreshing, white screen, port conflicts, and abnormal iframe height, check references/environments/tavern-helper-runtime.md 's isolation boundary and iframe height adaptation; for watch mode not compiling and entry scanning issues, check references/environments/tavern-helper-template.md 's real-time preview mechanism and webpack build pipeline.

7. Frontend Bundling and Deployment

# 打包到 dist 文件夹
pnpm build

Deployment Methods：

  • GitHub + jsdelivr(Recommended): Push to a GitHub repository and access via the jsdelivr CDN. The CDN approach makes the regex code block load only a link instead of inlining the entire HTML, significantly reducing the burden on SillyTavern to render the code block (see "CDN Caching and Refreshing" after step 8)
  • Self-Hosting: Deploy to any accessible URL

For errors such as build failures, abnormal artifacts, CI not updating dist, or runtime undefined variables, check references/environments/tavern-helper-template.md 's webpack build pipeline, CI workflow, and pre-injected global variable list; for runtime variable scope and lifecycle issues, check references/environments/tavern-helper-runtime.md 's pre-injection mechanism and variable scope chain.

8. Update the Placeholder

After deployment is complete, modify the 正则/状态栏界面.htmlin the project (the file has a single line of pure triple backticks ``` at both the beginning and end as code block markers, which must be retained).

CDN / Self-Hosted Syntax(loads link only):

```
<body>
<script>
$('body').load('https://testingcf.jsdelivr.net/gh/{GH_USER}/{GH_REPO}/dist/{ProjectName}/界面/状态栏/index.html')
</script>
</body>
```

Replace:

  • {GH_USER}: GitHub username
  • {GH_REPO}: repository name
  • {ProjectName}: project name

Full Inline Syntax(no CDN, paste the compiled artifact directly):

The source file is in the template repository tavern_helper_template/dist/{ProjectName}/界面/状态栏/index.html, and the target file is in the user project's 正则/状态栏界面.html. The two are in different directories. Run the following command in the root directory of tavern_helper_template to write the compiled artifact, together with the leading and trailing triple-backtick lines, into the target file ({ProjectName} replace with the real project name; adjust the target path according to the project's actual location):

{
  echo '```'
  cat "dist/{ProjectName}/界面/状态栏/index.html"
  echo '```'
} > "{ProjectName}/正则/状态栏界面.html"

Note: The inline approach significantly increases the size of the regex code block (including all CSS/JS), placing a heavy rendering burden on SillyTavern. Use it only when CDN conditions are unavailable.

CDN Caching and Refreshing

The jsdelivr main server, mirror servers, and players' browsers all cache files, so changes will not take effect immediately after pushing. The following methods can solve this:

  • Wait for automatic refresh: The template repository is already configured with bundle.yaml, which automatically increments the version number during packaging. After about 12h, the jsdelivr main server cache updates automatically
  • Force refresh(choose one of two):
    • purge: Enter the link in https://www.jsdelivr.com/tools/purge (replacetestingcf.jsdelivr with cdn.jsdelivr), which immediately refreshes the main server cache; mirror servers are unaffected
    • Switch mirror domain: Temporarily switch to fastly.jsdelivr.net or gcore.jsdelivr.net and other mirror sites that have not yet cached it
  • Players clear cache: Players actively clear their browser cache
  • Self-hosted server: HTTPS must be configured, otherwise players using https cloud SillyTavern cannot load it

9. Repackage

Follow the packaging process of the tavern-cards skill's references/packaging.md to generate the official character card.

What the Template Already Provides

The tavern_helper_template repository already includes the following:

  • Writing rules：.cursor/rules/(frontend interface, SillyTavern helper APIs, MVU variable framework, etc.)
  • Interface type definitions：@types/(SillyTavern and SillyTavern helper APIs)
  • Built-in libraries: Vue, Pinia, Vue Router, VueUse, GSAP, Tailwind CSS, jQuery, lodash, zod, etc. (see package.json）
  • example project：示例/角色卡示例/界面/

For more advanced usages, refer to the README.md in the 教程文档 links.

References

This index is the authoritative source for the references/ document list. Those marked "consult as needed" are troubleshooting and in-depth reference documents; the rest are proactively loaded documents.

references/
├── design-thinking.md                         —— 设计构思流程（感官词/交互人格/语义配色/组件构思）
├── mvu-variables.md                           —— MVU 变量读写方式（useDataStore / 酒馆助手接口 / Mvu 函数，三写法关系、同步机制、迁移注意点）
├── interactive-opening-form.md                —— 开局表单前端界面（交互表单开局：自定义占位符、读写 stat_data、提交触发生成与部署）
└── environments/
    ├── tavern-helper-template.md              —— tavern_helper_template 开发环境（目录骨架/webpack/CI/实时预览/预注入变量）（按需查阅）
    └── tavern-helper-runtime.md               —— Tavern-Helper 运行时（iframe 隔离/生命周期/变量作用域/错误排查速查表）（按需查阅）