설치 및 환경 설정

Flitter를 처음 시작하는 분들을 위한 단계별 설치 가이드입니다. 이 튜토리얼을 완료하면 React 프로젝트에서 Flitter를 사용할 수 있게 됩니다.

🎯 학습 목표

이 튜토리얼을 완료하면 다음을 할 수 있습니다:

Node.js와 npm 환경이 올바르게 설정되어 있는지 확인
새로운 React 프로젝트 생성
Flitter 패키지 설치
첫 번째 Flitter 위젯 렌더링
개발 서버 실행 및 결과 확인

📋 사전 요구사항

Node.js 18 이상 - Node.js 공식 사이트에서 다운로드
npm, yarn, 또는 pnpm - Node.js와 함께 자동 설치됨
기본적인 React 지식 - JSX와 컴포넌트 개념 이해

🚀 1단계: 환경 확인

먼저 개발 환경이 올바르게 설정되어 있는지 확인해보겠습니다.

터미널을 열고 다음 명령어를 실행하세요:

# Node.js 버전 확인 (18 이상이어야 함)
node --version

# npm 버전 확인
npm --version

출력 예시:

v20.10.0
10.2.3

⚠️ Node.js 버전이 18 미만이라면?
Node.js 공식 사이트에서 최신 LTS 버전을 설치해주세요.

🏗️ 2단계: 새 프로젝트 생성

Vite를 사용해서 새로운 React 프로젝트를 생성합니다:

# 새 프로젝트 생성
npm create vite@latest my-flitter-app -- --template react

# 프로젝트 폴더로 이동
cd my-flitter-app

# 기본 의존성 설치
npm install

📦 3단계: Flitter 패키지 설치

이제 Flitter 관련 패키지를 설치합니다:

# Flitter 핵심 패키지와 React 통합 패키지 설치
npm install @meursyphus/flitter @meursyphus/flitter-react

설치되는 패키지:

@meursyphus/flitter: Flitter 핵심 라이브러리
@meursyphus/flitter-react: React 통합을 위한 컴포넌트

🔧 4단계: 첫 번째 Flitter 위젯 만들기

이제 src/App.jsx 파일을 수정해서 첫 번째 Flitter 위젯을 만들어보겠습니다.

TODO: 코드 완성하기

아래 코드에서 TODO 부분을 완성해보세요:

import React from 'react';
// TODO: Widget 컴포넌트를 import 하세요
// TODO: Container와 Text 위젯을 import 하세요

function App() {
  // TODO: Container 위젯을 만들어보세요
  // 힌트: 파란색 배경(#e3f2fd)과 20px 여백을 가진 컨테이너
  // 힌트: "🎉 Flitter 설치 완료!" 텍스트를 포함
  const widget = null;

  return (
    <div style={{ padding: '20px' }}>
      <h1>Flitter 설치 성공!</h1>
      {/* TODO: Widget 컴포넌트로 위젯을 렌더링하세요 */}
      {/* 힌트: canvas 렌더러 사용, 300x100 크기 */}
    </div>
  );
}

export default App;

완성된 코드

import React from 'react';
import { Widget } from '@meursyphus/flitter-react';
import { Container, Text } from '@meursyphus/flitter';

function App() {
  const widget = Container({
    color: '#e3f2fd',
    padding: { all: 20 },
    child: Text('🎉 Flitter 설치 완료!')
  });

  return (
    <div style={{ padding: '20px' }}>
      <h1>Flitter 설치 성공!</h1>
      <Widget 
        widget={widget}
        renderer="canvas"
        style={{ 
          width: '300px', 
          height: '100px',
          border: '1px solid #ddd',
          borderRadius: '8px'
        }}
      />
    </div>
  );
}

export default App;

🏃 5단계: 개발 서버 실행

이제 개발 서버를 실행해서 결과를 확인해보겠습니다:

npm run dev

브라우저에서 http://localhost:5173을 열면 다음을 볼 수 있습니다:

“Flitter 설치 성공!” 제목
파란색 배경에 ”🎉 Flitter 설치 완료!” 텍스트가 있는 박스

🎯 예상 결과

설치가 성공적으로 완료되면:

개발 서버가 정상 실행됨: 터미널에 “Local: http://localhost:5173” 표시
Flitter 위젯이 렌더링됨: 파란색 배경의 박스가 화면에 표시
콘솔 에러 없음: 브라우저 개발자 도구에서 에러 메시지 없음

🔧 연습 문제

기본 설치를 완료했다면, 다음을 시도해보세요:

연습 1: 색상 변경하기

Container의 color 속성을 다른 색상으로 변경해보세요:

'#ffebee' (연한 빨강)
'#f3e5f5' (연한 보라)
'#e8f5e8' (연한 초록)

연습 2: 텍스트 변경하기

Text 위젯의 내용을 자신만의 메시지로 변경해보세요.

연습 3: 크기 조정하기

Widget 컴포넌트의 style 속성에서 width와 height를 다른 값으로 변경해보세요.

🚨 흔한 실수와 해결법

문제 1: 모듈을 찾을 수 없다는 에러

Error: Cannot resolve module '@meursyphus/flitter'

해결법: 패키지가 올바르게 설치되었는지 확인하세요:

npm install @meursyphus/flitter @meursyphus/flitter-react

문제 2: 빈 화면이 나타남

원인: 위젯이 올바르게 생성되지 않았거나 Widget 컴포넌트에 전달되지 않음

해결법:

widget 변수가 null이 아닌지 확인
Widget 컴포넌트에 widget prop이 전달되었는지 확인

문제 3: Node.js 버전 에러

Error: Node.js version 16.x is not supported

해결법: Node.js 18 이상으로 업데이트하세요.

🚀 다음 단계

설치가 완료되었다면, 다음 튜토리얼에서 더 복잡한 위젯을 만들어보겠습니다:

다음: 첫 번째 Flitter 앱 - 더 복잡한 위젯 구조 익히기
관련 문서: 위젯 기초 - 위젯 개념 자세히 알아보기

📚 더 자세한 정보가 필요하다면?
모든 프레임워크별 설치 방법과 고급 설정은 설치 문서를 참고하세요.