Saltar al contenido principal

API

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Si deseas ejecutar Prettier programáticamente, consulta esta página.

import * as prettier from "prettier";

Nuestras APIs públicas son todas asíncronas. Si necesitas una versión síncrona por algún motivo, puedes probar @prettier/sync.

prettier.format(source, options)​

format se utiliza para formatear texto con Prettier. options.parser debe configurarse según el lenguaje que estés formateando (ver la lista de parsers disponibles). Alternativamente, puedes especificar options.filepath para que Prettier infiera el parser por la extensión del archivo. Puedes proporcionar otras opciones para sobrescribir los valores predeterminados.

await prettier.format("foo ( );", { semi: false, parser: "babel" });
// -> 'foo()\n'

prettier.check(source [, options])​

check verifica si el archivo ha sido formateado con Prettier usando esas opciones y devuelve una Promise<boolean>. Es equivalente a los parámetros --check o --list-different en la CLI y es útil para ejecutar Prettier en entornos de CI.

prettier.formatWithCursor(source [, options])​

formatWithCursor formatea el código y traslada la posición del cursor desde el código sin formatear al formateado. Esto es útil para integraciones en editores, para evitar que el cursor se mueva al formatear el código.

Debe proporcionarse la opción cursorOffset para especificar la ubicación del cursor.

await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" });
// -> { formatted: '1;\n', cursorOffset: 1 }

prettier.resolveConfig(fileUrlOrPath [, options])​

resolveConfig resuelve la configuración para un archivo fuente específico, usando su ruta o URL como primer argumento. La búsqueda de configuración comenzará en el directorio del archivo y ascenderá por la jerarquía de directorios. También puedes pasar directamente la ruta del archivo de configuración como options.config si prefieres evitar la búsqueda. Devuelve una promesa que se resolverá como:

La promesa se rechazará si ocurre un error al analizar el archivo de configuración.

Si options.useCache es false, se omitirá toda caché.

const text = await fs.readFile(filePath, "utf8");
const options = await prettier.resolveConfig(filePath);
const formatted = await prettier.format(text, {
  ...options,
  filepath: filePath,
});

Si options.editorconfig es true y existe un archivo .editorconfig en tu proyecto, Prettier lo analizará y convertirá sus propiedades a la configuración equivalente de Prettier. Esta configuración será sobrescrita por .prettierrc, etc. Actualmente se admiten estas propiedades de EditorConfig:

  • end_of_line

  • indent_style

  • indent_size/tab_width

  • max_line_length

prettier.resolveConfigFile([fileUrlOrPath])​

resolveConfigFile encuentra la ruta del archivo de configuración de Prettier que se usará al resolver la configuración (por ejemplo, al llamar a resolveConfig). Devuelve una promesa que se resolverá como:

  • La ruta del archivo de configuración.

  • null, si no se encontró ningún archivo.

La promesa se rechazará si ocurre un error al analizar el archivo de configuración.

La búsqueda comienza en process.cwd(), o en el directorio de fileUrlOrPath si se proporciona.

const configFile = await prettier.resolveConfigFile(filePath);
// you got the path of the configuration file

prettier.clearConfigCache()​

Cuando Prettier carga archivos de configuración y plugins, la estructura del sistema de archivos se almacena en caché para mejorar el rendimiento. Esta función borra dicha caché. Generalmente solo es necesaria para integraciones en editores que detectan cambios en el sistema de archivos posteriores al último formateo.

prettier.getFileInfo(fileUrlOrPath [, options])​

getFileInfo puede ser utilizado por extensiones de editores para decidir si un archivo específico necesita ser formateado. Este método devuelve una promesa que se resuelve en un objeto con las siguientes propiedades:

{
  ignored: boolean;
  inferredParser: string | null;
}

La promesa será rechazada si el tipo de fileUrlOrPath no es string o URL.

Configurar options.ignorePath (string | URL | (string | URL)[]) y options.withNodeModules (boolean) influye en el valor de ignored (false por defecto).

Si el fileUrlOrPath dado es ignorado, el inferredParser siempre será null.

Proporcionar rutas de complementos en options.plugins ((string | URL | Plugin)[]) ayuda a extraer inferredParser para archivos no soportados por el núcleo de Prettier.

Al establecer options.resolveConfig (boolean, por defecto true) en false, Prettier no buscará archivos de configuración. Esto es útil si esta función solo se usa para verificar si un archivo es ignorado.

prettier.getSupportInfo()​

Devuelve una promesa que se resuelve en un objeto que representa las opciones, analizadores, lenguajes y tipos de archivo que Prettier soporta.

La información de soporte tiene el siguiente aspecto:

{
  languages: Array<{
    name: string;
    parsers: string[];
    group?: string;
    tmScope?: string;
    aceMode?: string;
    codemirrorMode?: string;
    codemirrorMimeType?: string;
    aliases?: string[];
    extensions?: string[];
    filenames?: string[];
    linguistLanguageId?: number;
    vscodeLanguageIds?: string[];
    isSupported?(options: { filepath: string }): boolean;
  }>;
}
nota

Prettier no puede garantizar que filepath exista en el disco.
Cuando se usa desde APIs (ej: prettier.format()), Prettier tampoco puede garantizar que sea una ruta válida.

API de Analizador Personalizado (eliminada)​

Eliminada en v3.0.0 (reemplazada por la API de Complementos)

Antes de que existieran los complementos, Prettier tenía una característica similar pero más limitada llamada analizadores personalizados. Fue eliminada en v3.0.0 ya que su funcionalidad era un subconjunto de lo que hace la API de Complementos. Si la usabas, consulta el siguiente ejemplo para migrar.

❌ API de analizador personalizado (eliminada):

import { format } from "prettier";

format("lodash ( )", {
  parser(text, { babel }) {
    const ast = babel(text);
    ast.program.body[0].expression.callee.name = "_";
    return ast;
  },
});
// -> "_();\n"

✔️ API de complementos:

import { format } from "prettier";
import * as prettierPluginBabel from "prettier/plugins/babel";

const myCustomPlugin = {
  parsers: {
    "my-custom-parser": {
      async parse(text) {
        const ast = await prettierPluginBabel.parsers.babel.parse(text);
        ast.program.body[0].expression.callee.name = "_";
        return ast;
      },
      astFormat: "estree",
    },
  },
};

await format("lodash ( )", {
  parser: "my-custom-parser",
  plugins: [myCustomPlugin],
});
// -> "_();\n"
nota

En general, no se recomienda hacer codemods de esta manera. Prettier usa los datos de ubicación de los nodos AST para muchas cosas como preservar líneas en blanco y adjuntar comentarios. Cuando el AST se modifica después del análisis, los datos de ubicación a menudo pierden sincronización, lo que puede llevar a resultados impredecibles. Considera usar jscodeshift si necesitas codemods.

Como parte de la eliminada API de Analizador Personalizado, anteriormente era posible pasar una ruta a un módulo que exportara una función parse mediante la opción --parser. Utiliza la opción CLI --plugin o la opción API plugins en su lugar para cargar complementos.