Sheeshable Excel

A powerful and flexible Excel export helper library built with ExcelJS and file-saver. Create beautifully formatted Excel documents with logos, custom styling, and advanced features - all with a simple, chainable API.

Features

✨ Easy to Use: Simple, chainable API for quick Excel generation
🖼️ Logo Support: Add logos from S3 URLs, base64 data, or local files
🎨 Custom Styling: Full control over fonts, colors, borders, and alignment
📊 Auto-sizing: Intelligent column width and row height adjustment
🔒 Type Safe: Built with TypeScript-friendly patterns
🌐 Browser Compatible: Works seamlessly in modern browsers
⚡ Performance: Optimized for large datasets
🔧 Flexible: Support for multiple worksheets and page layouts

Installation

npm install sheeshable-excel

Or with yarn:

yarn add sheeshable-excel

Quick Start

import ExcelHelper from 'sheeshable-excel';

const excel = new ExcelHelper();

// Create a simple Excel file
await excel.createWorkbook('My Report')
  .addHeaderRow(['Name', 'Email', 'Status', 'Score'])
  .addDataRows([
    ['John Doe', '[email protected]', 'Active', 95],
    ['Jane Smith', '[email protected]', 'Inactive', 87],
    ['Bob Johnson', '[email protected]', 'Active', 92]
  ])
  .autoFitColumns()
  .exportToFile('user-report');

API Reference

Constructor

const excel = new ExcelHelper();

Core Methods

createWorkbook(sheetName, pageSetup)

Initialize a new workbook and worksheet.

excel.createWorkbook('Sales Report', {
  orientation: 'landscape',
  paperSize: 9, // A4
  fitToPage: true
});

addWorksheet(sheetName, pageSetup)

Add a new worksheet to the existing workbook.

excel.addWorksheet('Summary', {
  orientation: 'portrait'
});

Logo Methods

addLogo(s3Url, options)

Add a logo from an S3 URL or any public image URL.

await excel.addLogo('https://example.com/logo.png', {
  width: 100,
  height: 65,
  col: 0,
  row: 0,
  offsetX: 10,
  offsetY: 5
});

addLogoFromData(imageData, extension, options)

Add a logo from base64 data or buffer.

const base64Image = 'data:image/png;base64,iVBORw0KGgo...';
excel.addLogoFromData(base64Image, 'png', {
  width: 120,
  height: 80
});

testS3Access(s3Url)

Test if an S3 URL is accessible before using it.

const isAccessible = await excel.testS3Access('https://example.com/logo.png');
if (isAccessible) {
  await excel.addLogo(s3Url);
}

Content Methods

addDocumentTitle(title, columnCount, titleStyles)

Add a document title that spans across columns.

excel.addDocumentTitle('Annual Sales Report 2024', 5, {
  font: { size: 18, bold: true, color: { argb: '2F5496' } },
  fill: { fgColor: { argb: 'E7F3FF' } }
});

addHeaderRow(headers, headerStyles)

Add a styled header row.

excel.addHeaderRow(['Product', 'Q1', 'Q2', 'Q3', 'Q4', 'Total'], {
  font: { bold: true, color: { argb: 'FFFFFF' } },
  fill: { fgColor: { argb: '4472C4' } }
});

addDataRows(dataRows, dataStyles, heightOptions)

Add data rows with automatic styling and height adjustment.

excel.addDataRows([
  ['Product A', 1000, 1200, 1100, 1300, 4600],
  ['Product B', 800, 900, 950, 1000, 3650]
], {
  font: { size: 10 },
  alignment: { horizontal: 'center' }
}, {
  minHeight: 25,
  autoHeight: true
});

Formatting Methods

autoFitColumns(options)

Automatically adjust column widths.

excel.autoFitColumns({
  minWidth: 10,
  maxWidth: 50,
  padding: 2
});

setColumnWidths(columnWidths)

Set specific column widths.

excel.setColumnWidths({
  0: 20,  // Column A
  1: 15,  // Column B
  2: 30   // Column C
});

applyNumberFormat(columnIndex, format)

Apply number formatting to a column.

