For AI agents: the complete documentation index is available at https://rstack.rs/llms.txt, the full documentation bundle is available at https://rstack.rs/llms-full.txt, and this page is available as Markdown at https://rstack.rs/guide/formatting.md.
close
  • English
  • Formatting

    Rstack CLI includes a formatter built on Prettier. Compared with running Prettier directly, rs fmt offers better performance in three ways:

    • Parallel formatting: Files are formatted concurrently in a worker pool.
    • SWC Next parser: The high-performance SWC Next parser is used by default for JavaScript, JSX, and TypeScript files.
    • Persistent cache: Content-based results let later runs skip formatting unchanged files.

    rs fmt supports Prettier options and plugins and adds built-in capabilities such as sorting package.json fields.

    Basic usage

    Run rs fmt without file arguments to format files in the current directory and save the changes:

    rs fmt

    Use --check to verify formatting without changing files:

    rs fmt --check

    See the rs fmt CLI reference for more command-line options.

    Configuration

    Use define.fmt() in rstack.config.ts to set formatting rules. It supports all Prettier options:

    rstack.config.ts
    import { define } from 'rstack';
    
    define.fmt({
      printWidth: 100,
      singleQuote: true,
    });

    In addition to Prettier options and overrides, Rstack CLI provides two options:

    • ignorePatterns: exclude files with Gitignore-compatible patterns.
    • sortPackageJson: sort fields in package.json files. The default value is false.
    Prettier configuration files

    rs fmt does not automatically load Prettier configuration files, .prettierignore, or .editorconfig. Keep formatting options and additional ignore rules in define.fmt(). To load an ignore file explicitly, use --ignore-path.

    Supported languages

    rs fmt supports the same built-in languages as Prettier and normally infers the language from the file name:

    You can add support for other languages with Prettier plugins.

    Formatting scope

    rs fmt determines the formatting scope from the paths passed on the command line. You can combine the following inputs:

    • Files: format only the specified files.
    • Directories: scan directories recursively and format supported files.
    • Glob patterns: match multiple paths, and prefix a pattern with ! to exclude matches.

    When no paths are provided, rs fmt formats the current directory. All glob patterns are resolved from the current working directory. Quote them so that rs fmt, rather than the shell, expands them:

    # Format a directory and a file
    rs fmt src package.json
    
    # Format JavaScript and TypeScript files, excluding generated files
    rs fmt "src/**/*.{js,ts}" "!src/generated/**"

    When scanning directories or globs, rs fmt follows .gitignore rules, skips binary files, and does not traverse version-control directories or node_modules. It also skips files for which Prettier cannot infer a parser.

    .gitignore applies only when scanning directories and globs. It does not exclude files passed explicitly on the command line. To always exclude a file, use ignorePatterns.

    Ignore files

    Use ignorePatterns to exclude files from formatting:

    rstack.config.ts
    import { define } from 'rstack';
    
    define.fmt({
      ignorePatterns: ['dist/**', 'coverage/**', '**/generated/**'],
    });

    Patterns follow Gitignore syntax and are resolved relative to the directory containing the Rstack configuration file. Because they are applied after the files are selected, they also exclude files passed explicitly on the command line.

    Lock files

    By default, rs fmt ignores common lock files, including package-lock.json, pnpm-lock.yaml, and skills-lock.json.

    To format these files, use a negated pattern to explicitly include them:

    rstack.config.ts
    import { define } from 'rstack';
    
    define.fmt({
      ignorePatterns: ['!pnpm-lock.yaml'],
    });

    Ignore order

    rs fmt uses the following three steps to decide which paths to format:

    1. Process command-line arguments and .gitignore: It first processes the files, directories, and glob patterns passed on the command line. A glob that starts with ! excludes matching paths. Directory and glob scans follow .gitignore, while files passed directly do not. Paths excluded in this step cannot be re-included later.
    2. Apply default ignore rules and ignorePatterns: By default, the command ignores lock files, then applies ignorePatterns. These rules are evaluated in order, with later rules taking precedence. For example, !pnpm-lock.yaml re-includes the otherwise ignored file.
    3. Apply files specified with --ignore-path: Each ignore file is evaluated separately, and later rules take precedence within that file. Exclusions from different files and ignorePatterns are combined: if any source ignores a path, that path remains excluded, even if another source re-includes it.

    Even when a file is passed directly on the command line, the default ignore rules, ignorePatterns, and rules from --ignore-path still apply. The same is true for paths specified with --stdin-filepath and for documents formatted through --lsp.

    Sort package.json fields

    Enable sortPackageJson to sort fields in each selected package.json with sort-package-json:

    rstack.config.ts
    import { define } from 'rstack';
    
    define.fmt({
      sortPackageJson: true,
    });

    Overrides

    Use the overrides field to set options for specific files. Each override supports these fields:

    • files: files or glob patterns to match.
    • options: formatting options applied to matching files.
    • excludeFiles: optional files or glob patterns to exclude.
    rstack.config.ts
    import { define } from 'rstack';
    
    define.fmt({
      overrides: [
        {
          files: 'docs/**/*.md',
          excludeFiles: 'docs/generated/**',
          options: {
            proseWrap: 'always',
          },
        },
      ],
    });

    Pattern matching

    The files and excludeFiles patterns are resolved relative to the directory containing the Rstack configuration file.

    In files, a pattern without / matches file names at any depth, while a pattern containing / matches relative paths. In this example, *.md matches Markdown files in any directory, while scripts/**/*.js matches paths relative to the configuration directory:

    define.fmt({
      overrides: [
        { files: '*.md', options: { proseWrap: 'always' } },
        { files: 'scripts/**/*.js', options: { singleQuote: true } },
      ],
    });

    Merge order

    When multiple overrides match, they are applied in declaration order, so later values take precedence. Here, README.md matches both overrides, so the final printWidth is 80:

    define.fmt({
      overrides: [
        { files: '*.md', options: { printWidth: 100 } },
        { files: 'README.md', options: { printWidth: 80 } },
      ],
    });

    Cache

    rs fmt caches results by default to speed up repeated runs on unchanged files. The cache is shared by --write, --check, and --list-different.

    Cache behavior

    Cached results are reused when the file content and formatting options are unchanged. The cache also accounts for Rstack and Prettier versions, as well as the package name, version, and entry point of installed Prettier plugins. Changes to any of these cause the file to be processed again.

    The cache is stored in .rstack/cache/fmt under the Rstack configuration root. Running from a subdirectory uses the same cache as long as the command resolves to the same rstack.config.* file.

    CLI options

    Use --no-cache to disable the cache for the current run. Existing cache files are left unchanged:

    rs fmt --no-cache

    Use --cache-location <path> to choose a different cache directory. Relative paths are resolved from the current working directory:

    rs fmt --cache-location .cache/rs-fmt

    The custom directory is excluded from formatting. Add it to .gitignore if you do not want to commit it.

    Cache exceptions

    rs fmt bypasses the persistent cache in the following cases:

    • Input comes from stdin or an editor buffer through --lsp.
    • A file uses a local or linked Prettier plugin, or a plugin without package version information.
    • A file uses prettier-plugin-tailwindcss. Its class sorting can depend on external stylesheets and configuration files that the cache does not track.

    If you enable these plugins only for specific files through overrides, only those files bypass the cache. Other files can still use it.

    Clearing the cache

    To clear the formatting cache, run:

    rs fmt --clear-cache

    If you use a custom cache directory, include --cache-location <path>.

    The command deletes only the cache file, then exits without formatting files. See --clear-cache for details.

    Prettier plugins

    To add formatting capabilities that are not built into Rstack CLI, install the corresponding Prettier plugin and add it to plugins. Plugins can be referenced by package name, file path, or URL. Package names and relative paths are resolved from the directory containing the Rstack configuration file.

    Because rs fmt loads plugins in workers, plugin objects cannot be passed directly.

    For example, install and enable prettier-plugin-tailwindcss:

    npm
    yarn
    pnpm
    bun
    deno
    npm install -D prettier-plugin-tailwindcss
    rstack.config.ts
    import { define } from 'rstack';
    
    define.fmt({
      plugins: ['prettier-plugin-tailwindcss'],
    });

    To enable a plugin only for specific files, add plugins to the options of an overrides entry.