Terminal Styling#

Dokploy uses xterm.js (@xterm/xterm) for all interactive terminal components. Because xterm.js renders into a shadow-DOM-like canvas/DOM structure, its theming is split between xterm's own theme option (passed at construction) and CSS rules in globals.css that target xterm's generated class names. This split makes terminal styling sensitive to any global CSS change — most notably, major UI framework upgrades.

Terminal Components#

Two terminal component implementations exist in the codebase:

Both follow the same pattern: xterm is initialized inside a useEffect, configured with identical theme options, and connected to a WebSocket backend via AttachAddon.

XTerm Theme Configuration#

Both terminals are constructed with 1 2:

theme: {
  cursor: resolvedTheme === "light" ? "#000000" : "transparent",
  background: "rgba(0, 0, 0, 0)",
  foreground: "currentColor",
}

Key decisions:

• background: "rgba(0, 0, 0, 0)" — transparent, so the terminal inherits the surrounding card/panel background. Avoids a hard-coded black box in light mode.
• foreground: "currentColor" — inherits the CSS color value from the wrapping element, making text automatically adapt to light/dark mode.
• cursor — explicitly #000000 in light mode (xterm's default cursor is white, invisible on a light background); transparent in dark mode. This was introduced to fix the light-mode invisible-cursor regression in PR #936.

resolvedTheme is provided by the next-themes hook useTheme() 3.

CSS Cascade Dependencies (globals.css)#

Three xterm-specific CSS sections in apps/dokploy/styles/globals.css complete the styling:

1. Viewport geometry 4:

• .xterm-viewport — adds border-radius: 0.75rem to round the terminal's scroll container.
• .xterm .xterm-viewport — forces overflow-y: auto to ensure the terminal is scrollable.
• .xterm .xterm-screen — sets overflow: hidden to clip canvas overflow.

2. Paste highlight 5:

.xterm-bg-257.xterm-fg-257 {
  background-color: var(--terminal-paste) !important;
  color: currentColor !important;
}

xterm uses color index 257 for clipboard paste selections. Without this rule, pasted text appears invisible. The --terminal-paste CSS variable is defined per theme 6 7:

• Light mode: rgba(0, 0, 0, 0.2)
• Dark mode: rgba(255, 255, 255, 0.2)

3. Monospace font enforcement — an earlier regression (#terminal span being overridden by global Inter sans-serif styles) was fixed in PR #268 by removing the offending #terminal span global rule and explicitly setting fontFamily to a full monospace stack in the xterm config. The current components carry lineHeight: 1.4 and convertEol: true 8.

Recurring Regression Pattern#

Terminal styling has regressed repeatedly at framework boundaries. The root cause is the same each time: xterm-generated class names (xterm-*) are invisible to Tailwind's purge/scan, so they must be maintained as explicit CSS rules — any global CSS reset or @layer base change can silently break them.

Adding a New Terminal Component#

When creating a new terminal component:

1. Copy the theme object pattern from either existing component — do not hard-code colors.
2. Import @xterm/xterm/css/xterm.css 9 — required for xterm's internal layout.
3. Load ClipboardAddon if paste support is needed 10.
4. Do not add CSS rules that target #terminal span or other xterm internals — use the xterm theme option instead.
5. Verify in both light and dark mode before merging.

Key Files#