TypeScript Formatter (tsfmt)

Common errors

• sample.ts is not formatted

  cause The content of the specified TypeScript file does not conform to the configured formatting rules.
  fix Run `tsfmt -r <file>` to automatically format and replace the file, or modify your code/configuration to meet the expected format.

• Cannot find module 'typescript'

  cause The `typescript` peer dependency is missing or cannot be resolved by the package manager.
  fix Install `typescript` as a direct dependency in your project: `npm install typescript` or `yarn add typescript`. Ensure the installed version satisfies the peer dependency range of `typescript-formatter`.

• TypeError: [tsfmt] Formatting failed

  cause An error occurred internally during the formatting process, often due to syntax errors in the input TypeScript code or an incompatibility with the TypeScript language service version.
  fix First, check the TypeScript file for any syntax errors. If the file is valid, ensure your `typescript` peer dependency is within the compatible range for `typescript-formatter` and consider upgrading `typescript-formatter` to its latest version.

Warnings

• breaking Major TypeScript version upgrades can cause `typescript-formatter` to behave unexpectedly or fail, as it relies on the internal TypeScript Compiler Service API which can have breaking changes.
  Fix: Always ensure your project's `typescript` peer dependency aligns with the version range specified by `typescript-formatter`. Upgrade `typescript-formatter` when updating your `typescript` version to maintain compatibility.
• gotcha When multiple configuration files (e.g., `tsfmt.json`, `tsconfig.json`, `tslint.json`, `.editorconfig`, `.vscode/settings.json`) exist, their settings can override each other, leading to unexpected formatting results.
  Fix: Use the `--verbose` flag to debug which configuration files are being loaded and applied. Explicitly disable unwanted config sources using flags like `--no-tslint` or `--no-editorconfig` to isolate formatting rules.
• gotcha The project appears to be in maintenance mode, with the last significant update in early 2023. While functional, active development might be slower compared to alternatives.
  Fix: Consider evaluating alternative, more actively maintained formatters like Prettier if rapid updates or extensive new features are critical for your workflow.

Install

• npm install typescript-formatter npm
• yarn add typescript-formatter yarn
• pnpm add typescript-formatter pnpm

Imports

• format
  wrong:

  const { format } = require('typescript-formatter');

  correct:

  import { format } from 'typescript-formatter';

  While primarily a CLI tool, `format` provides programmatic access to format a single TypeScript code string. CommonJS `require` might work in older Node.js contexts, but ESM `import` is preferred for modern TypeScript projects.
• processFiles
  wrong:

  const processFiles = require('typescript-formatter').processFiles;

  correct:

  import { processFiles } from 'typescript-formatter';

  Used for programmatic processing and formatting of multiple files, mirroring the CLI behavior. This function typically takes a list of file paths and options.
• FormatOptions

  import { FormatOptions } from 'typescript-formatter';

  Type import for configuring the detailed formatting behavior when using the programmatic `format` or `processFiles` functions. This type defines properties such as indent size, tab style, and space insertion rules, reflecting the options available via `tsfmt.json`.

Quickstart

This quickstart demonstrates how to programmatically format a TypeScript file using `typescript-formatter`'s `format` function, including configuring specific formatting options.

import { format, FormatOptions } from 'typescript-formatter';
import * as fs from 'fs';
import * as path from 'path';

async function runFormatterExample() {
  const sampleFilePath = path.join(process.cwd(), 'sample.ts');
  const initialContent = `class Sample {hello(word="world"){return "Hello, "+word;}}`;

  // Create a dummy TypeScript file
  await fs.promises.writeFile(sampleFilePath, initialContent, 'utf-8');
  console.log('Original content created:\n', initialContent);

  const options: FormatOptions = {
    // These options correspond to settings found in tsfmt.json or editorconfig
    baseIndentSize: 0,
    indentSize: 2,
    tabSize: 2,
    convertTabsToSpaces: true,
    newLineCharacter: '\n',
    insertSpaceAfterCommaDelimiter: true,
    insertSpaceAfterSemicolonInForStatements: true,
    insertSpaceBeforeAndAfterBinaryOperators: true,
    insertSpaceAfterKeywordsInControlFlowStatements: true,
    insertSpaceAfterFunctionKeywordForAnonymousFunctions: false,
    insertSpaceAfterOpeningAndBeforeClosingNonemptyParenthesis: false,
    insertSpaceAfterOpeningAndBeforeClosingNonemptyBrackets: false,
    insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces: true,
    insertSpaceAfterOpeningAndBeforeClosingTemplateStringBraces: false,
    insertSpaceAfterOpeningAndBeforeClosingJsxExpressionBraces: false,
    insertSpaceAfterTypeAssertion: false
  };

  try {
    // Format the content of the file programmatically
    const formattedResult = await format(sampleFilePath, initialContent, options);
    console.log('\nFormatted content:\n', formattedResult.formatted.trim());

    // Optionally, write the formatted content back to the file
    // await fs.promises.writeFile(sampleFilePath, formattedResult.formatted, 'utf-8');
    // console.log(`Formatted and replaced ${sampleFilePath}`);

  } catch (error) {
    console.error('Formatting failed:', error);
  } finally {
    // Clean up the dummy file
    await fs.promises.unlink(sampleFilePath);
    console.log(`\nCleaned up ${sampleFilePath}`);
  }
}

runFormatterExample().catch(console.error);