excel-zod

Type-safe Excel reading and writing with Zod schemas.

Define your spreadsheet structure with Zod, then read, write, and validate Excel files with full TypeScript type safety. No more manual column mapping, no more runtime surprises.

Why excel-zod?

• Schema-first - Define your Excel structure once, get types and validation for free
• Full type inference - Parsed data is fully typed based on your Zod schema
• Detailed errors - Row number, column name, expected vs actual values
• Template generation - Create blank Excel files with headers, validation, and formatting
• Zero config - Headers auto-match to schema keys (case-insensitive)
• Battle-tested foundation - Built on ExcelJS and Zod

Installation

npm install excel-zod zod

Zod is a peer dependency. You need to install it separately.

Quick Start

import { z } from 'zod';
import { createExcelSchema } from 'excel-zod';

// 1. Define your schema
const UserSchema = createExcelSchema(z.object({
  name: z.string(),
  email: z.string().email(),
  age: z.number().int().positive(),
  joinDate: z.date(),
  active: z.boolean(),
}));

// 2. Read Excel into typed, validated objects
const { data, errors } = await UserSchema.parse('users.xlsx');
// data: { name: string, email: string, age: number, joinDate: Date, active: boolean }[]

if (errors.length > 0) {
  console.error('Validation errors:');
  for (const err of errors) {
    console.error(`  Row ${err.row}, Column "${err.column}": ${err.message}`);
  }
}

// 3. Write typed data back to Excel
await UserSchema.write(data, 'output.xlsx');

// 4. Generate a blank template
await UserSchema.generateTemplate('template.xlsx');

API Reference

createExcelSchema(zodSchema)

Creates an ExcelSchema instance from a Zod object schema.

const schema = createExcelSchema(z.object({ ... }));

schema.parse(filePath, options?)

Read and validate an Excel file. Returns { data, errors, totalRows }.

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | sheet | string \| number | 1 | Sheet name or 1-based index | | headerRow | number | 1 | Row containing headers | | startRow | number | headerRow + 1 | First data row | | columns | ColumnMapping[] | auto-detect | Custom column mappings | | stopOnEmpty | boolean | true | Stop on first empty row |

schema.parseStrict(filePath, options?)

Same as parse, but throws ExcelValidationError if any rows fail validation.

schema.write(data, filePath, options?)

Write typed data to an Excel file with headers, formatting, and proper column widths.

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | sheetName | string | "Sheet1" | Worksheet name | | columns | ColumnMapping[] | auto | Custom header names |

schema.generateTemplate(filePath, options?)

Generate a blank Excel template with headers, type hints, data validation, and frozen header row.

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | sheetName | string | "Sheet1" | Worksheet name | | addValidation | boolean | true | Add Excel data validation | | freezeHeader | boolean | true | Freeze the header row |

Column Mapping

By default, excel-zod matches Excel headers to schema keys (case-insensitive). You can customize this:

// Match by custom header names
const { data } = await schema.parse('file.xlsx', {
  columns: [
    { key: 'name', header: 'Full Name' },
    { key: 'email', header: 'Email Address' },
  ],
});

// Match by column index (1-based)
const { data } = await schema.parse('file.xlsx', {
  columns: [
    { key: 'name', index: 1 },
    { key: 'email', index: 3 },
  ],
});

Error Handling

import { ExcelValidationError } from 'excel-zod';

try {
  const data = await schema.parseStrict('users.xlsx');
} catch (err) {
  if (err instanceof ExcelValidationError) {
    console.error(err.format());
    // Row 3, Column "email": Invalid email (got: "not-an-email")
    // Row 5, Column "age": Number must be greater than 0 (got: -1)
  }
}

Supported Types

| Zod Type | Excel Handling | |----------|---------------| | z.string() | Text cells, auto-coerced | | z.number() | Numeric cells, string-to-number coercion | | z.boolean() | Yes/No, true/false, 1/0 | | z.date() | Excel dates, serial numbers, ISO strings | | z.optional() | Allows empty cells | | z.default() | Uses default for empty cells |

Comparison with Alternatives

| Feature | excel-zod | Manual ExcelJS | csv-parse + zod | |---------|-----------|---------------|-----------------| | Type-safe reading | Yes | No | Partial | | Schema validation | Built-in | Manual | Separate step | | Excel write | Yes | Manual setup | No (CSV only) | | Template generation | Yes | Manual | No | | Error messages | Row + column | Manual | Row only | | Date handling | Automatic | Manual | Manual |

Pro Version

Looking for advanced features like multi-sheet schemas, streaming for large files, custom formatters, and pivot table generation? Check out excel-zod Pro (coming soon).

License

MIT