???? 노션 기반 커스텀 사이트 구축 가이드 (with Nooxy & Cloudflare)

노션의 기본 기능을 넘어 나만의 브랜딩을 입힌 웹사이트를 구축하고 싶은 분들을 위해, Nooxy와 Cloudflare Workers를 활용한 배포 과정을 정리합니다.

1. 사전 준비 (Prerequisites)

• Notion 페이지: 공개(Publish to web) 설정이 완료된 페이지 ID

• Cloudflare 계정: Workers 배포를 위한 무료 플랜

• 개발 환경: Node.js v18+, wrangler CLI 설치

2. 핵심 구축 단계

Step 1: 프로젝트 초기화

단순히 파일을 복사하는 대신, Cloudflare Workers 환경에서 Nooxy를 라이브러리로 사용하는 방식이 가장 안정적입니다.

npm create cloudflare@latest my-nooxy-site
cd my-nooxy-site
npm install nooxy

Step 2: 실행부(src/index.ts) 및 설정 작성

config.js의 설정값을 불러와 Nooxy 엔진을 가동하는 코드입니다.

import { initializeNooxy } from 'nooxy';
import { SITE_CONFIG } from '../config';

const proxy = initializeNooxy(SITE_CONFIG);

export default {
  async fetch(request: Request): Promise<Response> {
    return proxy(request);
  },
};

3. 주요 트러블슈팅 (핵심 포인트)

이번 작업에서 가장 중요했던 '에러 해결' 노하우입니다. 블로그 독자들에게 가장 큰 도움이 될 부분이죠.

✅ 에러 10021: "No event handlers were registered"

• 원인: Cloudflare가 실행할 fetch 핸들러(입구)를 찾지 못할 때 발생.

• 해결: src/index.ts 파일에 반드시 export default { fetch... }가 포함되어 있는지 확인하고, wrangler.jsonc의 main 경로를 정확히 지정해야 합니다.

✅ 에러: "Cannot convert undefined to object"

• 원인: config.js에서 불러온 객체가 비어있거나 경로가 틀린 경우.

• 해결: 자바스크립트의 백틱(`) 문법을 사용하여 여러 줄의 CSS를 안전하게 처리하고, import * as Config 방식을 통해 설정값을 방어적으로 불러와야 합니다.

4. 커스텀 브랜딩 (CSS 팁)

전문적인 보안 사이트 느낌을 주기 위해 불필요한 요소를 제거하고 폰트를 최적화하는 CSS 코드입니다.

/* 한글 가독성을 위한 Pretendard 폰트 적용 */
@import url('https://cdn.jsdelivr.net/gh/orioncactus/pretendard/dist/web/static/pretendard.css');
body { font-family: 'Pretendard', sans-serif !important; }

5. 배포 및 업데이트

수정 사항이 생길 때마다 아래 루틴을 반복합니다.

1. npx nooxy generate (자산 생성)

2. npx wrangler deploy src/index.ts --name [name]-worker (배포)

config.js

export const SITE_CONFIG = {

  domain: '[name]-worker.[id].workers.dev',

  notionDomain: '[name].notion.site', // 본인의 노션 도메인

  siteName: '[name]',

  // 이 부분이 누락되었거나 이름이 틀렸을 확률이 높습니다.

  slugToPage: {

    '/': '[pageid]'

  },

  googleAnalyticsId: ''

% ls -R  

nooxy

./nooxy:

generated nooxy package.json

node_modules package-lock.json wrangler.jsonc

./nooxy/generated:

_body-js-string.js _head-js-string.js

_head-css-string.js _header-html-string.js

./nooxy/node_modules:

nooxy

./nooxy/node_modules/nooxy:

LICENSE README.md dist package.json

./nooxy/node_modules/nooxy/dist:

cli index.d.ts index.js index.js.map

./nooxy/node_modules/nooxy/dist/cli:

index.js templates

./nooxy/node_modules/nooxy/dist/cli/templates:

body.js config.js head.css head.js header.html

./nooxy/nooxy:

body.js head.css nooxy.config.json

config.bak head.js src

config.js header.html

generated nooxy

./nooxy/nooxy/generated:

_body-js-string.js _head-js-string.js

_head-css-string.js _header-html-string.js

./nooxy/nooxy/nooxy:

generated

./nooxy/nooxy/nooxy/generated:

./nooxy/nooxy/src:

index.ts