[Spring boot] HTMX + Thymeleaf 조합으로 웹 페이지 개발 시작하기

[Web] HTML 말고 HTMX(HyperText Markup eXtension)

지난 포스트에서 우리는 HTMX라는 HTML 확장 개념에 대해 알아봤습니다. 이를 바탕으로 이번 포스트에서는 Spring과 Spring에서 지원하는 템플릿 엔진인 타임리프(Thymeleaf) 조합으로 간단한 페이지를 만들어보도록 하겠습니다.

 

 

초기 구성

Spring Initializer를 이용하여 먼저 애플리케이션 프로젝트 구성을 해보겠습니다. 사용할 패키지는 아래와 같습니다.

 

• Spring boot 3.2.0
• Spring boot starter web
• Spring boot starter thymeleaf

build.gradle 혹은 pom.xml에서 해당 패키지를 추가한 뒤 아래와 같이 타임리프 기본 설정을 진행합니다.

 

개발한 코드가 잘 적용되었는지 보기 위해 캐시를 비활성화 합니다. 캐시를 활성화 하는 경우 브라우저에서 기존에 서버로 가져온 결과물을 미리 로드하여 보여주므로 바로 보여지지 않는 버그가 발생할 수 있습니다. 

 

그리고 웹 페이지 파일은 모두 resources/templates 폴더에 넣어서 보도록 할 것이며 정적 파일(js, css 파일)은 static 폴더에 넣어서 보는 것으로 설정하겠습니다.

 

이제 templates/index.html 파일을 만들고, 위 코드를 입력해본 다음 스프링 부트 서버를 실행해보겠습니다.

 

위와 같이 It works ! 라는 화면이 보이면 thymeleaf가 포함된 Spring boot 프로젝트가 잘 생성된 것입니다. 이제 다음으로 HTMX를 구성해보겠습니다.

 

 

 

HTMX를 프로젝트에 적용하는 방법 1

HTMX 홈페이지에서 공식적으로 프로젝트에 적용하는 방법은 HTML 파일에 htmx 스크립트 파일을 추가하는 것입니다.

 

script 태그를 이용하여 htmx 스크립트를 추가하면 성공적으로 적용이 완료되었으며 테스트를 위해 샘플 API를 한 개 만들고, 화면에 버튼을 추가하여 버튼을 클릭했을 때, It works ! 화면을 Hello htmx ! 라는 문구로 바꾸어보겠습니다.

 

먼저 화면을 구성해보겠습니다. It works ! 메시지를 DOM으로 감싸고, 그 DOM이 바뀔 수 있도록 구현하기 위해 ID를 지정합니다. 그리고, 바로 하단에 버튼을 만들어 버튼 클릭시 It works ! 메시지가 바뀔 수 있도록 hx-get으로 GET /hello 호출시 outerHTML 함수로 컴포넌트가 바뀌도록 하고 hx-target으로 바꿀 DOM의 ID를 지정해줍니다.

 

다음으로 /hello API를 구현합니다. HTMX는 선언적 구문을 사용하기 때문에 Hello htmx라는 단순 텍스트가 아닌 HTML 코드를 반환해줘야 하며 이 때는 Controller 어노테이션이 아닌 RestController 어노테이션을 사용해야 합니다. 왜냐하면 View를 반환하는 것이 아니고, HTML 코드를 반환해줘야 하기 때문이죠.

 

이제 서버를 실행하면 Click Me 라는 버튼이 만들어지고 이 버튼을 클릭해보면...

 

이렇게 위와 같이 Hello htmx ! 문구로 바뀌는 것을 볼 수 있습니다. 이렇게 HTMX는 Javascript와 같은 명령 구문 없이도 선언적 HTML 코드와 attribute만을 이용하여 쉽게 웹페이지를 개발할 수 있습니다.

 

HTMX 라이브러리를 외부 CDN 등에 미리 저장된 리소스를 불러올 수도 있지만 Spring의 경우는 Maven에서 npm 패키지를 일부 지원해주기 때문에 해당 패키지 저장소에서 직접 받아 HTMX를 프로젝트에 적용하는 방법도 있습니다.

 

 

 

HTMX를 프로젝트에 적용하는 방법 2

1에서는 템플릿 엔진 없이 순수 HTML 파일에서 구현하는 방법을 사용했지만 이번에는 템플릿 엔진인 타임리프(thymeleaf)를 이용하여 Maven에서 원하는 HTMX 버전에 맞춰 자동으로 정적 파일에 적용될 수 있도록 적용해보겠습니다.

 

먼저 앞에서 사용했던 web.resources.static-locations를 기존으로 롤백하고, thymeleaf의 prefix를 templates 하위로 변경합니다. 이제 templates 하위에 있는 html 파일을 순수 HTML 파일이 아닌 템플릿 엔진으로 읽어서 HTML로 변환할 것입니다.

 

