ShojiWM

Documents

• English
• 日本語

Quick Start

Source installs are documented in the getting started guide. Experimental NixOS support is also available:

nix develop
cargo run --release -p shoji_wm -- --dev

Prefer Rust? The default config is also available as a Rust config (see Config languages):

nix develop
cargo run --release -p shojiwm_rs --example default_config

For NixOS module installation, see the installation docs.

Features

• Window management
• Animations
• Screenshots and screen sharing via xdg-desktop-portal-shojiwm
• XWayland support via xwayland-satellite
• Custom shaders
• Layer shell support
• Multi-monitor support
• Config in TypeScript/TSX, Rust, or any language through a pluggable config runtime
• Intel, AMD, and NVIDIA GPU support

Why not Niri or Hyprland?

Niri and Hyprland are, at their core, software that bundles a window manager and a compositor together.

ShojiWM is different. It provides only the compositor, plus window-manager functionality as a default config.

In other words, the window-manager part is something you can program entirely and freely yourself. That is exactly why it bills itself as "The most customizable Wayland compositor with TypeScript (tsx)."

Here is an example. The code below implements a window's close button. When you run it, the button's composition changes reactively on hover, so its appearance updates.

const CloseButton = ({ window }: { window: WaylandWindow }) => {
  const [hover, setHover] = useState(false);

  const borderColor = hover((hover) => (hover ? "#00000000" : "#F0808030"));

  var icon: CompositionRenderable | null = null;
  if (hover()) {
    icon = (
      <Image
        src="./assets/x.svg"
        style={{
          width: 16,
          height: 16,
          position: "absolute",
          zIndex: 1,
          pointerEvents: "none",
        }}
      />
    );
  }

  return (
    <Box style={{ position: "relative", flexShrink: 0 }}>
      <Button
        onHoverChange={setHover}
        style={{
          width: 16,
          height: 16,
          borderRadius: 8,
          background: "#FFFFFF20",
          border: { px: 1, color: borderColor },
        }}
        onClick={window.close}
      />
      {icon}
    </Box>
  );
};

Config languages

TypeScript/TSX is the default, not a requirement. The compositor core (shojiwm_lib) talks to its config through a language-neutral runtime interface, and ShojiWM ships two runtimes:

Language	Runtime	Notes
TypeScript/TSX	shoji_wm (embedded Deno/V8)	The default; hot reload with Super + Shift + R
Rust	shojiwm_rs	Same reactive model as the TypeScript SDK (signals, view builders, COMPOSITOR); your config compiles into its own compositor binary
Anything else	Implement ConfigRuntime + RuntimeLauncher from shojiwm_lib::runtime_api	C#, Lua, Python, ... in its own crate, without linking V8

The whole default config is ported to Rust in src/shojiwm_rs/examples/default_config. Here is the close button above, in Rust:

fn close_button(window: Window) -> Element {
    let hover = signal(false);
    let border = hover.map(|hover| if *hover { hex("#00000000") } else { hex("#F0808030") });

    Flex::column()
        .style(Style::new().relative().flex_shrink(0.0))
        .child(
            Button::new()
                .on_hover_change(move |value| hover.set(value))
                .on_click(move || window.close())
                .style(
                    Style::new()
                        .size(16.0, 16.0)
                        .border_radius(8.0)
                        .background(hex("#FFFFFF20"))
                        .border(1.0, border),
                ),
        )
        .child_dyn(move || {
            hover.get().then(|| {
                Image::new("./assets/x.svg").style(
                    Style::new().size(16.0, 16.0).absolute().z_index(1).pointer_events_none(),
                )
            })
        })
}

See Config languages in the docs for the Rust API and for writing a runtime for another language.

How ShojiWM compares

How ShojiWM differs from two popular Wayland compositors, Niri and Hyprland.

Legend: ✅ Yes / built-in  ·  🟡 Partial / limited  ·  ❌ No

Capability	Niri	Hyprland	ShojiWM
Server-side decoration (SSD) customization via a standard API	❌	❌	✅
Build your own window-management strategy in TypeScript	❌	🟡 1	✅
Powerful custom shader pipeline API	🟡 2	🟡 3	✅
Linux gaming support, including tearing	🟡 4	✅	✅
First-class xwayland-satellite support	✅	❌	✅

1 Hyprland 0.55+ adds custom layouts and event scripting via Lua (not TypeScript); core WM behavior remains built-in.

2 Custom GLSL is limited to window open/close/resize animations.

3 A single full-screen screen shader, not a per-element pipeline.

4 Niri supports VRR (adaptive sync), but not a tearing / immediate-flip mode.

Comparison reflects each project at the time of writing; corrections are welcome.