jss-rtl

jss-rtl is a plugin for JSS, the CSS-in-JS authoring library, that adds right-to-left (RTL) support by flipping style rules along the x-axis. It wraps the rtl-css-js conversion engine internally, so properties like padding-left, margin-right, and transform translations are automatically mirrored into their RTL equivalents as JSS processes each rule.

Teams can author styles once in a single direction and let jss-rtl generate the mirrored stylesheet, or flip the behavior to go from RTL back to LTR. It integrates as the last plugin in a JSS pipeline (jss.use(rtl())), and exposes a small options surface — enabled to toggle the whole plugin at runtime, opt to switch between opt-out and opt-in flipping, and a per-rule flip: true/false property for exceptions on individual rule sets or entire sheets.

What You Get

• A drop-in JSS plugin usable via jss.use(rtl()) or appended to jss-preset-default’s plugin list
• Automatic mirroring of directional CSS properties (padding-left/right, margin-left/right, transform translations, etc.) via the bundled rtl-css-js engine
• A global enabled switch for toggling RTL conversion at runtime without removing the plugin from the pipeline
• An opt mode ('in' or 'out') to control whether flipping applies by default or only when explicitly requested
• Per-rule and per-sheet flip: true/false overrides for exceptions to the default behavior
• Full TypeScript type definitions shipped with the package

Common Use Cases

• Adding Arabic, Hebrew, Persian, or Urdu locale support to a React/JSS application without hand-writing mirrored CSS
• Maintaining a single source of truth for component styles while serving both LTR and RTL layouts
• Runtime language switching where a user can toggle text direction and have the UI’s spacing and alignment flip automatically
• Excluding specific rules (icons, fixed-direction graphics) from automatic flipping via the flip: false escape hatch

Under The Hood

Architecture The entire plugin is a single factory function (src/main.ts) that returns an object implementing JSS’s onProcessStyle(style, rule, sheet) plugin hook — there is no internal layering because the problem is scoped to one CSS-transform step run once per rule. The function closes over its enabled/opt options, short-circuits font-face rules (which have no meaningful direction), strips a rule-level flip prop when the plugin is disabled, resolves the effective flip decision from sheet-level and rule-level overrides, and delegates the actual property mirroring to the external rtl-css-js conversion function. The design cleanly separates “should this rule flip” decision logic from the mechanical CSS transformation itself.

Tech Stack Written in TypeScript and compiled with tsc to a lib/ output directory, with type declarations shipped alongside the compiled JS. The only runtime dependency is rtl-css-js, which performs the actual property-mirroring; jss itself is declared as a peer dependency rather than bundled, so the plugin composes with whatever JSS version the host app already uses. The dev toolchain uses mocha with ts-node for direct TypeScript test execution, chai for assertions, and tslint (with the tslint-microsoft-contrib and tslint-eslint-rules rule sets) for linting, wired into a Travis CI pipeline that runs lint and test on every push.

Code Quality A dedicated spec file (src/main.spec.ts) exercises the plugin against a real jss instance across several scenarios — default flipping, global enabled: false, opt-in mode, and per-rule/per-sheet overrides — asserting on the generated CSS output rather than just internal state, which gives reasonably high confidence in correctness. Types are used throughout, though several JSS interop points fall back to any for the untyped parts of the JSS API. Naming is short and consistent with the single-purpose scope of the codebase.

API Design The public surface is intentionally minimal: a single default export function taking an options object with two properties (enabled, opt), both with sensible defaults, plus a flip escape hatch recognized directly on style objects and sheet options. Getting started requires exactly one line (jss.use(rtl())) with zero required configuration, and the opt-in/opt-out toggle plus per-rule override cover the realistic exception cases without expanding the API. Documentation in the README walks through each option with runnable before/after CSS examples.