notion-step
교육용 Padlet 클론 Step 1: Notion DB 연동 코드 생성 및 교안 작성 가이드. Express.js 서버 + Notion API 프록시 + Vanilla HTML/CSS/JS 프론트엔드 구현. Notion 연동, Step 1 코드 작성, Notion API 키 설정 가이드가 필요하면 이 스킬을 사용할 것.
SKILL.md.claude/skills/notion-step/SKILL.md
GitHubNotion Step — Step 1 구현 가이드
교육용 Padlet 클론의 첫 번째 단계: Notion을 시각적 데이터베이스로 사용하는 보드 앱.
이 단계의 학습 목표
- 데이터베이스란 무엇인가 (Notion 표 = DB)
- 클라이언트-서버 구조 이해 (브라우저 ↔ Express 서버 ↔ Notion)
- API와 HTTP 요청 개념 (fetch, JSON)
- CRUD 동작 직접 확인 (Notion 페이지에서 데이터 변화 관찰)
기술 스택
브라우저 (HTML/CSS/JS)
↕ fetch() — HTTP 요청
localhost:3000 (Express.js 서버)
↕ @notionhq/client — Notion SDK
Notion Database (학생이 직접 볼 수 있는 표)
사용 패키지:
express— 웹 서버@notionhq/client— Notion 공식 SDKdotenv— 환경변수 (.env 파일)cors— 브라우저-서버 통신 허용
Notion DB 구조 (표준)
학생의 Notion에 만들 데이터베이스 컬럼:
| 컬럼명 | 타입 | 설명 |
|---|---|---|
| Title | Title | 카드 제목 (Notion 기본 컬럼) |
| Content | Text | 카드 내용 |
| Color | Select | 카드 배경색 (yellow/blue/green/pink) |
| BoardId | Text | 어느 보드에 속하는지 |
| CreatedAt | Created time | 자동 생성 |
코드 구현 가이드
server.js 핵심 구조
// 필요한 도구들을 가져옵니다
require('dotenv').config();
const express = require('express');
const { Client } = require('@notionhq/client');
const cors = require('cors');
const app = express();
const notion = new Client({ auth: process.env.NOTION_API_KEY });
const DATABASE_ID = process.env.NOTION_DATABASE_ID;
app.use(cors());
app.use(express.json());
app.use(express.static('public'));
// db.js를 통해 Notion 연동
const db = require('./db');
// 서버 시작 전 환경변수 확인
if (!process.env.NOTION_API_KEY || !process.env.NOTION_DATABASE_ID) {
console.error('❌ .env 파일에 NOTION_API_KEY와 NOTION_DATABASE_ID가 필요합니다.');
console.error(' .env.example 파일을 복사해서 .env를 만들고 값을 채워주세요.');
process.exit(1);
}
// API 엔드포인트
app.get('/api/cards', async (req, res) => { ... });
app.post('/api/cards', async (req, res) => { ... });
app.patch('/api/cards/:id', async (req, res) => { ... });
app.delete('/api/cards/:id', async (req, res) => { ... });
app.listen(3000, () => console.log('✅ 서버 시작! http://localhost:3000'));
db.js (Notion 버전) 표준 구현
code-builder는 아래 인터페이스를 정확히 구현해야 한다:
const { Client } = require('@notionhq/client');
require('dotenv').config();
const notion = new Client({ auth: process.env.NOTION_API_KEY });
const DATABASE_ID = process.env.NOTION_DATABASE_ID;
// Notion 응답을 우리 앱 형식으로 변환하는 함수
function notionToCard(page) {
return {
id: page.id,
title: page.properties.Title?.title[0]?.plain_text || '',
content: page.properties.Content?.rich_text[0]?.plain_text || '',
color: page.properties.Color?.select?.name || 'yellow',
boardId: page.properties.BoardId?.rich_text[0]?.plain_text || 'default',
createdAt: page.created_time,
};
}
module.exports = {
// DB 초기화 (Notion은 이미 만들어져 있으므로 연결 테스트만)
initialize: async () => {
await notion.databases.retrieve({ database_id: DATABASE_ID });
console.log('✅ Notion DB 연결 성공');
},
// 카드 목록 조회
getCards: async (boardId = 'default') => {
const response = await notion.databases.query({
database_id: DATABASE_ID,
filter: boardId !== 'all' ? {
property: 'BoardId',
rich_text: { equals: boardId }
} : undefined,
});
return response.results.map(notionToCard);
},
// 카드 생성
createCard: async ({ title, content, color = 'yellow', boardId = 'default' }) => {
const response = await notion.pages.create({
parent: { database_id: DATABASE_ID },
properties: {
Title: { title: [{ text: { content: title } }] },
Content: { rich_text: [{ text: { content: content } }] },
Color: { select: { name: color } },
BoardId: { rich_text: [{ text: { content: boardId } }] },
},
});
return notionToCard(response);
},
// 카드 수정
updateCard: async (id, { title, content, color }) => {
const properties = {};
if (title !== undefined) properties.Title = { title: [{ text: { content: title } }] };
if (content !== undefined) properties.Content = { rich_text: [{ text: { content: content } }] };
if (color !== undefined) properties.Color = { select: { name: color } };
const response = await notion.pages.update({ page_id: id, properties });
return notionToCard(response);
},
// 카드 삭제 (Notion은 아카이브 처리)
deleteCard: async (id) => {
await notion.pages.update({ page_id: id, archived: true });
return { success: true };
},
// 보드 목록 (Step 1에서는 기본 보드 1개만)
getBoards: async () => [{ id: 'default', name: '우리 반 보드' }],
createBoard: async ({ name }) => ({ id: name.toLowerCase(), name }),
};
프론트엔드 구현 포인트
public/index.html + public/app.js에서 구현할 내용:
- 보드 레이아웃 — CSS Grid로 카드 배치 (Masonry 레이아웃 지향)
- 카드 추가 — 모달 또는 인라인 폼
- 카드 삭제 — 카드 우상단 X 버튼
- 카드 색상 — 4가지 색상 선택 (yellow, blue, green, pink)
- 자동 새로고침 — 5초마다
GET /api/cards호출 (폴링 방식, Step 1 한정)
app.js 핵심 패턴:
// 서버에서 카드 가져오기
async function loadCards() {
const res = await fetch('/api/cards');
const cards = await res.json();
renderCards(cards);
}
// 카드 HTML로 변환
function renderCards(cards) {
const board = document.getElementById('board');
board.innerHTML = cards.map(card => `
<div class="card ${card.color}" data-id="${card.id}">
<button class="delete-btn" onclick="deleteCard('${card.id}')">×</button>
<h3>${card.title}</h3>
<p>${card.content}</p>
</div>
`).join('');
}
.env.example 표준
# Notion API 키 (https://www.notion.so/my-integrations 에서 발급)
NOTION_API_KEY=secret_여기에_실제_키를_붙여넣으세요
# Notion 데이터베이스 ID (Notion DB 페이지 URL에서 복사)
# URL 예: https://notion.so/abc123def456?v=... → ID: abc123def456
NOTION_DATABASE_ID=여기에_데이터베이스_ID를_붙여넣으세요
Notion API 키 발급 절차 요약
curriculum-writer가 학생용 가이드를 작성할 때 참고:
- notion.so 로그인 → 우측 상단 프로필 → Settings
- 좌측 메뉴 "Connections" → "Develop or manage integrations" 클릭
- "+ New integration" → 이름 입력 (예: "우리반 패들렛") → Submit
- "Internal Integration Secret" 복사 →
.env의NOTION_API_KEY에 붙여넣기 - Notion에서 DB 페이지 열기 → 우상단 "..." → "Connections" → 방금 만든 인테그레이션 연결
- DB 페이지 URL에서 ID 복사:
notion.so/[이_부분_32글자]?v=...
상세 스크린샷 설명은
references/notion-api-guide.md참조
테스트 시나리오
정상 동작 확인 순서
npm install→ 오류 없음.env.example→.env복사 후 키 입력node server.js→ "✅ Notion DB 연결 성공", "✅ 서버 시작!" 출력http://localhost:3000→ 빈 보드 화면- 카드 추가 → Notion DB 새로고침 → 새 행 생성 확인
- 카드 삭제 → Notion DB 새로고침 → 해당 행 아카이브 처리 확인