NotionNext 개발 시작 가이드

이 문서는 다소 오래되었습니다. 더 포괄적인 개발 안내가 필요하다면 프로젝트 저장소의 README.md와 /docs 디렉터리의 관련 문서를 함께 읽어 주세요.

머리말

2차 개발을 시작하기 전에 먼저 알아야 할 점이 있습니다. NotionNext 자체가 많은 사용자 정의 설정을 지원합니다. 개발 전에 설정 매뉴얼을 읽고 사이트를 먼저 설정하세요. 예를 들면 다음과 같습니다.

blog.config.js 파일에서 사이트 기본 정보, 테마, 언어, 댓글 플러그인 같은 핵심 설정을 수정할 수 있습니다.
각 테마 아래에는 config_[theme].js 설정 파일이 있어 사용자가 페이지를 개인화할 수 있습니다.

NotionNext 코드 구조

사용자 정의 스크립트

NotionNext 사용 설명서에는 사용자 정의 스크립트와 스타일을 가져오는 방법이 설명되어 있습니다.

/public/js/custom.js와 /public/css/custom.css에 스크립트를 추가하면 원하는 페이지 기능을 구현할 수 있습니다.
blog.config.js의 CUSTOM_EXTERNAL_JS, CUSTOM_EXTERNAL_CSS에서도 서드파티 스크립트를 가져올 수 있습니다.

이 두 방식으로 스크립트를 가져오면 로컬에 Node.js 같은 개발 환경이 설치되어 있지 않아도 브라우저 콘솔에서 바로 작성하고 디버깅할 수 있습니다.

Notion에서 사용자 정의 JS와 CSS 설정

4.2.0 이후 버전에서는 Notion에서 웹페이지 스타일과 실행할 스크립트를 직접 지정할 수 있습니다. NotionConfig에 GLOBAL_CSS 속성과 GLOBAL_JS 속성을 설정하면 됩니다. 예시는 다음과 같습니다.

Untitled

직접 개발하기

위 설정 방식으로 요구 사항을 충족할 수 없다면, 예를 들어 새 컴포넌트 추가나 깊은 커스터마이징이 필요하다면 GitHub에서 issue를 생성해 개선 제안을 남기거나, 이 튜토리얼을 따라 직접 개발할 수 있습니다.

선택지는 Codespaces 클라우드 개발과 로컬 개발 두 가지입니다.

1. 클라우드 개발(Codespaces)

선택 사항입니다. 로컬 개발과 비교하면 컴퓨터에 개발 환경을 설치할 필요가 없습니다. GitHub 저장소를 클라우드 개발 환경으로 가져온 뒤 온라인에서 편집하면 됩니다.

프로젝트 가져오기와 실행

Codespaces를 클릭합니다.
새 코드 공간을 만듭니다.
프로젝트를 가져오고 코드 브랜치와 클라우드 환경의 서버 구성을 선택한 뒤 Create codespace를 클릭합니다.
몇 분 정도 기다리면 클라우드 개발 환경이 준비됩니다.

터미널에 yarn을 입력해 의존성 환경을 설치합니다.
설치가 모두 끝난 뒤(약 3분) 터미널에 yarn dev를 입력하면 실시간 디버깅을 시작할 수 있습니다. 터미널에 다음 내용이 표시되면 서비스가 정상적으로 시작된 것입니다.

Bash

@tangly1024 ➜ /workspaces/NotionNext (main) $ yarn dev
yarn run v1.22.19
$ next dev
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
info  - Loaded env from /workspaces/NotionNext/.env.local
Attention: Next.js now collects completely anonymous telemetry regarding usage.
This information is used to shape Next.js' roadmap and prioritize features.
You can learn more, including how to opt-out if you'd not like to participate in this anonymous program, by visiting the following URL:
https://nextjs.org/telemetry

오른쪽 아래의 브라우저에서 열기 버튼을 클릭하면 디버깅 페이지를 열 수 있습니다.

Untitled

디버깅 결과

GitHub는 개발과 디버깅에 사용할 임시 도메인을 할당합니다.

Untitled

2. 로컬 개발

1. 개발 환경 준비

컴퓨터에 Node.js 개발 환경과 코드 편집기 VS Code가 필요합니다.

Node.js 실행 환경

설치 단계

Windows 운영체제에서는 공식 사이트에서 최신 Node.js를 다운로드해 설치하면 됩니다.

Node.js

Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine.

저장소의 README와 .nvmrc에 맞춰 Node 20 사용을 권장합니다. 예: 20.20.0. 아직 18 계열을 사용한다면 최소 18.17.0 이상을 사용하세요. 예: 18.20.4. 설치 후 node -v로 확인합니다.

설치 성공 확인

설치 후 CMD를 실행하고 node -v, npm -v를 각각 입력해 Node와 npm 버전을 확인합니다.

Untitled

Node는 기본 실행 환경이고, npm은 의존성 패키지 관리 도구입니다.

npm -v 실행 시 npm.ps1 파일을 로드할 수 없다는 오류가 나타나면 다음 문서를 참고할 수 있습니다.

VS Code 편집기

다운로드와 설치

Download Visual Studio Code - Mac, Linux, Windows

Visual Studio Code is free and available on your favorite platform - Linux, macOS, and Windows. Download Visual Studio Code to experience a redefined code editor, optimized for building and debugging modern web and cloud applications.

한국어 또는 원하는 언어로 설정

Visual Studio Code 언어 설정 참고

VS Code는 여러 언어와 형식을 지원하는 편집기입니다. 확장 프로그램에서 원하는 언어 팩을 설치한 뒤 다시 시작하면 인터페이스 언어를 바꿀 수 있습니다.

2. 프로젝트 가져오기와 실행

코드 다운로드

GitHub Desktop 설치

GitHub Desktop

Checkout branches with pull requests and view CI statuses See all open pull requests for your repositories and check them out as if they were a local branch, even if they're from upstream branches or forks. See which pull requests pass commit status checks, too!

Sign in to GitHub를 클릭해 로그인하거나, skip this step으로 나중에 로그인해도 됩니다.

Untitled

코드 다운로드

Untitled

본인의 저장소 주소를 찾아 Clone합니다.

Untitled

Clone을 클릭하면 코드가 다운로드됩니다.

VS Code로 프로젝트 열기

프로젝트 파일 열기

Untitled

프로젝트 의존성 설치

메뉴 바에서 터미널을 클릭하고 새 터미널을 선택한 뒤, 새 터미널 창에 설치와 실행 스크립트를 입력합니다.

Untitled

아래 중 한 가지 방식을 선택해 설치합니다.

Bash

# Install with npm
npm install -g yarn --registry=https://registry.npm.taobao.org

# Install with yarn (recommended, faster)
yarn config set registry https://registry.npm.taobao.org/
yarn install

잠시 기다리세요. 처음 의존성을 설치할 때는 시간이 조금 걸립니다.

프로젝트 실행: 명령 하나면 충분합니다

Plain

yarn dev

Bash

# Output shown in VS Code after running
yarn run v1.22.19
$ next dev
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
info  - Loaded env from D:\Workspace\NotionNext\.env.local

Untitled

기타 스크립트 설명

Bash

yarn        # Install dependencies
yarn dev    # Development with hot reload
yarn build  # Build for production
yarn start  # Run the built production server

페이지 접속

브라우저에서 [http://localhost:3000/](http://localhost:3000/)을 열면 로컬 블로그에 접속할 수 있습니다

Untitled

디버그 모드에서는 코드를 수정할 때마다 페이지에 실시간으로 반영됩니다. 새로고침하거나 서비스를 다시 시작할 필요가 없습니다.

3. 로컬 개발 환경 설정

VS Code의 launch 패널을 사용하면 환경 변수 설정과 breakpoint 디버깅을 할 수 있습니다.

Untitled

launch 파일을 만듭니다.

Untitled

공식 권장 설정 예시

JavaScript

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: Debug Server",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "yarn",
      "runtimeArgs": ["dev"],
      "console": "integratedTerminal",
      "skipFiles": ["&lt;node_internals&gt;/**"],
      "env": {
        "NODE_OPTIONS": "--inspect",
        "ENABLE_CACHE": "true"
      }
    },
    {
      "name": "Next.js: Debug Client (Chrome)",
      "type": "pwa-chrome",
      "request": "launch",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}",
      "sourceMaps": true
    }
  ],
  "compounds": [
    {
      "name": "Next.js: Debug Full Stack",
      "configurations": [
        "Next.js: Debug Server",
        "Next.js: Debug Client (Chrome)"
      ]
    }
  ]
}

VS Code에 세 가지 실행 항목이 표시됩니다.

① Debug Server

Node 쪽만 디버깅합니다.

디버깅에 적합한 대상:

getServerSideProps
app/api/*
middleware.ts
server components

② Debug Client (Chrome)

브라우저 디버깅만 실행합니다.

디버깅에 적합한 대상:

React 컴포넌트
hooks
프론트엔드 로직
페이지 이동

③ Debug Full Stack(권장)

한 번에 다음을 함께 실행합니다.

Next dev server
Chrome 디버깅

이는 Next.js에서 가장 자주 쓰는 디버깅 방식입니다.

코드 구조 간단 소개

Next.js

프로젝트는 Next.js 프레임워크로 구성되어 있습니다. 아래는 코드의 주요 디렉터리입니다. 스타일 수정은 주로 themes 디렉터리에서 진행합니다.

Untitled

Next.js 프레임워크는 공식 문서를 참고하세요.

Tailwind CSS

프로젝트 개발에는 Tailwind CSS를 사용합니다. 매우 단순하고 유연한 CSS 유틸리티 라이브러리이며, 익숙해지면 개발 효율이 높습니다.

Tailwind CSS를 사용해야 하는 이유

Tailwind CSS는 HTML의 class를 통해 스타일을 직접 조합하는 프레임워크입니다. 처음에는 기존 CSS 파일이나 style 작성과 무엇이 다른지 의문이 들 수 있습니다. 핵심은 컴포넌트 개발 방식과 높은 재사용성, 그리고 gzip 압축 효율입니다. class가 많아져 HTML이 커져도 유사한 class 문자열이 반복되므로 gzip 압축률이 높습니다. 또한 유지보수할 때 컴포넌트 파일만 보면 스타일을 이해할 수 있어 여러 CSS 파일을 뒤질 필요가 줄어듭니다. 단점도 있습니다. 복잡한 선택자 기반 스타일은 별도 CSS가 필요할 수 있고, 초반에는 클래스명을 익히는 부담이 있습니다. 하지만 익숙해지면 빠르게 스타일을 조합할 수 있습니다.

설치 - Tailwind CSS 문서

The simplest and fastest way to get up and running with Tailwind CSS from scratch is with the Tailwind CLI tool.

코드 포맷 규칙

프로젝트는 ESLint와 Prettier를 사용합니다. 코드 포맷팅은 다음 문서를 참고할 수 있습니다.

juejin.cn

ESLint 플러그인:
- https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint

Untitled

Prettier 플러그인

두 플러그인 중 하나를 선택하고 플러그인 설정 설명에 따라 작업 공간을 설정하면 됩니다.

Untitled

예시: Prettier - Code formatter

사용 설명:

https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

설치 후 프로젝트 설정에서 자동 포맷팅을 활성화하고 settings.json에 다음 설정을 추가합니다.

JSON

{
  // Automatically format with Prettier on save
  "editor.formatOnSave": true,
  // Use Prettier as the default formatter
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // Enable ESLint checks
  "eslint.enable": true,
  // Run ESLint fixes and organize imports on save
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit",
    "source.organizeImports": "explicit"
  }
}

Untitled

설치 후 사용자 또는 프로젝트의 settings.json에서 자동 포맷팅을 활성화할 수 있습니다.

예시 2: Prettier - ESLint

사용 설명: Prettier ESLint - Visual Studio Marketplace
설치 후 프로젝트 설정에서 자동 포맷팅을 활성화하고 settings.json에 다음 설정을 추가합니다.

JSON

{
  "editor.defaultFormatter": "rvest.vs-code-prettier-eslint",
  "editor.formatOnType": false, // required
  "editor.formatOnPaste": true, // optional
  "editor.formatOnSave": true, // optional
  "editor.formatOnSaveMode": "file", // required to format on save
  "files.autoSave": "onFocusChange", // optional but recommended
  "vs-code-prettier-eslint.prettierLast": false // set as "true" to run 'prettier' last not first
}

프로젝트의 관련 설정 파일:

Java

.eslintrc.js
.prettierrc.json

원문 링크

https://docs.tangly1024.com/article/how-to-develop-with-notion-next

NotionNext 개발 시작 가이드 ​

머리말 ​

사용자 정의 스크립트 ​

Notion에서 사용자 정의 JS와 CSS 설정 ​

직접 개발하기 ​

1. 클라우드 개발(Codespaces) ​

프로젝트 가져오기와 실행 ​

2. 로컬 개발 ​

1. 개발 환경 준비 ​

2. 프로젝트 가져오기와 실행 ​

3. 로컬 개발 환경 설정 ​

① Debug Server ​

② Debug Client (Chrome) ​

③ Debug Full Stack(권장) ​

코드 구조 간단 소개 ​

Next.js ​

Tailwind CSS ​

코드 포맷 규칙 ​

원문 링크 ​

NotionNext 개발 시작 가이드

머리말

사용자 정의 스크립트

Notion에서 사용자 정의 JS와 CSS 설정

직접 개발하기

1. 클라우드 개발(Codespaces)

프로젝트 가져오기와 실행

2. 로컬 개발

1. 개발 환경 준비

2. 프로젝트 가져오기와 실행

3. 로컬 개발 환경 설정

① Debug Server

② Debug Client (Chrome)

③ Debug Full Stack(권장)

코드 구조 간단 소개

Next.js

Tailwind CSS

코드 포맷 규칙

원문 링크