Skip to content

refactor(packages/ui): internalize third-party Rspress plugins #59

@zrosenbauer

Description

@zrosenbauer

Summary

We currently depend on several third-party Rspress plugins that are raw-copied or resolved at runtime by Rspress's webpack. This creates brittle build behavior — e.g. rspress-plugin-file-tree code-splits its output into chunk files (0~*.js) with hardcoded relative imports, forcing us to copy its entire dist/ into ours and risk clobbering our own build output (see rslib.config.ts 🚨 comment).

We should fork/internalize every third-party plugin we use so we fully control the build output, avoid chunk resolution issues, and can adapt components to our codebase conventions.

Plugins to internalize

Plugin Source Notes
rspress-plugin-file-tree linbudu599/rspress-plugins Chunk files break when copied; hardcoded relative imports; uses rspress-plugin-devkit
rspress-plugin-katex linbudu599/rspress-plugins Math rendering
rspress-plugin-supersub linbudu599/rspress-plugins Superscript/subscript support

Approach

For each plugin:

  1. Clone the source into packages/ui/src/plugins/<name>/
  2. Adapt to our codebase conventions (functional TS, no classes, no ternaries, etc.)
  3. Bundle as part of our Rslib build (single file, no code splitting)
  4. Remove the output.copy rules and node_modules dependency
  5. Register via createRspressConfig the same way mermaidPlugin already works

Why

  • Brittle builds: File-tree chunks must be copied to dist/ root with glob exclusions to avoid clobbering index.mjs / index.d.ts — any change in the plugin's build output breaks us silently
  • No control over code splitting: Plugin authors can change their Rslib config at any time, breaking our copy assumptions
  • Convention mismatch: Third-party code doesn't follow our functional TS standards
  • Mermaid precedent: We already internalized the mermaid plugin successfully — same pattern applies here

Acceptance criteria

  • All three plugins internalized under packages/ui/src/plugins/
  • No rspress-plugin-file-tree, rspress-plugin-katex, or rspress-plugin-supersub in package.json
  • No output.copy rules referencing node_modules in rslib.config.ts
  • pnpm build && pnpm docs:build passes locally and on Vercel
  • File tree, KaTeX math, and superscript/subscript render correctly in docs

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions