Class TomlFile

constructor

• new TomlFile(path: string, content: JsonMap): TomlFile

  Parameters

  • path: string
  • content: JsonMap

  Returns TomlFile

content

Readonlypath

patch

• patch(changes: { [key: string]: unknown }): Promise<void>

  Surgically patch values in the TOML file, preserving comments and formatting.

  Accepts a nested object whose leaf values are set in the TOML. Intermediate tables are created automatically. Setting a leaf to undefined removes it (use remove() for a clearer API when deleting keys).

  Parameters

  • changes: { [key: string]: unknown }

  Returns Promise<void>

  Example

  await file.patch({build: {dev_store_url: 'my-store.myshopify.com'}})
  await file.patch({application_url: 'https://example.com', auth: {redirect_urls: ['...']}})
  Copy

remove

• remove(keyPath: string): Promise<void>

  Remove a key from the TOML file by dotted path, preserving comments and formatting.

  Parameters

  • keyPath: string

    Dotted key path to remove (e.g. 'build.include_config_on_deploy').

  Returns Promise<void>

  Example

  await file.remove('build.include_config_on_deploy')
  Copy

replace

• replace(content: JsonMap): Promise<void>

  Replace the entire file content. The file is fully re-serialized — comments and formatting are NOT preserved.

  Parameters

  • content: JsonMap

    The new content to write.

  Returns Promise<void>

  Example

  await file.replace({client_id: 'abc', name: 'My App'})
  Copy

transformRaw

• transformRaw(transform: (raw: string) => string): Promise<void>

  Transform the raw TOML string on disk. Reads the file, applies the transform function to the raw text, writes back, and re-parses to keep content in sync.

  Use this for text-level operations that can't be expressed as structured edits — e.g. Injecting comments or positional insertion of keys in arrays-of-tables. Subsequent patch() calls will preserve any comments added this way.

  Parameters

  • transform: (raw: string) => string

    A function that receives the raw TOML string and returns the modified string.

  Returns Promise<void>

  Example

  await file.transformRaw((raw) => `# Header comment\n${raw}`)
  Copy

Staticread

• read(path: string): Promise<TomlFile>

  Read and parse a TOML file from disk. Throws if the file doesn't exist or contains invalid TOML. Parse errors are wrapped in TomlParseError with the file path for context.

  Parameters

  • path: string

    Absolute path to the TOML file.

  Returns Promise<TomlFile>

  A TomlFile instance with parsed content.