00:00:00TanStack이 자바스크립트 세상을 고치려는 여정의 일환으로 또 하나의 새로운 패키지를 출시했습니다.
00:00:03이번에는 단축키(hotkeys) 문제를 해결하려 하는데요. 만약 이게 너무 간단해 보여서
00:00:07요즘 같은 시대에 AI가 대신 짜줄 수 있는 수준이라고 생각하신다면 다시 생각해보세요. TanStack Hotkeys는
00:00:11다양한 키보드 레이아웃, 여러 운영체제처럼 AI가 흔히 놓치는 예외 상황들을 처리하며
00:00:16충돌하는 단축키와 스코프 등 수많은 문제를 해결해 줍니다. 게다가 단축키 시퀀스나
00:00:20단축키 녹화 같은 기능도 제공하면서 타입 안정성을 갖췄고 프레임워크에도 구애받지 않습니다.
00:00:26믿으셔도 좋습니다. 단축키가 필요하다면 그냥 이 패키지를 쓰거나 AI 에이전트에게 시키세요.
00:00:30TanStack 제품인 만큼 개발자 경험(DX)은 보장되어 있으니까요. 그럼 이제
00:00:35실제로 어떻게 작동하는지 살펴봅시다.
00:00:41사용법이 꽤 간단하기 때문에 바로 코드로 들어가 보겠습니다.
00:00:45저는 리액트 애플리케이션에서 작업 중이라 TanStack React Hotkeys 패키지를 사용하고 있지만,
00:00:49현재 바닐라 자바스크립트 패키지도 준비되어 있고 다른 프레임워크용도 곧 출시될 예정입니다.
00:00:52지금은 알파 버전이라 여기저기 버그가 있을 수 있지만, 제 사용 사례에서는 이미 모든 문제가 해결되었습니다.
00:00:56가장 기본적인 사용 사례인 `useHotkey` 훅부터 시작해 보죠.
00:01:01여기 아래를 보시면 패키지에서 훅을 임포트해 왔고, 우리가 해야 할 일은
00:01:05단축키가 무엇인지 정의하고 해당 키를 눌렀을 때 실행될 함수를 작성하는 것뿐입니다.
00:01:09제 경우에는 단축키를 눌렀을 때 커맨드 팔레트가 열리도록 설정했습니다.
00:01:13아주 흔한 예시죠.
00:01:17아래쪽에 토스트 메시지도 넣어두어서 제가 어떤 키를 눌렀고 무엇이 실행됐는지 바로 확인하실 수 있습니다.
00:01:20보시다시피 이 훅은 굉장히 단순하고 제 역할을 충실히 해냅니다.
00:01:24하지만 TanStack의 진가는 대개 개발자 경험과 타입 안정성에서 드러나는데,
00:01:28여기서도 마찬가지입니다. 우선 단축키 정의부터 시작해 보죠.
00:01:32이 패키지 내에서 단축키를 사용하는 모든 곳은 타입 안전하게 보호되는데, 정말 놀랍습니다.
00:01:37입력 가능한 모든 키와 그 조합을 알고 있습니다.
00:01:41예를 들어, 이것을 macOS에서 'Command + S'에 해당하는 'meta + s'로 바꾼다고 해봅시다.
00:01:46애플리케이션에 새로운 저장 단축키를 설정하는 상황이죠. 보시다시피 유효한 조합임을 인식하고,
00:01:50만약 오타를 내면 타입 에러를 띄워 유효하지 않은 단축키라고 알려줍니다.
00:01:54단축키 정의에 관한 또 다른 멋진 점은, 현재 저는 'meta + k'로 설정해 뒀는데
00:01:58이건 macOS에서 'Command + K'입니다. 저는 Mac을 쓰고 있어서 잘 작동하지만,
00:02:02이렇게 하면 윈도우나 다른 플랫폼에서는 작동하지 않게 됩니다.
00:02:06해당 플랫폼들에는 'meta' 키가 없기 때문이죠. 그래서 대신에
00:02:11'meta' 키를 'mod'(modifier) 키로 바꿔줄 수 있습니다.
00:02:15그러면 macOS에서는 자동으로 'Command'가 되고, 다른 모든 플랫폼에서는
00:02:19'Control'로 설정됩니다. 즉시 크로스 플랫폼 단축키를 갖게 되는 거죠.
00:02:24마지막으로 단축키 정의 방식에 대해 한 가지만 더 짚고 넘어가자면,
00:02:27문자열 방식이 마음에 들지 않는다면 객체 정의 방식을 사용할 수도 있습니다.
00:02:31방금 본 'Command + K' 또는 'Control + K'와 똑같은 키 바인딩입니다.
00:02:35보시다시피 조합 키가 아닌 일반 키를 지정하고, 수정 키(modifier)를 true로 설정하기만 하면 됩니다.
00:02:38원하는 다른 수정 키들도 같은 방식으로 설정할 수 있고요. 단축키 정의 방식은 여기까지 하고,
00:02:42다음으로 훅의 인자 중 단축키를 눌렀을 때 실제로 실행되는 함수를 살펴보겠습니다.
00:02:46이 부분은 당연히 매우 간단하며, 안에 무엇이든 원하는 대로 작성할 수 있습니다.
00:02:50필요하다면 로우(raw) 키보드 이벤트에 직접 접근할 수도 있고,
00:02:54컨텍스트(context)도 활용할 수 있습니다. 이 경우 컨텍스트를 통해
00:02:58눌린 단축키를 문자열로 가져오거나, 방금 본 객체 형태의 정의로
00:03:02파싱된 단축키 데이터를 얻을 수도 있습니다. 그리고 `useHotkey` 훅의 마지막으로,
00:03:05보여드리고 싶은 기능이 아주 많지만, 세 번째 인자로는
00:03:09단축키 작동 방식을 제어하는 몇 가지 옵션을 사용할 수 있습니다.
00:03:13대부분은 따로 설명이 필요 없을 정도로 직관적이며, 지금은 모두 기본값으로 설정해 뒀습니다.
00:03:17단축키 활성화 여부를 프로그래밍적으로 제어하는 `enabled`나
00:03:21키를 누를 때(keydown) 혹은 뗄 때(keyup) 중 언제 트리거할지 결정하는 `eventType` 등이 있죠.
00:03:25`requireReset`은 현재 false로 되어 있는데, 'Command + K'를 꾹 누르고 있으면
00:03:29단축키가 계속 반복해서 트리거되는 것을 볼 수 있습니다. 하지만 이것을 true로 설정하면
00:03:33다시 트리거되기 위해 키에서 손을 뗐다가 다시 눌러야 합니다.
00:03:37지금 꾹 누르고 있는데 이번에는 한 번만 실행되는 걸 보실 수 있죠. 다음은 `ignoreInputs`입니다.
00:03:41이것은 입력창(input) 안에 있을 때 'Command + K'를 누르면
00:03:45보시는 것처럼 완전히 무시되어 단축키가 실행되지 않게 합니다. 물론 입력창 안에서도
00:03:49단축키가 작동하게 하려면 이 값을 false로 바꾸면 됩니다. 마지막으로 살펴볼 옵션은
00:03:53`target`입니다. 이 옵션을 사용하면 단축키에 스코프(범위)를 설정할 수 있습니다.
00:03:57기본적으로는 전체 문서(document)로 설정되어 있어서,
00:04:00페이지 어디서든 'Command + K'를 누르면 커맨드 팔레트가 열립니다.
00:04:04하지만 이것을 특정 엘리먼트나 리액트 ref로 바꿀 수 있습니다.
00:04:09예를 들어 'badgeRef'로 바꾸면, 페이지의 다른 곳을 클릭하고 'Command + K'를 눌러도
00:04:13반응이 없습니다. 하지만 여기 아래에 있는 커맨드 K 엘리먼트(배지)에 포커스를 맞추면
00:04:17실행되는 걸 볼 수 있죠. 이제 스코프가 지정된 단축키가 생겼습니다.
00:04:21벌써 제가 왜 이 패키지를 좋아하는지 아시겠죠? 디테일에 대한 집착과
00:04:25훌륭한 개발자 경험, 그리고 완벽한 타입 안정성까지 갖췄으니까요. 아직 훅 하나만 보여드렸는데,
00:04:30다른 것들도 살펴봅시다. 다음은 `useHotkeySequences` 훅입니다.
00:04:34여러 개의 키를 순서대로 누르는 시퀀스를 지원하여 Vim 스타일의 네비게이션 등을 구현할 수 있게 해줍니다.
00:04:38이것도 매우 직관적입니다. `useHotkey` 훅과 비슷하게
00:04:43어떤 키 시퀀스를 사용할지 정의하고, 시퀀스가 완료되었을 때 실행할 함수를 작성하면 됩니다.
00:04:47여기도 옵션이 있는데, `timeout`은 각 키를 누르는 사이의 간격을 의미하며
00:04:51이 시간 내에 다음 키를 눌러야 하나의 시퀀스로 등록됩니다.
00:04:54현재 'gg'를 입력하면 목록의 맨 위로 이동하도록 설정해 뒀습니다.
00:04:59실제로 가서 'gg'를 누르면 보시는 대로 작동합니다. 또한
00:05:04아래쪽에 'sub'라고 치면 맨 아래로 이동하게 해뒀는데, 우연히도
00:05:09글자가 '구독(subscribe)'이네요. 꼭 하셔야 할 일이죠. 다음은 더 간단한 훅들입니다.
00:05:12첫 번째는 `useKeyHold` 훅입니다. 추적하고 싶은 키를 지정하기만 하면
00:05:16해당 키가 현재 눌려 있는지 여부를 불리언(boolean) 값으로 반환합니다.
00:05:20여기 몇 가지 키를 모니터링하고 있는데, 제가 'Shift'와 'Alt'를 꾹 누르면
00:05:24그 불리언 값에 따라 페이지 상태가 변하는 걸 볼 수 있습니다. 또한
00:05:28아래쪽에는 현재 제 키보드에서 눌려 있는 키들의 목록이 나오고 있죠.
00:05:32이건 두 번째 훅인 `useHeldKeys` 덕분인데, 단순히 현재 눌린 키들을
00:05:36배열로 반환해 줍니다. 다시 'sub'를 누르면 배열에 나타나는 걸 볼 수 있습니다.
00:05:40유용한 유틸리티 함수로 넘어가기 전에 보여드릴 마지막 훅은
00:05:43`useHotkeyRecorder` 훅입니다. 이 훅을 사용하면 키보드 단축키를
00:05:47사용자가 직접 커스텀할 수 있는 UI를 아주 쉽게 만들 수 있습니다. 정말 멋진 헬퍼 훅이죠.
00:05:52사용법은 아주 간단합니다. `useHotkeyRecorder` 훅을 호출하면
00:05:56현재 녹화 중인지 여부, 녹화된 단축키 값, 녹화 시작 및 취소 함수 등을 얻을 수 있습니다.
00:06:00그리고 훅의 옵션 내에서
00:06:05단축키가 성공적으로 녹화되었을 때 어떤 처리를 할지 등록할 수 있습니다.
00:06:09제 경우에는 커맨드 팔레트 단축키를 사용자가 결정한 값으로 설정하도록 했습니다.
00:06:14이 모든 걸 버튼에 연결하면 이런 식의 UI를 만들 수 있습니다. 현재는 'Command + K'가
00:06:17팔레트를 열지만, '녹화(record)'를 누르면 훅이 작동하면서 제 키보드 입력을 기다립니다.
00:06:21여기서 'Command + Backspace'를 누르면, 이게 팔레트를 여는 새로운 단축키가 됩니다.
00:06:26실제로는 이 값을 데이터베이스에 저장해서 사용자 설정으로 유지하겠죠.
00:06:29정말 유용한 헬퍼 훅입니다. 지금까지 본 다른 훅들과 마찬가지로
00:06:33사용이 매우 간편하며, 훌륭한 기본 설정들도 제공합니다.
00:06:37예를 들어 macOS에서 'Command' 키를 사용해 단축키를 녹화하면
00:06:42나중에 윈도우나 리눅스 사용자가 접속했을 때 자동으로 'Control' 키로 변환해 줍니다.
00:06:46이제 훅 외에 이 패키지에 대해 보여드리고 싶은 게 몇 가지 더 있습니다.
00:06:49첫 번째는 포맷팅을 도와주는 함수들입니다.
00:06:53`formatForDisplay`라는 함수가 있는데, TanStack Hotkeys에서 제공하며
00:06:57'mod + backspace' 같은 값을 넣으면 사용자의 플랫폼에 맞춰
00:07:02자동으로 아이콘으로 변환해 줍니다. 제 화면엔 'Command Backspace'로 보이지만
00:07:06윈도우라면 'Control Backspace'로 표시될 겁니다. 또한 `formatWithLabels`
00:07:10함수도 있는데, 방금 전과 거의 똑같은 역할을 하지만
00:07:14수정 키를 아이콘 대신 올바른 텍스트 레이블로 변환해 줍니다. 제 경우에는
00:07:18'Command Backspace'가 되겠지만 윈도우에서는 'Control Backspace'가 되겠죠.
00:07:22마지막으로 제가 TanStack을 사랑하는 이유 중 하나인 데브툴(Devtools)입니다. 이 패키지도 예외는 아니죠.
00:07:27데브툴을 열면 페이지에 등록된 모든 단축키와
00:07:30시퀀스를 확인할 수 있습니다. 각 상태와 얼마나 많이 트리거되었는지도 볼 수 있고,
00:07:33키를 누를 때 실행되는지 뗄 때 실행되는지도 알 수 있습니다. 또한 문서 전체를 감시 중인지
00:07:37아니면 특정 엘리먼트를 감시 중인지도 보여줍니다. 안을 들여다보면
00:07:41설정된 옵션들을 자세히 확인할 수 있고 수동으로 트리거해 볼 수도 있습니다.
00:07:45게다가 상단에서는 현재 페이지에서 눌려 있는 키들을 확인할 수 있습니다.
00:07:49특정 키를 설정하고 싶은데 그 키의 정확한 값을 모른다면 그냥 여기 와서
00:07:52키를 눌러보세요. 바로 정확한 값을 알 수 있습니다. 자꾸 같은 말을 반복하는 것 같지만,
00:07:56TanStack은 정말 개발자 경험을 잘 이해하고 있습니다. AI 코딩의 시대에도
00:08:00여전히 이런 퀄리티를 누릴 수 있다는 게 기쁩니다. 단축키 구현이 필요하다면
00:08:05이 패키지를 꼭 한번 확인해 보시고, 어떻게 생각하시는지
00:08:08댓글로 알려주세요. 구독도 잊지 마시고요. 그럼 다음 영상에서 뵙겠습니다!