내가 ‘오픈소스’ 프로젝트를 진행하며 배운 것들

“당신에게 직접 커피챗을 요청하는 회사가 있다면 어떤 기분일까요?”

불과 2년 전까지만 해도 저는 서류 탈락과 면접 불합격 통보를 일상처럼 받아들이고 있었습니다. 그렇게 수십 통의 거절 메일을 받으며, 개발자로서 부족하다고 느끼던 시기가 있었죠. 그러나 이제는 구직 활동조차 하지 않았는데도 여러 곳에서 이직 제안을 받는 상황이 되었습니다.

재밌었던 경험 중 하나는 같은 기업의 서로 다른 계열사로부터 각각 연락을 받았을 때입니다. “회사가 커서 채용 과정도 따로 진행하는구나”라는 생각에 신기했죠. 그 당시 이미 직장을 구한 상태였기에 모두 정중히 거절했지만, 그들이 저의 오픈소스 활동을 보고 기술력과 문제 해결 능력을 높이 평가했다는 점을 알 수 있었습니다. 그렇게 오픈소스는 제 커리어를 한 단계 끌어올리는 데 중요한 역할을 해주었죠.

아마 비슷한 고민을 하는 분들이 있을 겁니다. 회사 업무만으로는 뭔가 부족하다는 느낌, 더 성장하고 싶은데 방법을 모르겠다는 생각… 저도 그랬습니다. 회사 프로젝트는 론칭이 미뤄지기도 하고, 정확히 어떤 기여를 했는지 드러내기도 어려웠죠. 한때 사이드 프로젝트도 고민해 봤지만 현실의 벽은 높았습니다. 수익을 내지 못하면 단순한 토이 프로젝트로 치부되기 쉽고, 프론트엔드부터 백엔드, 서버 운영비까지 모든 것을 스스로 감당해야 하는 부담도 컸습니다.

반면 오픈소스는 달랐습니다. 깃허브에 코드를 투명하게 공개하고, 전 세계 개발자들과 협력하며 자연스럽게 기술력을 증명할 수 있었습니다. 무엇보다 수익이나 비용 걱정 없이 온전히 코드에만 집중할 수 있다는 점에서 큰 매력을 느꼈죠. 그래서 최근 ‘NotionPresso’라는 프로젝트를 시작했습니다. 노션 페이지를 개인 블로그나 포트폴리오 페이지로 변환해 주는 오픈소스 도구로, 기존의 ‘oopy’나 ‘super.so’ 같은 서비스의 오픈소스화를 목표로 하고 있습니다. 개발자들이 자신의 노션 페이지를 자유롭게 커스터마이징하며, 블로그를 만들 수 있게 돕는 것이 이 프로젝트의 핵심입니다.

이 글에서는 제가 오픈소스 프로젝트 ‘NotionPresso’를 진행하며 배운 것들을 공유하고자 합니다. 오픈소스 주제를 선정하는 방법부터 구조 설계, 커뮤니티와의 소통, 그리고 결과물을 발전시키는 과정을 담았고, 이 여정을 통해 오픈소스라는 새로운 도전에 대한 작은 동기를 얻을 수 있다면 좋겠습니다.

오픈소스 프로젝트 주제 선정하기

“내가 만든 코드를 공개했으니 이제 오픈소스 개발자네요!”

이런 생각으로 오픈소스를 시작했다가 낭패를 보는 개발자들을 많이 봤습니다. 저도 그중 하나였죠. 코드를 깃허브에 공개하고 무료로 풀어놓는다고 해서 가치를 인정받는 건 아닙니다. 오픈소스는 프로덕트와 다르지 않습니다. 결국 누군가에게 필요해야 의미가 생기고, 이를 위해선 철저한 시장 조사가 필요합니다.

저는 NotionPresso를 시작하기 전, 먼저 기존 노션 관련 도구들을 살펴봤습니다. oopy나 super.so 같은 상용 서비스들이 노션 페이지를 블로그로 변환해 주는 유용한 기능을 제공하며, 많은 인기를 얻고 있었습니다. 동시에 몇 가지 분명한 한계도 보였습니다.

1. 비용의 부담: 많은 사람들이 구독형 서비스 비용에 부담을 느꼈습니다. 특히 개인 개발자나 프리랜서들에게는 무료 혹은 저비용 대안이 필요했죠.
2. 제한된 커스터마이징: 원하는 대로 블로그나 페이지를 꾸밀 수 없다는 점이 큰 제약이었습니다.

기존 오픈소스 라이브러리에서도 기술적인 한계가 보였습니다.