excel.applyNumberFormat(3, '$#,##0.00'); // Currency format
excel.applyNumberFormat(4, '0.00%');     // Percentage format

freezePanes(row, column)

Freeze panes for better data viewing.

excel.freezePanes(1, 2); // Freeze first row and first 2 columns

applyBorders(borderStyle)

Apply borders to all cells.

excel.applyBorders({
  top: { style: 'thin', color: { argb: '000000' } },
  left: { style: 'thin', color: { argb: '000000' } },
  bottom: { style: 'thin', color: { argb: '000000' } },
  right: { style: 'thin', color: { argb: '000000' } }
});

Export Methods

exportToFile(filename, addTimestamp)

Export the workbook as an Excel file.

await excel.exportToFile('sales-report', true); // Adds timestamp

getBuffer()

Get the workbook as a buffer for API usage.

const buffer = await excel.getBuffer();
// Send buffer via API or save server-side

Advanced Examples

Complete Report with Logo and Styling

import ExcelHelper from 'sheeshable-excel';

const excel = new ExcelHelper();

try {
  await excel.createWorkbook('Quarterly Report', {
      orientation: 'landscape'
    })
    .addLogo('https://yourcompany.com/logo.png', {
      width: 120,
      height: 60
    })
    .addDocumentTitle('Q4 2024 Sales Report', 6, {
      font: { size: 16, bold: true, color: { argb: '2F5496' } }
    })
    .addHeaderRow([
      'Region', 'Q1 Sales', 'Q2 Sales', 'Q3 Sales', 'Q4 Sales', 'Total'
    ])
    .addDataRows([
      ['North', 125000, 132000, 128000, 140000, 525000],
      ['South', 98000, 105000, 110000, 115000, 428000],
      ['East', 110000, 118000, 125000, 130000, 483000],
      ['West', 135000, 142000, 138000, 145000, 560000]
    ])
    .applyNumberFormat(1, '$#,##0') // Currency for sales columns
    .applyNumberFormat(2, '$#,##0')
    .applyNumberFormat(3, '$#,##0')
    .applyNumberFormat(4, '$#,##0')
    .applyNumberFormat(5, '$#,##0')
    .autoFitColumns({ minWidth: 12, maxWidth: 20 })
    .freezePanes(3, 1) // Freeze headers
    .exportToFile('quarterly-report');
    
  console.log('Report exported successfully!');
} catch (error) {
  console.error('Export failed:', error);
}

Multiple Worksheets

const excel = new ExcelHelper();

// First worksheet
await excel.createWorkbook('Summary')
  .addHeaderRow(['Category', 'Total'])
  .addDataRows([
    ['Sales', 1000000],
    ['Marketing', 250000],
    ['Operations', 180000]
  ]);

// Add second worksheet
excel.addWorksheet('Detailed Sales')
  .addHeaderRow(['Date', 'Product', 'Amount'])
  .addDataRows([
    ['2024-01-15', 'Product A', 5000],
    ['2024-01-16', 'Product B', 3200]
  ]);

await excel.exportToFile('multi-sheet-report');

Error Handling with Logo

const excel = new ExcelHelper();
const logoUrl = 'https://example.com/logo.png';

// Test logo accessibility first
const logoAccessible = await excel.testS3Access(logoUrl);

await excel.createWorkbook('Report')
  // Only add logo if accessible
  if (logoAccessible) {
    await excel.addLogo(logoUrl);
  }
  
excel.addDocumentTitle('Report Title', 4)
  .addHeaderRow(['Col1', 'Col2', 'Col3', 'Col4'])
  .addDataRows([['Data1', 'Data2', 'Data3', 'Data4']])
  .exportToFile('safe-report');

Browser Compatibility

This library is designed for modern browsers and supports:

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Dependencies

• exceljs: Excel file generation
• file-saver: File download in browsers
• axios: HTTP requests for logo fetching

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © [Joseph Cerbito]

Changelog

v1.0.12

• Enhanced logo support with S3 URL encoding
• Improved error handling for network requests
• Better browser compatibility
• Added comprehensive styling options

v1.0.0

• Initial release
• Basic Excel export functionality
• Logo support
• Custom styling capabilities

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Made with ❤️ by [Joseph Cerbito]