@dooboostore두부가게
StartComponentsSSREcosystem
GitHub
Get started시작하기
From an empty folder to a working component in about five minutes.
빈 폴더에서 동작하는 컴포넌트까지, 대략 5분.
Fastest way가장 빠른 길
A homepage search engines can read — in onenpm run build.검색엔진이 읽는 회사 홈페이지,npm run build한 줄.
A small company homepage, ready to edit. Copy it, run it, change the words. Static files only — no server to run.바로 고쳐 쓸 수 있는 작은 회사 홈페이지예요. 받아서, 돌리고, 문구만 바꾸세요. 정적 파일이라 서버가 필요 없어요.
- Home / About / Contact pages, a header menu and a 404홈 / 소개 / 문의 페이지, 헤더 메뉴, 404
- A title and description per page (SEO)페이지마다 제목·설명 (SEO)
npm run build→ HTML per page + sitemap.xml + robots.txtnpm run build→ 페이지별 HTML + sitemap.xml + robots.txt- Push to main → deployed to GitHub Pagesmain 에 푸시 → GitHub Pages 배포
- Vite dev server — the one you already know익숙한 Vite 개발 서버
terminal
npx degit dooboostore-develop/dooboostore-develop.github.io/templates/homepage-starter my-sitecdmy-site
npm install
npm run dev# http://localhost:5173Full-stack · SSR풀스택 · SSR
Server-rendered pages that call the server like a method.서버가 그려 주는 페이지, 서버 호출은 메서드 한 줄.
A Node server renders the same components, ships the data with the page, and answers the browser through one shared interface. Open/usersand watch what happens.Node 서버가 같은 컴포넌트를 그리고, 데이터를 페이지에 실어 보내고, 공유 인터페이스 하나로 브라우저 호출에 답해요./users를 열어 보세요.
- First load: drawn on the server, 0 requests from the browser (hydration)첫 화면: 서버가 그려 보냄, 브라우저 요청 0개 (하이드레이션)
- One interface in
src/services— HTTP proxy in front, real code on the serversrc/services의 인터페이스 하나 — 프론트는 HTTP 프록시, 서버는 진짜 구현 - No API routes, no
fetchcode — components just callgetUsers()API 라우트도fetch코드도 없음 — 컴포넌트는getUsers()를 부를 뿐 npm run devrebuilds the front and restarts the server on savenpm run dev하나로 저장하면 프론트 다시 빌드 + 서버 재시작
terminal
npx degit dooboostore-develop/dooboostore-develop.github.io/templates/ssr-starter my-appcdmy-app
npm install
npm run dev# http://localhost:3000Or set it up yourself직접 하나씩 설정하고 싶다면
The same thing, one piece at a time.같은 걸 한 조각씩.
1
Install설치
simple-boot,coreandcore-webcome along as dependencies. Add@dooboostore/simple-bootyourself only when your code imports it (e.g.@Sim,@inject).simple-boot·core·core-web은 의존성으로 같이 따라옵니다. 내 코드에서 직접 import 할 때(@Sim,@inject등)만@dooboostore/simple-boot를 따로 설치하세요.
terminal
npm i @dooboostore/simple-web-component reflect-metadata2
Turn on decorators데코레이터 켜기
emitDecoratorMetadatalets the container inject by type alone. Plain esbuild/Vite don't emit it — there, name what you want with@inject(SYMBOL)(the starters do), or run tsc in the pipeline (ts-loader, esbuild-plugin-tsc).emitDecoratorMetadata가 있으면 타입만 보고 주입됩니다. esbuild/Vite 단독은 이걸 안 만들어요 — 거기선@inject(SYMBOL)로 이름을 찍어 주입하거나(스타터들이 이 방식), 파이프라인에 tsc를 끼우세요(ts-loader, esbuild-plugin-tsc).
tsconfig.json
{"compilerOptions":{"experimentalDecorators":true,"emitDecoratorMetadata":true}}3
Write a component컴포넌트 하나
The method returns; the decorators decide where it goes. That's the whole idea.메서드는 반환만, 둘 곳은 데코레이터가. 이게 전부예요.
hello-card.ts
import{ elementDefine, onConnectedBodyShadow, event, innerHtml }from'@dooboostore/simple-web-component';exportdefault(w:Window) => {consttag ='hello-card';if(w.customElements.get(tag))returntag;@elementDefine(tag, {window: w })classHelloCardextendsw.HTMLElement{privatecount =0;@onConnectedBodyShadowrender() {return`<p>Hello,${this.getAttribute('name')}!</p>
<button>clicked <b>0</b> times</button>`;
}@eventClick('button')@innerHtml('b')onClick() {returnString(++this.count);
}
}returntag;
};4
Put it on a page페이지에 놓기
<body is="swc-app-body">becomes the app host. Safari needs theis="…"polyfill (first script).<body is="swc-app-body">가 앱 호스트가 됩니다. 사파리는is="…"폴리필이 필요해요(첫 번째 스크립트).
index.html
<head><scriptsrc="https://unpkg.com/@ungap/custom-elements"></script><scripttype="module"src="./main.ts"></script></head><bodyid="app"is="swc-app-body"><hello-cardname="World"></hello-card></body>5
Boot the app앱 띄우기
Register the app hosts, then connect: give it a window, a container and the components to define.앱 호스트를 등록하고 connect: window, 컨테이너, 정의할 컴포넌트를 넘기면 끝.
main.ts
import'reflect-metadata';import{ defineSwcAppAll }from'@dooboostore/simple-web-component';importhelloCardfrom'./hello-card';awaitdefineSwcAppAll(window);document.querySelector<any>('#app').connect({window,container:Symbol('app'),onStartedLazyDefineComponent: [helloCard],
});That's it — a counter with no state library, no virtual DOM.끝 — 상태 라이브러리도 가상 DOM도 없는 카운터.
Every decorator idea데코레이터 아이디어 전부Full example apps예제 앱Reference (README)레퍼런스 (README)Add SSRSSR 붙이기
FAQ
The questions you were about to ask.막 물어보려던 그 질문들.
Why is every component wrapped in(w: Window) => { … }?왜 컴포넌트마다(w: Window) => { … }로 감싸나요?
So the same class can register intoany window— the browser's, an iframe's, or the server-side DOM that renders SSR. The factory returns the tag name and bails out early if it's already defined.같은 클래스를어떤 window에든등록하려고요 — 브라우저, iframe, 그리고 SSR을 그리는 서버 쪽 DOM까지. 팩토리는 태그 이름을 돌려주고, 이미 정의돼 있으면 바로 빠집니다.
Standard (TC39) decorators?표준(TC39) 데코레이터는요?
Today it runs on TypeScript's
experimentalDecorators+reflect-metadata. Moving to standard decorators isa goal, and the aim is to keep your call sites as they are.지금은 TypeScript의experimentalDecorators+reflect-metadata위에서 돕니다. 표준 데코레이터로 옮기는 게목표이고, 호출하는 코드는 그대로 두는 걸 지향해요.Can I drop these into React, Vue or a plain page?React, Vue, 그냥 HTML 페이지에 넣어도 되나요?
Yes. They are standard custom elements — anything that renders DOM can render them.네. 표준 커스텀 엘리먼트라 DOM을 그리는 건 뭐든 렌더할 수 있어요.
Do I have to useis="swc-app-body"?is="swc-app-body"를 꼭 써야 하나요?
No —
swc-app-divand friends exist, andSwcAppMixinturns your own element into an app host (nois, no Safari polyfill).아니요 —swc-app-div같은 변형도 있고,SwcAppMixin으로 내 엘리먼트를 앱 호스트로 만들 수도 있어요(is도 사파리 폴리필도 불필요).Is it a fit?나한테 맞을까?
Where it shines, and where to think twice.잘 맞는 곳, 그리고 한 번 더 생각할 곳.
A good fit이럴 때 잘 맞아요
- Company and product sites, landing and event pages — where search visibility matters회사·제품 소개 사이트, 랜딩·이벤트 페이지 — 검색 노출이 중요한 곳
- Adding interactive widgets to an existing site (they are standard custom elements)기존 사이트에 인터랙티브 위젯 붙이기 (표준 커스텀 엘리먼트라 어디든)
- Front and back end in one TypeScript codebase (same DI, Symbol RPC)프론트와 백을 TypeScript 하나로 (같은 DI, Symbol RPC)
- Small teams and personal projects that want a light, readable stack가볍고 읽을 수 있는 스택을 원하는 작은 팀·개인 프로젝트
Think twice이럴 땐 아직 신중하게
- Large services many teams will run for years — React has far more people and material여러 팀이 오래 운영할 대형 서비스 — 사람·자료는 React 쪽이 압도적
- Non-developers must publish posts themselves — there is no content admin; consider a CMS비개발자가 글을 직접 올려야 함 — 콘텐츠 관리 화면이 없어요, CMS를 고려하세요
- You need lots of ready-made UI parts — the component library is still small기성 UI 부품이 많이 필요함 — 컴포넌트 라이브러리가 아직 작아요
- Only standard (TC39) decorators are allowed in your codebase표준(TC39) 데코레이터만 허용되는 코드베이스
How it compares비교
Honest, including where we lose.솔직하게, 지는 칸까지.
| simple-web-component | Lit | React + Next | |
|---|---|---|---|
| What you ship결과물 | ✓standard custom elements✓표준 커스텀 엘리먼트 | ✓standard custom elements✓표준 커스텀 엘리먼트 | React componentsReact 컴포넌트 |
| Virtual DOM가상 DOM | none없음 | none없음 | yes있음 |
| How the DOM updatesDOM 갱신 방식 | a method returns → decorators write to targets메서드 반환 → 데코레이터가 대상에 씀 | reactive props → template re-render리액티브 프로퍼티 → 템플릿 재렌더 | state → re-render → diff상태 → 재렌더 → 비교 |
| After SSR, the browser…SSR 뒤 브라우저는… | ✓keeps the DOM, wires behavior✓DOM 유지, 행위만 연결 | hydrates templates (labs)템플릿 하이드레이트(labs) | re-runs components to hydrate컴포넌트를 다시 돌려 하이드레이트 |
| DI (dependency injection) containerDI(의존성 주입) 컨테이너 | ✓built in✓내장 | — (context protocol)— (context 프로토콜) | — (context)— (context) |
| Calling the server서버 호출 | ✓interface + Symbol (Symbol RPC)✓인터페이스 + Symbol (Symbol RPC) | —— | Server ActionsServer Actions |
| Decorators데코레이터 | TypeScript experimentalTypeScript experimental | standard + experimental표준 + experimental | —— |
| Ecosystem생태계 | small — you'd be early작음 — 초기 멤버가 됩니다 | large큼 | huge거대 |
Small ecosystem, big leverage: issues get read by the people who wrote the code.Say hi on GitHub.생태계는 작지만, 대신 이슈를 코드 쓴 사람이 직접 읽습니다.GitHub에서 인사하기.