Prettier 19 🎨 resolveConfig — Programmatic config lookup - KandZ

⏱️ Estimated read: 13 min | |

prettier.resolveConfig() is the function that answers a deceptively simple question: given a file path, which configuration options apply? The answer is not simply “the contents of .prettierrc” because Prettier supports multiple configuration file formats, overrides for specific file patterns, and EditorConfig integration. The function searches from the file’s directory upward, finds the first applicable configuration, applies any overrides that match the file path, merges in EditorConfig properties if enabled, and returns the resulting options object—or null if no configuration was found .

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The function is asynchronous and returns a Promise. It is the first step in any programmatic integration that wants to use the project’s configuration rather than hardcoded options. The format() and check() functions do not resolve configuration automatically; they use the options passed to them. The resolveConfig() function is the bridge between the file on disk and the options object that those functions expect .

Key point: resolveConfig(filePath) returns a Promise that resolves to an options object or null. It searches upward from the file’s directory, applies overrides that match the file path, and optionally merges EditorConfig properties. It does not read the file’s contents; it only resolves the options that should be used when formatting that file.

Why `resolveConfig` exists separately from `format`

The configuration discovery problem. Prettier supports configuration files in many formats: package.json with a "prettier" key, .prettierrc in JSON or YAML, .prettierrc.js, .prettierrc.toml, and several others . The search starts at the file’s directory and walks up the tree until a configuration is found. This discovery logic is not trivial, and it is not the same as reading a single file. The resolveConfig() function encapsulates the discovery, parsing, and merging logic so that integrations do not have to reimplement it.

The overrides problem. A configuration file can contain an overrides array that applies different options to files matching specific patterns. An override for *.test.js might set a different printWidth than the base configuration. The resolveConfig() function applies these overrides based on the file path passed to it. The same configuration file produces different options for different files, and the function is what resolves the difference .

The EditorConfig integration. If options.editorconfig is true and an .editorconfig file exists, Prettier parses it and converts its properties to the corresponding Prettier options. The .prettierrc configuration overrides the EditorConfig properties, so the EditorConfig provides a baseline and the Prettier configuration refines it. The resolveConfig() function handles this merge when the option is enabled .

The trade-off. The function performs filesystem I/O to find and parse the configuration. It caches the results for performance, but the cache can become stale if the configuration changes during a long-running process. The useCache: false option bypasses the cache, and clearConfigCache() clears it entirely. An editor integration that watches for configuration changes must handle the cache invalidation, or it will use outdated options after the user edits .prettierrc .

a. The basic usage pattern

The canonical usage is to resolve the config for a file, read the file, and format it with the resolved options. The filepath option is passed to format() so that the parser is inferred from the extension.

// format-file.mjs — the canonical usage pattern
import { readFile } from "node:fs/promises";
import * as prettier from "prettier";

async function formatFile(filePath) {
  // Resolve the configuration for this specific file.
  // The search starts at the file's directory and walks upward.
  // Returns null if no configuration is found.
  const options = await prettier.resolveConfig(filePath);

  // Read the source file as a string.
  const source = await readFile(filePath, "utf8");

  // Format with the resolved options.
  // The filepath option infers the parser from the extension.
  // Spreading null is safe and contributes no properties.
  const formatted = await prettier.format(source, {
    ...options,
    filepath: filePath,
  });

  return formatted;
}

The filepath option serves two purposes in this call: it tells Prettier which parser to use, and it provides the path for error messages. Without it, the parser option would need to be specified explicitly. The resolved options may include an override that matches the file path, so the same configuration file can produce different options for different files .

b. The search behavior and the explicit config option

The default search starts at the file’s directory and walks up the tree. The options.config parameter overrides the search and points directly to a configuration file.

// resolve-config.mjs — explicit config path
import * as prettier from "prettier";

// Skip the search and use a specific config file.
// This is useful when the config lives outside the project tree,
// or when the integration needs to use a known config regardless
// of the file's location.
const options = await prettier.resolveConfig("src/app.js", {
  config: "/path/to/custom/.prettierrc",
});

// The result is the parsed options from the specified file.
// The search from the file's directory is bypassed entirely.

