#Formatting

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

• Parallel formatting: rs fmt formats files concurrently in a worker pool.
• Yuku parser: rs fmt uses the high-performance Yuku parser by default for JavaScript, JSX, and TypeScript 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:

import { define } from 'rstack';

define.fmt({
  printWidth: 100,
  singleQuote: true,
});

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

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

#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:

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 and pnpm-lock.yaml.

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

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: rs fmt 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: rs fmt ignores lock files by default, 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.

rs fmt still applies the rules from the second and third steps to files passed directly on the command line and to paths specified with --stdin-filepath. It formats a path only if none of these rules excludes it.

#Sort package.json fields

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

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.

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 } },
  ],
});

#Prettier plugins

To add formatting capabilities that are not built into Rstack, 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. Reference each plugin by package name, path, or URL instead. For example, install and enable prettier-plugin-tailwindcss:

npm install -D prettier-plugin-tailwindcss

yarn add -D prettier-plugin-tailwindcss

pnpm add -D prettier-plugin-tailwindcss

bun add -D prettier-plugin-tailwindcss

deno add -D npm:prettier-plugin-tailwindcss

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.