RTLCSS: LTR to RTL CSS Transformer

Common errors

• TypeError: (0, _postcss.default) is not a function

  cause Attempting to import `postcss` incorrectly in an ESM context (e.g., `import { postcss } from 'postcss';`) when it's typically a default export.
  fix Use `import postcss from 'postcss';` for ESM or `const postcss = require('postcss');` for CommonJS.

• Error: Cannot find module 'postcss'

  cause The `postcss` package, a peer dependency for `rtlcss`, is not installed in the project.
  fix Install PostCSS: `npm install postcss` or `yarn add postcss`.

• Error: Command failed with exit code 1

  cause Running a build process involving `rtlcss` on an unsupported Node.js version, especially after upgrading to `rtlcss` v3.0 or later.
  fix Ensure your Node.js environment meets the minimum requirement of `node >=12.0.0` as specified in `rtlcss` v3.0.0 and above. Upgrade Node.js if necessary.

Warnings

• breaking Version 3.0.0 introduced a breaking change by upgrading to PostCSS 8 and dropping support for Node.js versions 6.x, 8.x, 11.x, and 13.x. Users on these Node.js versions or older PostCSS versions will experience compatibility issues.
  Fix: Upgrade Node.js to version 12.0.0 or higher. Ensure PostCSS is installed at version 8 or later in your project dependencies.
• breaking When upgrading from version 1.0.0 to 2.0.0, the options and configuration settings underwent significant changes. While CSS directives remain backward-compatible, direct programmatic configuration will likely need updates.
  Fix: Refer to the RTLCSS v2.0 documentation for updated configuration schemas and option definitions when migrating from v1.x.
• gotcha RTLCSS is a PostCSS plugin. Attempting to use it directly on CSS strings without integrating it into a PostCSS processing pipeline will result in errors or unexpected behavior.
  Fix: Always use `rtlcss` via `postcss([rtlcss()])` or similar PostCSS integration methods.

Install

• npm install rtlcss npm
• yarn add rtlcss yarn
• pnpm add rtlcss pnpm

Imports

• rtlcss

  import rtlcss from 'rtlcss';
  // Or for CommonJS:
  const rtlcss = require('rtlcss');

  The primary export is a function that returns a PostCSS plugin. RTLCSS itself is typically imported as a default, or the direct result of a CommonJS require.
• postcss
  wrong:

  import { postcss } from 'postcss';

  correct:

  import postcss from 'postcss';
  // Or for CommonJS:
  const postcss = require('postcss');

  PostCSS itself is imported as a default export in most configurations.
• PostCSS plugin usage
  wrong:

  rtlcss.process(cssString);

  correct:

  postcss([rtlcss(/* options */)]).process(cssString, { from: undefined });

  RTLCSS is a PostCSS plugin; it must be used as part of a PostCSS processing chain, not directly on a CSS string.

Quickstart

Demonstrates how to use `rtlcss` as a PostCSS plugin to transform an LTR CSS string into an RTL equivalent, including basic options and directives.

import postcss from 'postcss';
import rtlcss from 'rtlcss';

const ltrCss = `
  .container {
    text-align: left;
    margin-left: 10px;
    padding: 5px 10px 15px 20px;
    border-radius: 5px 10px 0 0;
  }
  /*rtl:ignore*/
  .no-flip {
    left: 0; /* Should not be flipped */
  }
  /*rtl:begin:ignore*/
  .block-ignore {
    right: 0;
    left: 10px;
  }
  /*rtl:end:ignore*/
  .flex-justify {
    justify-content: flex-start;
  }
`;

async function transformCss() {
  try {
    const result = await postcss([rtlcss({
      autoRename: true, // Example option
      processUrls: true // Example option
    })]).process(ltrCss, { from: undefined });
    console.log('LTR CSS:\n', ltrCss);
    console.log('\nRTL CSS:\n', result.css);
  } catch (error) {
    console.error('Error transforming CSS:', error);
  }
}

transformCss();