The explicit config option is documented as the way to bypass the search: “Or you can pass directly the path of the config file as options.config if you don’t wish to search for it” . The search itself is upward-only: it starts at the file’s directory and continues to the filesystem root, stopping at the first configuration file it finds. It does not search downward or sideways .

// resolve-config.mjs — searching from the current directory
// If there is no specific file to resolve for, process.cwd()
// can be used as the starting point for the search.
const options = await prettier.resolveConfig(process.cwd());

The process.cwd() pattern is useful for tools that format stdin or for integrations that need the project-level configuration without a specific file. The search starts at the current working directory and walks upward, which typically finds the project’s .prettierrc .

c. The EditorConfig option and the cache

The editorconfig option enables the merge of .editorconfig properties into the resolved options. The .prettierrc configuration takes precedence over the EditorConfig properties.

// resolve-config.mjs — with EditorConfig integration
const options = await prettier.resolveConfig("src/app.js", {
  // Parse .editorconfig if it exists and convert its properties
  // to Prettier options. The .prettierrc configuration overrides
  // these properties where they overlap.
  editorconfig: true,
});

The supported EditorConfig properties are end_of_line, indent_style, indent_size/tab_width, and max_line_length . The EditorConfig search stops at the project root, unlike the Prettier configuration search, which can walk up to the filesystem root .

The useCache option controls the caching behavior. The default is true, which caches the resolved configuration for performance. Setting it to false bypasses the cache and re-reads the configuration on every call.

// resolve-config.mjs — bypassing the cache
const options = await prettier.resolveConfig("src/app.js", {
  // Re-read the configuration even if it was cached.
  // This is slower but ensures the latest configuration is used.
  useCache: false,
});

The cache is a performance optimization for the common case where the configuration does not change during a process’s lifetime. An editor integration that watches for configuration changes must either bypass the cache or clear it when the configuration file is modified. The prettier.clearConfigCache() function clears the entire cache .

Complete Example Session

// ============================================
// PART 1: THE BASIC RESOLVE AND FORMAT
// ============================================

// format-file.mjs
import { readFile } from "node:fs/promises";
import * as prettier from "prettier";

async function formatFile(filePath) {
  // Step 1: Resolve the configuration for the file.
  // The search starts at the file's directory and walks upward.
  const options = await prettier.resolveConfig(filePath);

  // Step 2: Read the source.
  const source = await readFile(filePath, "utf8");

  // Step 3: Format with the resolved options.
  // The filepath option infers the parser.
  return prettier.format(source, {
    ...options,
    filepath: filePath,
  });
}

// ============================================
// PART 2: THE NULL RESULT
// ============================================

// If no configuration file is found, resolveConfig returns null.
// Spreading null into an object is safe and contributes nothing.
const options = await prettier.resolveConfig("src/app.js");

if (options === null) {
  // No configuration found. The format call will use Prettier's defaults.
  console.log("No configuration file found; using defaults.");
}

// ============================================
// PART 3: THE EXPLICIT CONFIG PATH
// ============================================

// Bypass the search and use a specific config file.
const explicitOptions = await prettier.resolveConfig("src/app.js", {
  config: "./configs/.prettierrc",
});

// ============================================
// PART 4: THE EDITORCONFIG MERGE
// ============================================

// Enable EditorConfig parsing.
// The .prettierrc configuration overrides EditorConfig properties.
const withEditorConfig = await prettier.resolveConfig("src/app.js", {
  editorconfig: true,
});

// ============================================
// PART 5: THE CACHE BYPASS
// ============================================

// Bypass the cache for a long-running process that needs
// to see configuration changes.
const freshOptions = await prettier.resolveConfig("src/app.js", {
  useCache: false,
});

// ============================================
// PART 6: THE OVERRIDES BEHAVIOR
// ============================================

// Given a .prettierrc with an overrides array:
// {
//   "semi": true,
//   "overrides": [
//     { "files": "*.test.js", "options": { "semi": false } }
//   ]
// }
//
// resolveConfig("src/app.test.js") returns { semi: false }.
// resolveConfig("src/app.js") returns { semi: true }.
// The file path determines which override is applied.

// ============================================
// PART 7: THE SEARCH STARTING POINT
// ============================================

// The search starts at the file's directory, not the cwd.
// A file in a nested directory finds the configuration
// in the nearest parent directory.
//
// project/
// ├── .prettierrc          ← found for src/app.js
// └── src/
//     └── app.js           ← resolveConfig("src/app.js")
//
// If src/ has its own .prettierrc, that one is found first.
// The search stops at the first configuration file.

// ============================================
// PART 8: THE CACHE CLEARING
// ============================================

// In a long-running process that watches the filesystem:
prettier.clearConfigCache();

// This clears the cached configurations.
// The next resolveConfig call re-reads the configuration files.

// ============================================
// PART 9: THE CONFIG FILE PATH DISCOVERY
// ============================================

// prettier.resolveConfigFile(filePath) returns the path
// of the configuration file that would be used,
// without parsing it.
const configPath = await prettier.resolveConfigFile("src/app.js");
console.log("Configuration file:", configPath);

// This is useful for debugging which config is being used.

// ============================================
// PART 10: THE VERIFICATION CHECKLIST
// ============================================

// [ ] resolveConfig is awaited.
// [ ] The result is spread into format/check options.
// [ ] The filepath option is passed to format/check.
// [ ] null is handled (spread of null is safe).
// [ ] useCache is set to false if the config can change during the process.
// [ ] editorconfig is set to true if .editorconfig should be merged.

The ten parts covered the basic pattern, the null result, the explicit config path, the EditorConfig merge, the cache bypass, the overrides behavior, the search starting point, the cache clearing, the config file discovery, and the verification checklist. The through-line is that resolveConfig is the discovery mechanism, and format/check are the consumers of its result.

Quick Reference

Function signature

Element	Type	Meaning
`fileUrlOrPath`	`string \| URL`	The file to resolve configuration for
`options.config`	`string`	Explicit config path (bypasses search)
`options.editorconfig`	`boolean`	Merge `.editorconfig` properties
`options.useCache`	`boolean`	Bypass the configuration cache
Return	`Promise<object \| null>`	Resolved options, or `null` if none found

Search behavior

Aspect	Behavior
Starting point	The file’s directory
Direction	Upward through the directory tree
Stop condition	First configuration file found, or filesystem root
Explicit config	Bypasses the search entirely

Related functions

Function	Purpose
`resolveConfigFile(filePath)`	Returns the config file path without parsing
`clearConfigCache()`	Clears the cached configurations

Best Practices

✅ Do This:

// Await the result
const options = await prettier.resolveConfig(filePath);          // ✅

// Spread the result into format options
await prettier.format(source, { ...options, filepath: filePath }); // ✅

// Handle null (spread is safe)
// options is null or an object                                    // ✅

// Use useCache: false in long-running processes
await prettier.resolveConfig(filePath, { useCache: false });     // ✅

❌ Don’t Do This:

// Use the result without awaiting
const options = prettier.resolveConfig(filePath); // Promise      // ❌

// Assume resolveConfig parses the file content
// It only resolves options, not source code.                     // ❌

// Expect the search to go downward
// The search is upward-only from the file's directory.           // ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
`options` is a Promise	`resolveConfig` not awaited	Add `await`
Options are stale after config edit	Cache not invalidated	Use `useCache: false` or `clearConfigCache()`
Wrong config is used	Search found a nearer config	Use `options.config` to specify explicitly
`null` causes an error	Spread of `null` is safe, but direct access is not	Check for `null` or spread it
Overrides not applied	File path does not match the override pattern	Verify the path passed to `resolveConfig`

Real-World Examples

1. Basic resolve

const options = await prettier.resolveConfig(filePath);

2. Resolve and format

const opts = await prettier.resolveConfig(filePath);
await prettier.format(source, { ...opts, filepath: filePath });

3. Explicit config path

await prettier.resolveConfig(filePath, { config: "./custom/.prettierrc" });

4. EditorConfig merge

await prettier.resolveConfig(filePath, { editorconfig: true });

5. Cache bypass

await prettier.resolveConfig(filePath, { useCache: false });

6. Config file discovery

const configPath = await prettier.resolveConfigFile(filePath);

7. Cache clearing

prettier.clearConfigCache();

8. Null handling

const options = await prettier.resolveConfig(filePath);
const formatted = await prettier.format(source, { ...options, filepath });

9. Overrides resolution