1. 가장 널리 쓰이는 react-notion-x는 노션의 공식 API를 사용하지 않았습니다. 사용자들은 브라우저 개발자 도구에서 API 키값을 직접 찾아 입력해야 했고, 노션이 비공식 API 사용을 막으면 라이브러리가 동작하지 않을 수도 있습니다.
2. 공식 API를 사용하는 react-notion-render는 개발이 중단된 상태였으며, 완성도가 낮아 커스터마이징도 거의 불가능했습니다.

이러한 문제를 분석하면서 저는 NotionPresso의 차별화 포인트를 명확히 정했습니다.

1. 공식 API 사용: 안정적인 연결을 위해 노션의 공식 API를 적극 활용하기.
2. 완전한 커스터마이징 제공: 사용자들이 자유롭게 페이지 디자인과 기능을 조정할 수 있도록 설계하기.
3. 무료 제공: 누구나 부담 없이 활용할 수 있는 오픈소스 솔루션 만들기.

주제를 정하는 데 가장 큰 계기가 된 것은 노션을 활용한 서비스의 성행이었습니다. 많은 기업이 노션을 활용해 채용 사이트를 만들고 있었지만, 기존 도구들로는 원하는 대로 버튼을 추가하거나 스타일을 수정하는 데 한계가 있었습니다. “채용 사이트에 지원하기 버튼을 마음대로 추가할 수 있다면 얼마나 좋을까?”라는 질문이 떠올랐죠.

결국 NotionPresso는 이러한 필요를 해결하기 위해 탄생했습니다. 단순한 토이 프로젝트가 아닌, 실질적인 수요를 해결하기 위한 솔루션을 목표로 말이죠. 저 역시 여전히 배워가는 과정에 있습니다. 그럼에도 확실히 깨달은 점이 있다면, 바로 코드를 공개한다는 것만으로는 충분하지 않다는 겁니다. 오픈소스는 단순히 코드를 공유하는 것이 아니라, 사람들에게 실질적인 가치를 제공할 수 있는 해결책이어야 합니다.

“내가 해결하려는 문제는 무엇인가?” 그리고 “이것이 누구에게 필요한가?”이 두 가지 질문에 답할 수 있다면, 여러분도 더 많은 사람들과 함께할 수 있는 오픈소스 프로젝트를 만들어갈 수 있을 겁니다.

프로젝트 구조 설계하기

처음 오픈소스 프로젝트를 설계할 때 “새로운 걸 만들어야 한다”는 생각에 사로잡히기 쉽습니다. 그러나 새로운 것을 처음부터 만드는 일은 시간과 노력이 많이 들고, 성공 가능성을 낮출 수 있습니다. 그래서 이미 존재하는 프로젝트를 참고하고, 장점을 흡수하면서 개선점을 찾아내는 것이 훨씬 효과적인 접근법이라는 걸 깨달았습니다.

NotionPresso를 설계하며 제가 가장 먼저 한 일은 기존 라이브러리를 분석하는 것이었습니다. 특히 react-notion-x는 노션 스타일을 구현하는 데 뛰어난 CSS 시스템을 제공하고 있었고, 이를 적극 활용하기로 했습니다. 반면, 사용자가 블록 간의 들여쓰기를 자유롭게 변경하지 못한다는 점은 개선이 필요했습니다. 그래서 CSS 변수를 중심으로 블록 간 들여쓰기를 유연하게 조정할 수 있도록 설계했습니다.

.notion-block > .notion-block {
  margin-left: var(--notion-indent);
}

이처럼 기존 프로젝트를 적극 활용하는 것은 단순히 시간 절약뿐만 아니라 여러 도움을 줍니다. 코드를 읽고 분석하는 과정 자체가 더 나은 설계를 유도하며, 실수를 미연에 방지하는 데도 큰 역할을 합니다.

또한 ‘확장성’을 고려한 설계도 중요한 포인트였습니다. 오픈소스는 서비스보다 더 다양한 요구사항을 수용해야 합니다. 이를 위해 저는 두 가지 디자인 패턴을 적용했습니다.

1) 팩토리 메서드 패턴

각 노션 블록 타입에 맞는 컴포넌트를 생성하는 팩토리를 외부에서 주입받을 수 있도록 설계했습니다. 이렇게 하면 사용자들이 원하는 대로 컴포넌트를 오버라이드하여, 자신만의 스타일을 추가할 수 있습니다.

import { Notion } from "@notionpresso/react";
import CustomHeading from "./CustomHeading";
import CustomParagraph from "./CustomParagraph";
import CustomToggle from "./CustomToggle";

const MyNotionPage = ({ pageData }) => {
  const customComponents = {
    heading_1: CustomHeading,
    heading_2: CustomHeading,
    heading_3: CustomHeading,
    paragraph: CustomParagraph,
    toggle: CustomToggle,
  };

  return (
    <Notion custom={customComponents}>
      <Notion.Body>
        <Notion.Blocks blocks={pageData.blocks} />
      </Notion.Body>
    </Notion>
  );
};

2) 컴파운드 패턴

컴포넌트의 세부적인 부분만 수정할 수 있는 구조를 만들었습니다. 예를 들어, Toggle 블록의 경우 전체 동작은 유지하면서도 아이콘만 바꾸고 싶다면, <Toggle.Icon>로 컴포넌트를 주입하면 됩니다. 반대로 동작 방식을 전면 수정하려면 전체 컴포넌트를 교체할 수도 있습니다.

import { Toggle } from '@notionpresso/react';

const CustomToggle = (props) => (
  <Toggle {...props}>
    <Toggle.Icon>
      {/* 커스텀 아이콘 */}
    </Toggle.Icon>
    <Toggle.Content>{props.children}</Toggle.Content>
  </Toggle>
);

문서화의 필요성

제가 첫 오픈소스 프로젝트를 시작했을 때 가장 간과했던 것이 바로 문서화였습니다. “이 정도만 해도 사람들이 알아서 쓰겠지”라는 마음으로 사용법을 적당히 작성하고 넘어갔죠. 그 결과는 참담했습니다. 아무도 프로젝트를 쓰지 않았고, 기여자도 나타나지 않았습니다. 설명이 부족한 오픈소스는 아무도 쓰지 않습니다. 사람들이 프로젝트를 이해하기 전에, 이 프로젝트가 나에게 필요한지부터 알 수 있어야 한다는 사실을 간과했던 겁니다.

더 중요한 깨달음은 이 문서는 이 프로젝트에 관심 있는 사람들보다, 관심 없는 사람들에게 더 많이 보인다는 점입니다. 프로젝트를 좋아하는 사람들은 스스로 노력해서 이해하려고 하겠지만, 대부분의 사람들은 그렇지 않습니다. 그들의 관심을 끌기 위해 문서를 최대한 친절하고 자세히 작성해야 한다는 것을 뒤늦게 깨달았죠.

이러한 실패 경험을 바탕으로 NotionPresso에서는 문서화를 최우선으로 고려했습니다. README에 프로젝트의 핵심 강점과 기본 사용법을 담았고, 기여 가이드에는 프로젝트 구조와 PR 규칙을 상세히 설명했습니다. 문서는 단순한 텍스트가 아닌, 별도의 웹사이트로 배포했습니다. 이 웹사이트에는 NotionPresso로 블로그를 생성하는 과정을 넘어, Cloudflare에 배포하고 댓글 시스템을 연동하는 방법까지 포함했습니다. 개발자뿐만 아니라 웹 개발에 익숙하지 않은 사용자도 쉽게 따라 할 수 있도록, 가능한 구체적으로 작성했습니다.

문서는 단순히 프로젝트를 사용하는 사람을 늘리는 데 그치지 않습니다. 프로젝트를 중심으로 커뮤니티를 형성하고, 사용자와 기여자가 프로젝트에 쉽게 참여할 수 있는 환경을 만들어줍니다. NotionPresso 역시 앞으로 더 많은 피드백을 받아 문서를 발전시키고, 누구나 쉽게 사용할 수 있는 프로젝트를 만들어가고자 합니다.

오픈소스 프로젝트 홍보하기

처음 오픈소스를 시작했을 때 저는 “좋은 코드는 알아서 퍼진다.”라고 믿었습니다. GitHub에 코드를 올리고 스타를 기다리면 자연스럽게 사람들이 찾아올 것이라 생각했죠. 하지만 현실은 한 달 동안 고작 스타 5개를 받는 게 전부였습니다. 그래서 NotionPresso는 처음부터 다르게 접근했습니다. 홍보는 선택이 아니라 필수라는 것을 깨닫고, 더 많은 사람들에게 다가가기 위해 전략적으로 행동했습니다.

1. 적극적인 채널 활용

NotionPresso를 알리기 위해 국내외 다양한 채널을 활용했습니다.

• 국내 프로덕트 커뮤니티인 렛플과 디스콰이엇에서 프로젝트를 소개했습니다.
• 링크드인, 트위터 같은 SNS를 통해 더 많은 개발자들에게 다가갔습니다.
• 주기적으로 메이커로그를 작성하며 프로젝트 진행 상황을 공유합니다.

하지만 무작정 “제 라이브러리를 써주세요”라고 요청하지는 않습니다. 그것은 스팸과 다를 바 없으니까요. 대신 Notion API를 다루면서 겪은 기술적 도전과 해결 방법을 공유하거나, 적어도 읽는 이들에게 재미있는 인사이트를 전달하려 노력합니다. 유용한 정보를 먼저 제공하고 나면, 사람들이 프로젝트에도 자연스럽게 관심을 가지게 됩니다.

2. 커뮤니티와의 소통

커뮤니티 구축은 프로젝트 성장의 핵심입니다. NotionPresso는 현재 디스코드 채널을 통해 사용자들과 실시간으로 소통하고 있습니다. 사용자들이 제안한 기능이나 개선 사항은 바로 문서에 반영하고, 이를 다시 커뮤니티에 공유하면서 더 나은 프로젝트를 만들어가고 있습니다. 또한 GitHub Discussions에서는 기술적인 토론이 활발히 이뤄지도록 유도하며, 최근에는 해외 사용자들을 위해 Reddit과 Hacker News에도 글을 올리기 시작했습니다.

3. GitHub 스타 확보

여기서 정말 중요한 교훈을 하나 나누고 싶습니다. 저는 첫 오픈소스를 통해 이직을 시도했을 때 아무도 제 라이브러리에 대해 물어보지 않는 현실을 직면했습니다. 면접관들이 서류 검토만으로도 시간이 부족한데, GitHub에 들어가 코드를 일일이 평가할 거라고 기대하는 건 너무 순진한 생각이었죠. 블로그 글이 먼저 조회수로 평가받듯이, 오픈소스는 GitHub 스타로 첫인상이 결정됩니다. 사용자가 코드를 읽어볼 동기를 먼저 제공해야 합니다.

그래서 이제는 매주 새로운 기능이나 개선 사항을 공유할 때마다 항상 GitHub 링크를 첨부하고, 스타를 눌러달라고 명시적으로 요청합니다. 실제로 스타 요청을 포함한 포스트는 그렇지 않은 포스트보다 훨씬 높은 참여도를 보였습니다. 막연히 “좋아요”나 “참고가 되었습니다”라는 댓글을 기대하기보다는, 구체적으로“GitHub에서 스타 눌러주시면 큰 힘이 됩니다!”라고 부탁해 보는 겁니다.

홍보는 선택이 아니라 필수

좋은 코드는 기본이고, 그것을 사람들에게 알리는 일 또한 오픈소스 프로젝트의 일부입니다. 사람들이 프로젝트를 찾고, 관심을 가지며 기여하도록 만드는 것은 코드 작성만큼이나 중요하다는 걸 잊지 마세요.

누구나 시작할 수 있습니다

오픈소스는 단순한 코드 공유가 아니라, 나의 열정과 문제 해결 능력을 보여줄 수 있는 살아 있는 이력서입니다. 제가 NotionPresso를 시작하고, 여러 시행착오를 겪으면서 얻은 가장 큰 교훈은 “완벽하지 않아도 괜찮다. 중요한 것은 시작하고, 꾸준히 개선해 나가는 과정이다.”라는 점입니다.

NotionPresso를 통해 얻은 것들은 단순히 기술적 성과에 그치지 않았습니다.

• 사용자들과 직접 소통하며 새로운 아이디어를 얻었고,
• 기술적 도전을 해결하면서 성장할 수 있었으며,
• 더 나아가 오픈소스가 가져다주는 협업의 힘을 경험할 수 있었습니다.

오픈소스는 여러분의 커리어를 바꿀 수 있는 강력한 도구입니다. 물론 쉬운 길은 아닙니다. 시장을 조사하고, 사용자들의 피드백을 수용하며, 지속적으로 개선하려는 노력이 필요합니다.

그럼에도 저는 여러분에게 이 여정을 추천합니다. 오픈소스는 단순히 결과물로 평가되지 않습니다. 문제를 해결하기 위해 고민하고, 이를 공개하며 더 나은 방향으로 나아가려는 과정 자체가 큰 의미를 갖습니다. 완벽하지 않아도 괜찮습니다. 첫걸음을 내딛고, 한 단계씩 나아가 보세요. 여러분의 프로젝트가 곧 누군가에게는 새로운 영감을 줄 것입니다. 이 글이 여러분에게 오픈소스를 시작할 작은 동기가 될 수 있길 바랍니다.

요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.