lucide-icons/lucide 딥다이브
— SVG 파일 1,756개가 소스이자 전부인 아이콘 세트

1한 줄 정체

Lucide는 아이콘 라이브러리다. 우리가 앱에서 매일 보는 돋보기(검색), 톱니바퀴(설정), 하트(좋아요) 같은 작은 선 그림들을 일관된 스타일로 통일해서 모아 놓고, 개발자가 코드 한 줄로 가져다 쓸 수 있게 포장해 놓은 프로젝트다. AI도 서버도 아니고, 순수하게 "그림 파일 + 그걸 각 프로그래밍 언어 코드로 바꿔주는 자동화 도구"다.

실제로 저장소를 열어 보면 핵심 폴더는 icons/ 하나뿐이다. 그 안에 아이콘 이름별로 activity.svg(그림 자체)와 activity.json(이름·태그·카테고리 같은 부가 정보)이 쌍으로 1,756벌 들어 있다. 이 폴더가 유일한 원본(source of truth)이고, packages/ 아래 있는 React용·Vue용·Svelte용 패키지들은 전부 이 원본을 재료 삼아 빌드 시점에 자동 생성된 결과물이다.

2왜 지금 뜨는가

Lucide 자체는 신생 기술이 아니라 2020년에 시작된 포크(fork, 원본 프로젝트를 복제해 독자적으로 이어가는 것)다. 그런데도 여전히, 그리고 갈수록 더 많이 쓰이는 데는 이유가 있다.

① 원조(Feather Icons)가 멈췄을 때, 커뮤니티가 "그대로 이어받았다"

Lucide의 LICENSE 파일에는 지금도 airplay, calendar, search 등 특정 아이콘 목록이 "Feather 프로젝트에서 유래했다"고 명시돼 있고, 그 아이콘들에는 Feather 원작자 Cole Bemis의 MIT 라이선스가 병기돼 있다. 즉 Lucide는 "Feather를 베낀 것"이 아니라 "멈춰버린 원조를 커뮤니티가 공식적으로 이어받아 계속 키운 것"이다. 이런 배경 덕에 초기부터 많은 기존 Feather 사용자가 자연스럽게 옮겨왔다.

② shadcn/ui 같은 인기 UI 킷의 "기본 아이콘"으로 채택됨

최근 몇 년 사이 폭발적으로 쓰이는 React 컴포넌트 모음 shadcn/ui를 비롯해, 여러 스타터 템플릿·보일러플레이트가 Lucide를 기본 아이콘 세트로 지정했다. 한 인기 도구가 채택하면, 그 도구를 쓰는 수많은 프로젝트가 자동으로 Lucide도 함께 설치하게 된다 — "기본값의 힘"이다.

③ 프레임워크를 가리지 않는 "전방위 패키지" 전략

packages/ 폴더를 보면 React·Vue·Svelte·Angular·Solid·Preact·React Native·Astro까지 사실상 프론트엔드 생태계 전체를 커버한다. 어떤 프레임워크로 시작하든 "Lucide는 있다"는 확신을 주기 때문에, 팀이 기술 스택을 바꿔도 아이콘 세트는 그대로 유지할 수 있다.

3무엇을 해결하나

아이콘 라이브러리가 없다면 개발자는 매번 아이콘을 PNG나 SVG로 하나하나 내려받아 프로젝트에 끼워 넣어야 한다. 색을 바꾸려면 SVG 코드를 열어 직접 수정해야 하고, 크기를 바꾸면 화질이 깨지거나 레이아웃이 어긋나기도 한다. 게다가 팀 안에서 어떤 사람은 동그란 스타일, 어떤 사람은 각진 스타일 아이콘을 섞어 쓰면 화면이 중구난방으로 보인다.

Lucide가 실제로 해결하는 문제는 세 가지로 요약된다.