// .prettierrc overrides apply based on the file path
const opts = await prettier.resolveConfig("src/app.test.js");

10. Search from cwd

const opts = await prettier.resolveConfig(process.cwd());

Visual

The Resolution Flow

┌──────────────────────────────────────────────────────────────┐
│  WHAT resolveConfig() DOES                                    │
│                                                              │
│  filePath: "src/app.test.js"                                 │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ Search upward from  │  src/ → project/ → root            │
│  │ the file's directory│                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                │
│  ┌─────────────────────┐                                    │
│  │ Find .prettierrc    │  First match wins                 │
│  │ in project/         │                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                │
│  ┌─────────────────────┐                                    │
│  │ Apply overrides     │  Match "*.test.js"                 │
│  │ for the file path   │  → semi: false                     │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                │
│  ┌─────────────────────┐                                    │
│  │ Merge EditorConfig  │  If editorconfig: true             │
│  │ (if enabled)        │  .prettierrc wins on conflict      │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                │
│  ┌─────────────────────┐                                    │
│  │ Return options      │  Or null if nothing found          │
│  │ object              │                                    │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Overrides Behavior

┌──────────────────────────────────────────────────────────────┐
│  ONE CONFIG, DIFFERENT OPTIONS                                │
│                                                              │
│  .prettierrc:                                                │
│  ┌──────────────────────────────────────────────┐           │
│  │ { "semi": true,                              │           │
│  │   "overrides": [                             │           │
│  │     { "files": "*.test.js",                  │           │
│  │       "options": { "semi": false } }         │           │
│  │   ] }                                        │           │
│  └──────────────────────────────────────────────┘           │
│                                                              │
│  resolveConfig("src/app.js")                                │
│  → { semi: true }                                           │
│                                                              │
│  resolveConfig("src/app.test.js")                           │
│  → { semi: false }                                          │
│                                                              │
│  The file path determines which override applies.           │
└──────────────────────────────────────────────────────────────┘

The Search Direction

┌──────────────────────────────────────────────────────────────┐
│  UPWARD ONLY                                                  │
│                                                              │
│  /project/                                                   │
│  ├── .prettierrc       ← found if no nearer config          │
│  └── src/                                                    │
│      ├── .prettierrc   ← found first for src/app.js         │
│      └── app.js                                              │
│                                                              │
│  resolveConfig("src/app.js")                                 │
│         │                                                    │
│         ▼                                                    │
│  Starts at src/                                              │
│  Finds src/.prettierrc                                       │
│  Stops. Does not check project/.prettierrc.                  │
│                                                              │
│  The search does not go downward or sideways.               │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
Function	`prettier.resolveConfig(fileUrlOrPath, options)`
Return	`Promise<object \| null>`
Search start	The file’s directory
Search direction	Upward to the filesystem root
Explicit config	`options.config` bypasses search
EditorConfig	`options.editorconfig: true`
Cache bypass	`options.useCache: false`
Related	`resolveConfigFile()`, `clearConfigCache()`

Key takeaways:

resolveConfig() is the discovery mechanism. It searches upward from the file’s directory, finds the first configuration file, applies overrides that match the file path, and optionally merges EditorConfig properties. It does not read the file’s contents; it only resolves the options .
The return value is a Promise that resolves to an object or null. Spreading null into an options object is safe and contributes no properties. The format() and check() functions use the resolved options, not the configuration file directly .
The search is upward-only and stops at the first match. A configuration in a nested directory overrides a configuration in a parent directory. The options.config parameter bypasses the search entirely and points to a specific file .
Overrides are applied based on the file path. The same configuration file can produce different options for different files. The path passed to resolveConfig() determines which override matches .
The cache is a performance optimization with a staleness risk. The default caching is correct for short-lived processes. A long-running process that watches for configuration changes must bypass the cache or clear it with clearConfigCache() .

Remember: resolveConfig() is the bridge between the file on disk and the options object that format() expects. It encapsulates the search, the parsing, the override matching, and the EditorConfig merge. The function does not format anything; it only answers the question “what options apply to this file?” The answer is a Promise, and the caller must await it. The search is upward-only, the first match wins, and the null result is a valid answer that means “use the defaults.”

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!

Why resolveConfig exists separately from format