[xlsx 라이브러리] 리액트에서 Excel 파일 읽고, 수정하고, 다운로드하기

xlsx 

웹 애플리케이션에서 사용자가 직접 엑셀 파일을 업로드하고, 그 내용을 읽어온 뒤 수정하거나 다시 다운로드할 수 있다면 정말 유용합니다. 특히 보고서 처리, 데이터 검증, 간단한 데이터 편집 UI 등에 적합하죠. 라이브러리로는 가장 널리 쓰이는 xlsx를 사용합니다.

이 글에서는 Node.js 없이, 순수 React에서 엑셀 파일을 읽고, 수정하고, 다시 엑셀이나 CSV로 다운로드하는 과정을 소개합니다.

 

---

1.  xlsx 라이브러리란?

xlsx는 JavaScript에서 엑셀 파일을 읽고 쓰기 위해 만들어진 라이브러리입니다.
브라우저, Node.js 환경 모두에서 사용할 수 있고, .xlsx, .xls, .csv 등 다양한 포맷을 지원합니다.

공식 명칭은 "SheetJS"이며, xlsx는 그 중 핵심 모듈입니다.

주요 기능

기능	설명
엑셀 파일 읽기	.xlsx, .xls, .csv 등 다양한 포맷 파싱
JSON 변환	시트 내용을 JavaScript 객체(JSON)로 변환
엑셀 생성	JSON 데이터를 엑셀 시트로 변환하여 새 파일 생성
다운로드	브라우저에서 직접 엑셀 파일 다운로드 트리거 가능
시트 변환	시트 ↔ JSON, 시트 ↔ CSV 등 다양한 변환 지원

 

---

2.  xlsx 라이브러리가 지원하는 파일 형식

확장자	설명	지원 여부
.xlsx	Excel Open XML 형식 (가장 많이 쓰이는 현대 엑셀 형식)	✅ 완벽 지원
.xls	구형 Excel 바이너리 형식	✅ 지원
.csv	Comma-Separated Values, 텍스트 기반 표 형식	✅ 지원
.tsv	Tab-Separated Values	✅ 지원
.ods	LibreOffice/OpenOffice 형식	제한적 지원 (비공식적)
.xlsm	매크로 포함 Excel 파일	일부 지원 (매크로는 무시됨)

React에서 다룰 수 있는 주요 포맷 - .xlsx, .xls, .csv

.xlsx & .xls

• XLSX.read(fileBuffer, { type: "array" | "binary" })로 처리
• workbook.Sheets, XLSX.utils.sheet_to_json() 사용
• 여러 시트 처리 가능

.csv

• CSV도 Excel처럼 읽을 수 있음 (단일 시트로 간주됨)
• XLSX.read(csvText, { type: "string" }) 또는 XLSX.read(arrayBuffer, { type: "array" })
• 시트 이름은 workbook.SheetNames[0] 하나만 존재

// CSV 문자열을 파싱할 때
const workbook = XLSX.read(csvString, { type: "string" });
const json = XLSX.utils.sheet_to_json(workbook.Sheets[workbook.SheetNames[0]]);

파일 확장자에 따른 처리 방식 예시 (React)

const handleFile = (file) => {
  const reader = new FileReader();
  const isCSV = file.name.endsWith(".csv");

  reader.onload = (e) => {
    const result = e.target.result;
    const workbook = XLSX.read(result, {
      type: isCSV ? "string" : "binary",
    });
    const sheetName = workbook.SheetNames[0];
    const sheet = workbook.Sheets[sheetName];
    const data = XLSX.utils.sheet_to_json(sheet);
    console.log("📦 파싱된 데이터:", data);
  };

  if (isCSV) {
    reader.readAsText(file); // CSV는 텍스트
  } else {
    reader.readAsBinaryString(file); // XLSX, XLS는 바이너리
  }
};

 

---

3.  필요한 라이브러리 설치

npm install xlsx

 

또는

yarn add xlsx

 

---

4.  엑셀 파일 읽기

a.  파일 업로드 후 데이터 파싱

import React, { useState } from "react";
import * as XLSX from "xlsx";

function ExcelReader() {
  const [excelData, setExcelData] = useState([]);

  const handleFileUpload = (e) => {
    const file = e.target.files[0];
    const reader = new FileReader();

    reader.onload = (evt) => {
      const binaryStr = evt.target.result;
      const workbook = XLSX.read(binaryStr, { type: "binary" });
      const sheetName = workbook.SheetNames[0];
      const sheet = workbook.Sheets[sheetName];
      const jsonData = XLSX.utils.sheet_to_json(sheet);
      setExcelData(jsonData);
    };

    reader.readAsBinaryString(file);
  };

  return (
    <div>
      <h2>엑셀 파일 업로드</h2>
      <input type="file" accept=".xlsx, .xls" onChange={handleFileUpload} />
      <pre>{JSON.stringify(excelData, null, 2)}</pre>
    </div>
  );
}