• 디자인 일관성 — 모든 아이콘이 같은 캔버스 크기(24×24)·같은 선 굵기(2px)·같은 둥근 끝처리 규칙을 따르도록 강제해, 1,756개를 섞어 써도 "한 사람이 그린 것"처럼 보인다.
• 프레임워크별 반복 작업 제거 — 디자이너·기여자는 SVG 원본 하나만 관리하면 되고, React 컴포넌트 코드나 Vue 컴포넌트 코드를 손으로 짤 필요가 없다(다음 섹션에서 그 파이프라인을 그대로 추적한다).
• 런타임에서 색·크기·굵기를 자유롭게 조정 — currentColor라는 CSS 기법 덕분에, 이미지 파일을 바꾸지 않고도 코드에서 color="red", size={32}처럼 속성만 바꿔 즉시 다른 느낌의 아이콘을 낼 수 있다.

4전체 구조

저장소는 pnpm 워크스페이스 모노레포(packages/*, tools/*, docs)로 구성돼 있다. 전체 그림을 셋으로 나누면 이렇다.

각 패키지 폴더(packages/lucide-react/src/icons/ 등) 안의 .ts/.svelte/.vue 파일들은 사람이 직접 짜서 커밋한 코드가 아니다. package.json의 build:icons 스크립트가 매 빌드마다 icons/*.svg를 읽어 새로 찍어낸다. 즉 "코드가 있는 폴더"처럼 보이지만 실제로는 생성된 산출물이 커밋에 섞여 있을 뿐이다 — 이 구조를 모르면 "왜 아이콘 파일 코드가 다 똑같이 생겼지?"에서 헤맬 수 있다.

5핵심 설계·동작 원리

이 레포에서 가장 배울 만한 부분은 "디자인 원본 하나에서 코드를 자동 생성하는 파이프라인"이다. 실제 소스 파일을 순서대로 따라가 보자.

① 원본 확인 — icons/activity.svg + activity.json

아이콘 하나는 SVG 파일과 JSON 메타데이터 파일이 이름이 같은 쌍으로 존재한다. 실제 icons/activity.svg를 열어보면 다음과 같다.

<svg
  xmlns="http://www.w3.org/2000/svg"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
>
  <path d="M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36..." />
</svg>

짝을 이루는 activity.json에는 그림 정보가 아니라 이름·기여자·태그·카테고리만 들어 있다. 그림(형태)과 의미(메타데이터)를 파일 두 장으로 확실히 분리해 둔 것이다.

② 빌드 엔진 — tools/build-icons가 SVG를 "데이터"로 바꾼다

각 패키지의 package.json에는 build:icons라는 스크립트가 있고, 실제로 lucide-react 패키지는 다음처럼 정의돼 있다(직접 확인한 원문).

"build:icons": "build-icons --output=./src
  --templateSrc=./scripts/exportTemplate.mts
  --renderUniqueKey --withAliases --withDynamicImports
  --separateAliasesFile --iconFileExtension=.ts
  --exportFileName=index.ts"

이 명령이 실행하는 tools/build-icons/cli.ts의 핵심 흐름은 이렇다. 함수 이름까지 그대로 인용한다.

1. readSvgDirectory(ICONS_DIR) — icons/ 폴더의 모든 SVG 파일 목록을 읽는다.
2. renderIconsObject(svgFiles, ICONS_DIR, renderUniqueKey) — 각 SVG의 <path>·<circle> 같은 태그를 파싱해, "[태그이름, 속성객체]" 배열(IconNode)이라는 프레임워크 중립적인 데이터 구조로 바꾼다. 이 시점부터는 더 이상 텍스트 SVG가 아니라 자바스크립트 객체다.
3. templateSrc로 지정된 패키지별 템플릿 함수(예: packages/lucide-react/scripts/exportTemplate.mts)를 불러온다. 이 템플릿이 "이 데이터를 어떤 프레임워크 문법으로 찍어낼지"를 결정하는 핵심이다.
4. generateIconFiles(...) — 아이콘 1,756개 각각에 대해 템플릿 함수를 호출해 src/icons/activity.ts 같은 실제 소스 파일을 써낸다.
5. withAliases·withDynamicImports 옵션이 켜져 있으면 별칭(구명·별명) 파일과 동적 import용 맵(dynamicIconImports)도 함께 생성한다.
6. generateExportsFile(...) — 마지막으로 1,756개 아이콘을 전부 다시 내보내는 index.ts(배럴 파일)를 만든다.

③ React 패키지의 실제 "틀" — exportTemplate.mts

실제로 packages/lucide-react/scripts/exportTemplate.mts는 다음과 같이 각 아이콘 파일을 위한 문자열 템플릿을 반환한다(원문 그대로).

export default defineExportTemplate(async({
  componentName, iconName, children, getSvg, deprecated, deprecationReason,
}) => {
  const svgContents = await getSvg();
  const svgBase64 = base64SVG(svgContents);
  return `
import createLucideIcon from '../createLucideIcon';
import { IconNode } from '../types';

export const __iconNode: IconNode = ${JSON.stringify(children)}

const ${componentName} = createLucideIcon('${iconName}', __iconNode);
export default ${componentName};
`;
});

즉 실제로 생성되는 src/icons/activity.ts 파일은 사람이 짠 게 아니라, 위 템플릿 함수가 children(파싱된 SVG 데이터)을 JSON.stringify로 그대로 박아 넣은 결과물이다. 그리고 그 파일이 부르는 createLucideIcon('activity', __iconNode)(packages/lucide-react/src/createLucideIcon.ts)가 진짜 React 컴포넌트를 만든다 — forwardRef로 감싸고, lucide-{kebab-case 이름} 클래스를 자동으로 붙인다.

렌더링 최종 단계인 Icon.ts에서는 size·color·strokeWidth 같은 props를 받아 진짜 <svg> 엘리먼트를 만든다. 흥미로운 디테일 하나 — absoluteStrokeWidth 옵션을 켜면 calculatedStrokeWidth = strokeWidth * 24 / size 공식으로 아이콘을 키워도 선 굵기 비율이 뭉개지지 않게 자동 보정한다.

④ 프레임워크마다 "틀"만 다르고 재료·조립 로직은 같다

이 표에서 보듯, "SVG를 파싱해 IconNode 데이터로 만드는 공통 엔진"은 tools/build-icons 하나뿐이고, 각 패키지는 --templateSrc 인자로 자기 문법에 맞는 출력 함수만 갈아 끼운다. 새 프레임워크를 지원하고 싶다면 이론적으로 템플릿 함수 하나만 새로 짜면 된다 — 실제로 @lucide/icons는 "컴포넌트가 아니라 데이터"를 내보내, 커뮤니티가 자체적으로 지원되지 않는 프레임워크용 통합을 만들 수 있게 열어둔 것이라고 공식 문서가 밝힌다.

⑤ 디자인 규칙은 "코드"가 아니라 "사람 + 도구"로 지켜진다

많은 사람이 "24×24 그리드, 선 굵기 2px, 둥근 끝처리" 같은 규칙이 자동 CI(지속적 통합) 검사로 딱딱 걸러질 거라고 짐작하지만, 실제 코드를 보면 다르다. docs/contribute/icon-design-guide.md에 14개 조항으로 규칙이 문서화돼 있고, 실제 자동화는 scripts/optimizeSvgs.mts(processSvg 함수)가 SVGO로 SVG를 최적화하고 기본 속성(width/height/stroke-width 등)을 강제로 덮어씌우는 것, 그리고 lint:icons(prettier로 SVG 포맷 검사)와 lint:json:icons(JSON 스키마 검증)뿐이다.

6기술 스택·의존성

주목할 점은 패키지별로 프레임워크 런타임이 peerDependencies(직접 설치하지 않고 사용자 프로젝트의 버전을 빌려 쓰는 의존성)로만 선언돼 있다는 것이다. 예를 들어 lucide-react는 react: "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"처럼 폭넓은 버전대를 허용해, React 16을 쓰는 오래된 프로젝트에서도 최신 아이콘을 그대로 쓸 수 있게 열어둔다.

7설치·요구사항

일반 사용자(그냥 아이콘을 쓰고 싶은 개발자)는 이 레포를 클론할 필요조차 없다. 원하는 프레임워크 패키지 하나만 설치하면 된다.

# React 프로젝트
npm install lucide-react

# Vue 3 프로젝트 (최신 패키지명)
npm install @lucide/vue

# 프레임워크 없이 순수 SVG/폰트만
npm install lucide-static

8실제 사용 흐름

가장 흔한 사용 사례인 React를 기준으로 실제 사용 흐름을 그대로 따라가 본다.

npm install lucide-react

import { Camera } from 'lucide-react';

function App() {
  return <Camera />;
}

<Camera size={48} color="red" strokeWidth={1} />

import { DynamicIcon } from 'lucide-react';

// name이 서버에서 온 문자열이라 미리 import를 정해둘 수 없을 때
<DynamicIcon name="camera" />

9함정·오해 방지

함정 ① "그냥 배럴 파일에서 import하면 트리셰이킹이 알아서 될 것" — 항상 그렇지는 않다

import { Camera } from 'lucide-react'처럼 배럴 파일(barrel file, 여러 모듈을 한곳에서 다시 내보내는 진입점 파일)에서 가져오면, 번들러가 트리셰이킹(안 쓰는 코드 제거)을 잘 해줄 거라 기대하기 쉽다. 하지만 공식 문서(docs/guide/react-native/advanced/optimizations.md)가 명시적으로 경고한다.

이 문제가 React Native 전용은 아니다. 오래된 번들러 설정이나 트리셰이킹이 약한 환경이라면 다른 프레임워크 패키지에서도 같은 증상이 날 수 있다 — "import 몇 줄 썼는데 번들이 갑자기 커졌다"는 리포트가 나오면 이 지점을 먼저 의심해야 한다.

함정 ② 튜토리얼에서 본 패키지명이 이미 옛날 이름일 수 있다

함정 ③ 저장소 안 package.json의 버전 번호를 믿지 말 것

이 저장소를 클론해서 packages/lucide-react/package.json을 열어보면 버전이 0.0.1로 적혀 있다(실제로 확인한 값). 하지만 npm에 배포된 실제 버전은 이 글 작성 시점 기준 1.27.0이다. 왜 이런 차이가 날까 — .github/workflows/release.yml을 보면, 버전은 소스 코드에 미리 적어두는 게 아니라 "릴리스 시 git 태그(v1.27.0 등)를 기준으로 pnpm version ... --no-git-tag-version 명령이 그 순간 덮어쓰는 값"이다. 즉 진짜 버전의 근원(source of truth)은 저장소 파일이 아니라 릴리스 워크플로가 참조하는 git 태그다.

함정 ④ "코드가 있는 폴더"처럼 보이지만 커밋에는 생성된 파일이 섞여 있다

packages/lucide-react/src/icons/*.ts 같은 파일들을 GitHub에서 보면 사람이 짠 코드처럼 보이지만, 5번 섹션에서 봤듯 이건 빌드 스크립트의 산출물이다. 이 폴더의 코드를 직접 고쳐도 다음 빌드에서 덮어써진다 — 아이콘 자체를 고치고 싶다면 src/icons/가 아니라 icons/*.svg 원본을 고쳐야 한다.

함정 ⑤ Feather와 100% 호환된다고 생각하기 쉽지만, 이름이 바뀐 아이콘이 있다

Feather에서 넘어온 아이콘들은 Lucide의 이름 규칙(예: "용도가 아니라 형태로 이름 짓기" — save 대신 floppy-disk)을 적용받아 일부는 이름이 바뀌었다. Feather 시절 코드를 그대로 복사해 붙이면 import가 실패할 수 있다.

10대안 비교

11정리 · 누가 쓰면 좋은가

Lucide는 화려한 신기술이 아니라, "원본 하나 → 여러 결과물 자동 생성"이라는 아주 오래되고 검증된 소프트웨어 공학 패턴을 아이콘이라는 소재로 아주 깔끔하게 구현한 사례다. 핵심을 세 문장으로 압축하면:

• 이 저장소의 진짜 원본은 icons/*.svg 1,756장뿐이고, 나머지 14개 패키지는 전부 빌드 시점 생성물이다.
• 디자인 일관성은 문서화된 규칙 + 사람의 리뷰 + 부분적 자동화(속성 강제·포맷 검사)로 지켜지며, 완전 자동 픽셀 검증은 아니다.
• 실사용에서 가장 흔한 실수는 배럴 import로 인한 번들 크기 폭증과 폐기된 옛 패키지명 사용이다.