그런 다음 위와 같이 webjars htmx와 webjars-locator를 추가해줍니다. webjars는 웹 개발에 필요한 자바스크립트 라이브러리를 jar로 패키징하여 Maven 등의 저장소에 사용할 수 있도록 만든 레포지터리이며 webjars-locator는 정적 경로 지정시 라이브러리 버전을 지정하지 않고, 동적으로 컴파일시 적용해주는 라이브러리입니다.

 

이제 index.html을 템플릿 엔진에 맞게 변환해줍니다. 눈에 띄게 바뀐 것은 기존의 script 태그의 src 속성이 아닌 th:src를 사용했다는 점입니다. 주소형식이 템플릿 엔진에서 지원하는 표현식(expression)을 사용하여야 합니다. 이렇게 하면 HTMX 라이브러리의 버전이 바뀌어도 수시로 index.html 파일에서 변경할 필요가 없게 됩니다.

 

마찬가지로 잘 동작하는 것을 볼 수 있습니다. 이처럼 HTMX는 템플릿 엔진을 이용하지 않고도 일반적인 MVC 개발 방식대로 사용할 수도 있고, 반대로 템플릿 엔진과 함께 HTMX를 사용할 수도 있습니다.

 

 

 

Tailwind CSS 적용해보기

페이지를 만들고 나니 CSS 적용이 여전히 난제입니다. webjars에서 bootstrap 등 다양한 CSS를 지원해주곤 있지만 좀 더 나만의 스타일을 만들어보기 위해 tailwind CSS를 적용해보는 것도 좋습니다.

 

HTMX + Thymeleaf 조합으로 tailwind CSS 조합을 사용하기 위해서는 Node.js를 사용하여 tailwind 디펜던시를 설치하고 진행해야 합니다. 해당 파일 생성을 위해 별도의 프로젝트를 내부에 모듈처럼 구현해보겠습니다.

 

main 하위에 frontend라는 폴더를 만들고, 터미널을 실행합니다.

 

$ npm init

 

위 명령어를 이용하여 초기 Node.js 프로젝트를 생성합니다.

 

{
  "name": "frontend",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Neon K.I.D",
  "license": "MIT"
}

 

그러면 위와 같이 package.json 파일이 만들어지는데, 여기에 우리는 tailwindcss를 디펜던시로 추가할 것입니다.

 

$ yarn add tailwindcss --dev​

 

yarn 혹은 npm 명령어를 이용하여 tailwindcss를 디펜던시로 추가해줍니다. 

 

그러면 위와 같이 devDependencies에 tailwindcss가 추가됩니다. 그리고, scripts 하위에 build 명령어를 추가해줍니다. npm, yarn 등으로 build 명령어를 입력했을 때 최종 CSS 결과물이 Spring MVC의 정적 파일에 저장되도록 하기 위함입니다.

 

$ tailwindcss init

 

tailwindcss init 명령어를 이용하여 tailwind.config.js 파일을 생성합니다. 그런 다음 content에 아래와 같이 코드를 추가해줍니다.

 

그러면 tailwindcss가 적용될 경로가 thymeleaf 템플릿 엔진에 맞춰 구성됩니다.

 

사용할 CSS 컴포넌트를 나열해줍니다.

 

$ yarn build​

 

이제 build 명령어를 이용하면 resources/static/css/main.css 파일이 생성된 것을 볼 수 있습니다.

 

index.html에 템플릿 엔진 표현식을 사용하여 link 태그를 이용해 생성된 CSS를 적용하면 Tailwind CSS도 입맞게 사용할 수 있게 됩니다.

 

이를 Spring boot 전체 프로젝트 빌드시 같이 적용하고 싶다면 아래의 링크를 통해 Gradle에 node 환경을 구성하고, 빌드해 볼 수 있습니다.

 

[Spring boot] Node Gradle을 이용하여 Spring 프로젝트와 Node 프로젝트 붙이기

 

 

 

마치며...

아주 간단하게 타임리프와 HTMX로 프로젝트를 시작할 수 있는 방법에 대해 알아봤습니다. Spring 프로젝트로 진행하고 있다면 어느 정도 백엔드 서버를 만들 수 있는 역량이 되시는 분들일테니 HTMX를 적용하는 방법에 대해서만 간단히 안다면 쉽게 백오피스와 웹페이지를 개발해 볼 수 있을 것입니다.

 

개인적으로 HTMX를 사용해 본 결과 복잡한 SPA를 이용했을 때보다 간단한 애플리케이션을 만드는 데 개발의 시간적 비용을 1.5배 정도 감소시킬 수 있었으며 특히 webpack 등의 빌드 도구 없이 실행할 수 있기 때문에 CI/CD로 검증이나 배포를 하는 데 있어서도 시간 비용이 꽤 단축될 수 있었습니다. 만약, webpack, vite 등의 빌드 도구로 웹 페이지를 빌드하는 데 너무 많은 시간이 소모되고, 게다가 그 애플리케이션이 백오피스 내지 간단한 웹페이지라면 HTMX는 최고의 선택이라고 볼 수 있어 보입니다.