# NextJS에서 SpreadJS 시작하기

## Content

SpreadJS는 Windows, Linux, Mac과 같은 다양한 플랫폼용 웹 애플리케이션을 개발할 수 있는 React 기반 프레임워크인 NextJS를 지원합니다. NextJS는 TypeScript 지원, 하이브리드 정적/서버 렌더링, 경로 사전 가져오기(route pre-fetching), 스마트 번들링 등 프로덕션 환경에 필요한 기능을 제공합니다.
자세한 내용은 [https://nextjs.org/docs/getting-started](https://nextjs.org/docs/getting-started)를 참고하세요.
이 튜토리얼에서는 SpreadJS를 사용하는 Next.js 애플리케이션을 만들어봅니다.

>type=note
> 참고: SpreadJS는 이제 NextJS 16 버전을 지원합니다. Next.js 애플리케이션을 생성하려면 Node.js 20.9 이상이 설치되어 있어야 합니다.

## Next.js 앱 만들기

Next.js 애플리케이션을 만드는 가장 쉬운 방법은 CLI 도구의 `create-next-app` 명령을 사용하는 것입니다.

1. 명령 프롬프트 또는 터미널에서 다음 명령을 실행하여 Next.js TypeScript 프로젝트를 생성합니다.

    ```auto
    npm create-next-app@latest
    ```
2. 프로젝트 이름(예: *nextjs-with-spreadjs*)을 입력합니다.
3. 터미널에 설정 관련 메시지가 표시되면 원하는 옵션을 선택하고 Enter 키를 눌러 확인합니다.
    프로젝트가 설치 및 생성될 때까지 잠시 기다립니다.

    > Next.js 16은 Turbopack을 기본 번들러로 사용합니다. 개발 및 프로덕션 빌드 모두에서 자동으로 활성화되므로 별도로 설정할 필요가 없습니다.
4. 종속성 설치가 완료되면 터미널에서 다음 명령을 입력하여 프로젝트를 시작합니다.

    ```auto
    cd nextjs-with-spreadjs
    npm run dev
    ```
5. 브라우저에서 [http://localhost:3000](http://localhost:3000/) 을 엽니다. 그러면 NextJS 시작 페이지가 표시됩니다.
6. 현재 터미널을 닫고 Visual Studio Code 또는 원하는 IDE에서 *nextjs-with-spreadjs* 폴더를 엽니다.

## SpreadJS 설치

1. SpreadJS 패키지를 설치합니다.

    ```auto
    npm install @mescius/spread-sheets-react
    ```
2. *spreadsheet.tsx*라는 TypeScript 파일을 생성하고 app 폴더에 추가한 뒤 다음 코드를 입력합니다.

    ```auto
    'use client';
    
    import React, { useState } from "react";
    import { SpreadSheets, Worksheet, Column } from "@mescius/spread-sheets-react";
    import * as GC from "@mescius/spread-sheets";
    
    // Optional: Set your SpreadJS license key
    var SpreadJSKey = "your-license-key";
    GC.Spread.Sheets.LicenseKey = SpreadJSKey;
    
    export default function SpreadSheet() {
    
        const [spreadBackColor, setSpreadBackColor] = useState('aliceblue');
        const [sheetName, setSheetName] = useState('Employees');
        const [hostStyle, setHostStyle] = useState({
            width: '100%',
            height: '700px'
        });
        const dataArr = [
            {
                "jobTitleName": "Developer",
                "preferredFullName": "Romin Irani",
                "region": "CA",
                "phoneNumber": "408-1234567"
            },
            {
                "jobTitleName": "Developer",
                "preferredFullName": "Neil Irani",
                "region": "CA",
                "phoneNumber": "408-1111111"
            },
            {
                "jobTitleName": "Program Director",
                "preferredFullName": "Tom Hanks",
                "region": "CA",
                "phoneNumber": "408-2222222"
            }
        ];
        const [data, setData] = useState(dataArr);
        const [columnWidth, setColumnWidth] = useState(200);
        return (
            <SpreadSheets backColor={spreadBackColor} hostStyle={hostStyle}>
                <Worksheet name={sheetName} dataSource={data}>
                    <Column dataField='preferredFullName' width={columnWidth}></Column>
                    <Column dataField='jobTitleName' width={columnWidth}></Column>
                    <Column dataField='phoneNumber' width={columnWidth}></Column>
                    <Column dataField='region' width={columnWidth}></Column>
                </Worksheet>
            </SpreadSheets>);
    }
    ```
3. index 파일 내용을 변경합니다. *app/page.tsx* 파일의 기본 내용을 다음 코드로 교체합니다.

    ```auto
    'use client';
    import dynamic from "next/dynamic";
    
    const SpreadSheet = dynamic(
      () => {
        return import("./spreadsheet");
      },
      { ssr: false }
    );
    
    export default function Home() {
      return (
        <div>
          <h1>
            Next.JS 16 + SpreadJS demo
          </h1>
          <SpreadSheet />
        </div>
      )
    }
    ```

>type=info
> SpreadJS는 브라우저 전용 API(`window`, `document`, Canvas)에 의존하므로 `ssr: false`와 함께 `next/dynamic`을 사용해야 합니다. 따라서 SpreadSheet 컴포넌트에서는 SSR을 비활성화해야 합니다. 또한 `next/dynamic`과 `ssr: false`는 반드시 `'use client'`로 표시된 Client Component 내부에서 사용해야 합니다.

## Next.js 16에서 SpreadJS 가져오기

Next.js 16에서 Turbopack을 사용하는 경우 SpreadJS 코어 패키지는 기본 import 구문으로 가져오는 것을 권장합니다.

```auto
import GC from "@mescius/spread-sheets";
```

다음과 같은 namespace import 방식은 사용하지 않는 것이 좋습니다.

```auto
import * as GC from "@mescius/spread-sheets";
```

일부 Next.js 16 환경에서는 namespace import를 사용할 경우 Pivot 또는 Report와 같은 SpreadJS 추가 기능 패키지가 `GC` 객체를 정상적으로 확장하지 못할 수 있습니다. 그 결과, 해당 추가 기능 패키지가 설치되어 있더라도 `GC.Pivot` 또는 `GC.Report`와 같은 네임스페이스가 정의되지 않은 것처럼 보일 수 있습니다.
기본 import 방식을 사용하면 추가 기능 모듈이 SpreadJS 코어 객체에 기능을 정상적으로 연결할 수 있습니다.

## 스타일 가져오기

app 폴더에 있는 *globals.css* 파일에 다음 줄을 추가하여 애플리케이션에 SpreadJS CSS를 가져옵니다.

```auto
@import '@mescius/spread-sheets/styles/gc.spread.sheets.excel2016colorful.css';
```

## 앱 실행 및 테스트

`npm run dev` 명령을 사용하여 애플리케이션을 실행할 수 있습니다.
기본적으로 프로젝트는 [http://localhost:3000/](http://localhost:3000/) 에서 실행됩니다.