B컷전문 | 개발과 인생의 이야기

JHipster로 자동 생성된 React 프론트엔드 프로젝트의 디렉토리 구조와 커스터마이징 방법을 실무 사례 중심으로 정리합니다. 페이지 추가, 상태 관리, 라우팅 확장, CSS 커스터마이징까지 포함합니다.

---

JHipster에서 React는 어떤 역할을 하는가?

JHipster는 Full Stack 개발을 지향합니다.
프론트엔드에서는 최신 React + Redux + TypeScript 기반 구조를 제공하여, 별도의 초기 설정 없이 바로 운영 가능한 수준의 UI를 자동 생성합니다.

기본 제공 기능:

• 로그인, 회원가입, 패스워드 초기화 화면
• Swagger 연동 API 테스트 화면
• 관리(Admin) 페이지
• Entity CRUD 화면 자동 생성

그러나 모든 프로젝트는 커스터마이징이 반드시 필요합니다.

이번 글에서는 실전에서 React 프론트엔드를 어떻게 수정하고, 재설계할 수 있는지 상세하게 안내합니다.

---

React 프로젝트 기본 구조 이해

생성된 React 소스는 src/main/webapp/app 폴더에 위치합니다.

app/
├── account/            # 로그인, 회원가입, 패스워드 초기화
├── admin/              # 관리 기능 (유저, 로그 등)
├── entities/           # Entity 기반 자동 생성 화면
├── shared/             # 공통 컴포넌트, 유틸, 아이콘 등
├── modules/            # 별도 기능 모듈화 영역 (권장)
├── app.tsx             # Root 컴포넌트 (Router 포함)
└── config/             # 환경변수, API URL 등 설정

---

커스터마이징 핵심 포인트

1. 신규 페이지 추가

모든 페이지는 app/modules 또는 app/custom-pages 아래 생성하는 것을 추천합니다.

// app/modules/customPage/CustomPage.tsx
const CustomPage = () => (
  <div>
    <h2>나만의 커스텀 페이지</h2>
  </div>
);

export default CustomPage;

라우팅 추가 (app/routes.tsx):

import CustomPage from 'app/modules/customPage/CustomPage';

<Route path="/custom" element={<CustomPage />} />

---

2. 기존 Entity 화면 수정

자동 생성된 Entity 화면 (예: Book)

app/entities/book/
├── book.tsx               # 목록
├── book-update.tsx        # 수정 폼
├── book-detail.tsx        # 상세 페이지
├── book.reducer.ts        # Redux Slice

실무 팁:

• book-update.tsx: Formik을 이용한 입력 검증 추가 가능
• book.tsx: Custom Table 스타일 적용 → Material UI, Ant Design으로 교체 가능

---

3. Redux 상태 관리 구조

JHipster는 Redux Toolkit 기반으로 상태 관리를 구성합니다.

// 예시: Book 엔티티
export const getEntities = createAsyncThunk(
  'book/fetch_entity_list',
  async () => await axios.get<Book[]>(apiUrl)
);

실제 Redux Store 구성 (app/config/store.ts):

const store = configureStore({
  reducer: {
    authentication,
    applicationProfile,
    administration,
    book, // 신규 Entity reducer
  },
});

실전 팁:
JHipster 구조에 새로운 Domain을 추가할 때, Redux Slice 파일을 작성하고 Store에 연결하면 됩니다.

---

4. CSS, Theme 커스터마이징

기본 테마는 Bootstrap + Reactstrap으로 설정되어 있습니다.
src/main/webapp/content/scss/custom.scss 에서 글로벌 CSS를 수정할 수 있습니다.

$primary: #0d6efd;
$secondary: #6c757d;
$font-family-base: 'Noto Sans KR', sans-serif;

body {
  background-color: #f8f9fa;
}

Material UI, Ant Design, Tailwind CSS와 같이 팀 선호 라이브러리로 교체도 가능합니다.
단, 기존 스타일과 충돌하지 않게 레이어드 방식을 권장합니다.

---

5. i18n 다국어 지원

JHipster는 기본적으로 다국어 국제화(i18n)를 지원합니다.

import { Translate } from 'react-jhipster';

<Translate contentKey="home.title">기본 제목</Translate>

언어 파일 위치:
src/main/webapp/i18n/{언어코드}/global.json

{
  "home": {
    "title": "환영합니다"
  }
}

실무 팁:
국내 서비스라면 ko, en, zh 정도를 우선 구성하고, 비즈니스 확장 시 국가별 json 파일을 추가하는 전략을 추천합니다.

---

실무 커스터마이징 사례

한 제조업 ERP 프로젝트에서는 다음과 같은 방식으로 커스터마이징을 진행했습니다.

항목 개선 내용

기본 Table 컴포넌트 → Material Table 교체	컬럼 드래그, 정렬, 필터링 개선
Bootstrap → Tailwind CSS	개발 생산성 및 디자인 자유도 향상
Entity CRUD → Wizard Form UX	고객 정보 입력 시 단계별 Form UX 제공
Redux Toolkit → Zustand 전환	상태 관리 성능 개선

이런 방식으로 기본 JHipster 구조를 유지하면서도 실제 서비스 수준의 커스터마이징을 성공적으로 적용했습니다.

---

마치며 – JHipster 프론트엔드는 유연하다

JHipster의 React 프로젝트는
**"시작용 템플릿 + 커스터마이징을 위한 기반 구조"**를 모두 제공합니다.

코드 생성기에 의존하지 않고 원하는 방식으로 점진적으로 개선할 수 있어,
스타트업 MVP부터 엔터프라이즈 제품까지 스케일업이 매우 용이합니다.

이번 글에서 배운 방법을 토대로, 이제는 자신만의 Domain 기반 화면을 자유롭게 추가하고, 스타일을 팀 표준에 맞게 바꿀 수 있습니다.

---

다음 화 예고

JHipster 시리즈 6화 - JHipster 프로젝트 구조와 코드 흐름 분석하기

프로젝트가 커지면 필연적으로 코드 구조의 이해가 중요합니다.
백엔드(Spring Boot)와 프론트엔드(React)의 디렉토리 구조, 코드 연결 방식, API Layer까지 상세하게 분석합니다.