Add CSV BOM option

Author: Recoveredd

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this package are documented here.
 
+## 0.1.1 - 2026-05-12
+
+- Added an optional `bom` export setting for spreadsheet apps that need a UTF-8 byte order mark.
+
 ## 0.1.0 - 2026-05-12
 
 - Initial release with JSON records to CSV conversion.

README.md

@@ -213,6 +213,8 @@ value
 '=SUM(A1:A2)
 ```
 
+Use `bom: true` when a spreadsheet app needs the UTF-8 byte order mark to detect accented characters correctly.
+
 ## Options
 
 ```ts
@@ -228,6 +230,7 @@ interface JsonToCsvOptions<TRecord> {
   arrayMode?: 'json' | 'join' | 'empty';
   arraySeparator?: string;
   escapeFormulae?: boolean | string;
+  bom?: boolean;
   dateFormatter?: (date: Date) => string;
 }
 ```
@@ -245,6 +248,7 @@ interface JsonToCsvOptions<TRecord> {
 | `arrayMode` | `'json'` | format arrays as JSON, joined text or empty |
 | `arraySeparator` | `', '` | separator used by `arrayMode: 'join'` |
 | `escapeFormulae` | `false` | prefix spreadsheet-like formulas |
+| `bom` | `false` | prefix the output with a UTF-8 BOM for spreadsheet apps |
 | `dateFormatter` | ISO string | format `Date` values |
 
 ## Arrays, dates and null values

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "json-csv-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Convert JSON records to clean CSV with TypeScript-first options.",
   "type": "module",
   "sideEffects": false,

package.json

@@ -55,7 +55,8 @@ export function jsonToCsv<TRecord extends object>(
     lines.push(formatRow(row, resolved));
   }
 
-  return lines.join(resolved.newline);
+  const csv = lines.join(resolved.newline);
+  return resolved.bom ? `\uFEFF${csv}` : csv;
 }
 
 export const toCsv = jsonToCsv;
@@ -107,6 +108,7 @@ function resolveOptions<TRecord extends object>(
     arrayMode,
     arraySeparator,
     escapeFormulae,
+    bom: options.bom ?? false,
     dateFormatter: options.dateFormatter ?? ((date) => date.toISOString())
   };
 }

src/index.ts

@@ -115,6 +115,13 @@ export interface JsonToCsvOptions<TRecord extends object = CsvRecord> {
    */
   escapeFormulae?: boolean | string;
 
+  /**
+   * Prefix the CSV with a UTF-8 byte order mark for spreadsheet apps.
+   *
+   * @default false
+   */
+  bom?: boolean;
+
   /**
    * Format Date instances.
    *
@@ -135,6 +142,7 @@ export interface ResolvedJsonToCsvOptions<TRecord extends object = CsvRecord> {
   arrayMode: ArrayValueMode;
   arraySeparator: string;
   escapeFormulae: false | string;
+  bom: boolean;
   dateFormatter: (date: Date) => string;
 }
 

src/types.ts

@@ -138,6 +138,10 @@ describe('json-csv-kit', () => {
     ).toBe('name;role\r\nAda;Engineer');
   });
 
+  test('can prefix CSV output with a UTF-8 BOM', () => {
+    expect(jsonToCsv([{ name: 'Ada' }], { bom: true })).toBe('\uFEFFname\nAda');
+  });
+
   test('supports null values and dates', () => {
     expect(
       jsonToCsv(