export default ExcelReader;

b.  프로젝트 내의 파일 파싱

import React, { useEffect, useState } from "react";
import * as XLSX from "xlsx";

function ExcelFromStaticFile() {
  const [excelData, setExcelData] = useState([]);

  useEffect(() => {
    fetch("/data.xlsx")
      .then(res => res.arrayBuffer())
      .then(arrayBuffer => {
        const workbook = XLSX.read(arrayBuffer, { type: "array" });
        const sheetName = workbook.SheetNames[0];
        const sheet = workbook.Sheets[sheetName];
        const jsonData = XLSX.utils.sheet_to_json(sheet);
        setExcelData(jsonData);
      })
      .catch(err => {
        console.error("엑셀 파일 로드 실패:", err);
      });
  }, []);

  return (
    <div>
      <h2>프로젝트 폴더의 엑셀 파일 불러오기</h2>
      <pre>{JSON.stringify(excelData, null, 2)}</pre>
    </div>
  );
}

export default ExcelFromStaticFile;

보너스 - xlsx가 처리 가능한 fetch 타입 정리

리소스 타입	XLSX.read() 옵션
FileReader.readAsBinaryString()	type: "binary"
fetch().arrayBuffer()	type: "array"
fetch().text()	type: "string" (CSV에만 적절)

 

---

5.  데이터 수정 - 예시로 "나이 +1" 버튼 만들기

<button onClick={() => {
  const updated = excelData.map(row => ({
    ...row,
    Age: row.Age + 1
  }));
  setExcelData(updated);
}}>모든 나이 +1</button>

 

---

6.  엑셀 파일 다운로드

const handleDownload = () => {
  const worksheet = XLSX.utils.json_to_sheet(excelData);
  const workbook = XLSX.utils.book_new();
  XLSX.utils.book_append_sheet(workbook, worksheet, "Sheet1");

  // 엑셀 파일 다운로드
  XLSX.writeFile(workbook, "updated_data.xlsx");
};

 

버튼 추가

<button onClick={handleDownload}>엑셀로 다운로드</button>

 

---

7.  전체 코드 요약

import React, { useState } from "react";
import * as XLSX from "xlsx";

function ExcelApp() {
  const [excelData, setExcelData] = useState([]);

  const handleFileUpload = (e) => {
    const file = e.target.files[0];
    const reader = new FileReader();

    reader.onload = (evt) => {
      const binaryStr = evt.target.result;
      const workbook = XLSX.read(binaryStr, { type: "binary" });
      const sheetName = workbook.SheetNames[0];
      const sheet = workbook.Sheets[sheetName];
      const jsonData = XLSX.utils.sheet_to_json(sheet);
      setExcelData(jsonData);
    };

    reader.readAsBinaryString(file);
  };

  const handleAgeIncrement = () => {
    const updated = excelData.map(row => ({
      ...row,
      Age: row.Age + 1
    }));
    setExcelData(updated);
  };

  const handleDownload = () => {
    const worksheet = XLSX.utils.json_to_sheet(excelData);
    const workbook = XLSX.utils.book_new();
    XLSX.utils.book_append_sheet(workbook, worksheet, "Sheet1");
    XLSX.writeFile(workbook, "updated_data.xlsx");
  };

  return (
    <div>
      <h2>React 엑셀 처리</h2>
      <input type="file" accept=".xlsx, .xls" onChange={handleFileUpload} />
      <button onClick={handleAgeIncrement}>모든 나이 +1</button>
      <button onClick={handleDownload}>엑셀로 다운로드</button>
      <pre>{JSON.stringify(excelData, null, 2)}</pre>
    </div>
  );
}

export default ExcelApp;

 

---

8.  마무리

• xlsx 라이브러리를 사용하면 React에서도 Node 없이 엑셀 파일을 읽고 쓰는 기능 구현이 가능합니다.
• FileReader와 XLSX.read()를 이용해 파일 업로드 시 데이터를 파싱할 수 있습니다.
• 수정된 데이터를 XLSX.utils.json_to_sheet() + XLSX.writeFile()로 다운로드할 수 있습니다.

함께 보면 좋은 자료

외부 사이트 :

• npm - xlsx
• GitHub - SheetJS
• MDN Web Docs - FileReader

 

---