create-ejs-web
- ejs 기반 웹 퍼블리싱 보일러 플레이트 입니다.
설치(npx)
- NodeJs v18 이상 설치해 주세요.
- 실행창( Windows + R ) 을 열고, "cmd" 를 입력, 엔터 해서 콘솔창(터미널)을 엽니다.
- 설치할 폴더로 이동합니다.
cd 작업할 폴더위치 - 아래의 코드를 실행창에 넣어 실행(설치)합니다.
# ejs 보일러플레이트 설치
npx create-ejs-web my-web
# 설치된 폴더로 이동
cd my-web
# 개발환경 실행
npm run dev- 브라우저에서
localhost:3000을 입력해서 접속해봅니다. - 혹시 오류나면 아래 추가내용 QA을 참고해주세요.
- 상세 설정은 "./gulp_modules/config.ts" 파일을 확인하세요.
스크립트 실행(npm run)
- 자주쓰는 실행은 npm run 을 통해서도 가능합니다.
- 상세한 실행 방법은 아래 gulp task를 참고하세요.
# gulp dev 와 동일
npm run dev
# gulp sitemap 와 동일
npm run sitemap| 스크립트명 | 연결 Gulp 테스크 | 기능 |
|---|---|---|
npm run compile |
gulp compile |
작업폴더(src) 컴파일러 통합 실행 |
npm run watch |
gulp watch |
작업폴더(src) 감시자 통합 실행 |
npm run sitemap |
gulp sitemap |
html 컴파일 및 PAGEDOC 수집 통합실행 합니다. |
npm run guide |
gulp guide:build |
가이드폴더(src/@guide)를 컴파일 및 산출물제출(배포)용으로 저장 |
npm run dev |
gulp dev |
컴파일 및 감시자, 사이트맵생성, 서버시작 통합 실행 |
npm run build |
gulp build |
작업폴더(src)를 산출물제출(배포)용으로 저장 |
Gulp Task
# gulp 테스크명 으로 실행
gulp dev
gulp html:compiler| Task Name | Series Tasks | config.ts Const | 설명 |
|---|---|---|---|
html:compiler |
- | htmlOptions | 작업폴더(src) 내 ".ejs" 또는 ".html" 을 ".html" 확장자인, ejs로 컴파일합니다. |
html:watcher |
- | htmlOptions | 작업폴더(src) 내 ".ejs" 또는 ".html" 가 변경 될 경우, 컴파일 되도록 감시합니다. |
html:dist |
- | htmlDistOptions | 페이지목록(sitemap.json)을 산출물제출(배포)용으로 저장합니다. |
html:build |
html:compiler, html:dist
|
- | html 산출물을 위한 통합빌드 |
scss:compiler |
- | scssOptions | 작업폴더(src) 내 ".scss"을 컴파일합니다. |
scss:watcher |
- | scssOptions | 작업폴더(src) 내 ".scss"가 변경 될 경우 컴파일 되도록 감시합니다. |
scss:dist |
- | cssDistOptions | 임시폴더(.pub)의 ".css"을 산출물제출(배포)용으로 저장합니다. |
scss:build |
scss:compiler, scss:dist
|
- | css(scss) 산출물을 위한 통합빌드 |
ts:compiler |
- | tsOptions | 작업폴더(src) 내 ".ts"을 컴파일합니다. |
ts:watcher |
- | tsOptions | 작업폴더(src) 내 ".ts"가 변경 될 경우 컴파일 되도록 감시합니다. |
ts:dist |
- | jsDistOptions | 임시폴더(.pub)의 ".js"을 산출물제출(배포)용으로 저장합니다. |
ts:build |
ts:compiler, ts:dist
|
- | ts(js)파일 산출물을 위한 통합빌드 |
image:copy |
- | imageOptions | 작업폴더(src) 내 ".jpg, .png, .gif, .ico"을 임시폴더로 복사합니다. |
image:watcher |
- | imageOptions | 작업폴더(src) 내 ".jpg, .png, .gif, .ico" 가 변경 될 경우 임시폴더로 복사합니다. |
image:dist |
- | imageDistOptions | 임시폴더(.pub)의 ".jpg, .png, .gif, .ico"을 산출물제출(배포)용으로 저장합니다. |
image:build |
image:copy, image:dist
|
- | 이미지파일 산출물을 위한 통합빌드 |
guide:compiler |
- | guideOptions | 가이드폴더(src/@guide) 내 markdown(.md)파일을 컴파일합니다. |
guide:dist |
- | guideDistOptions | 임시폴더의 가이드(.pub/@guide)를 산출물제출(배포)용으로 저장합니다. |
guide:build |
- | guideDistOptions | 가이드파일 산출물을 위한 통합빌드 |
lib:copy |
- | libOptions | 라이브러리 파일들을 임시폴더(.pub)로 복사합니다. |
compile |
lib:copy, html:compiler, scss:compiler, ts:compiler, image:copy
|
- | 컴파일러 통합 실행 |
watch |
html:watcher, scss:watcher, ts:watcher, image:watcher
|
- | 감시자 통합 실행 |
server:dev |
- | devServerOptions | 임시폴더(.pub)을 루트로 서버가 실행 됩니다. (기본포트 3000) |
sitemap:save |
- | htmlDistOptions, sitemapJson | 임시폴더(.pub)을 루트로 htmlDistOptions.src 하위의 html의 PAGEDOC 정보를 수집하여 sitemap.json을 생성합니다. |
sitemap:dist |
- | sitemapHtml | sitemap.json의 기반으로, 빌드용 sitemap.html 파일을 생성됩니다. |
sitemap |
html:compiler, sitemap:save
|
- | html 컴파일 및 PAGEDOC 수집 통합실행 합니다. |
dev |
watch, compile, sitemap:save, server:dev
|
- | 컴파일 및 감시자, 사이트맵생성, 서버시작 통합 실행 |
dist |
html:dist, scss:dist, ts:dist, image:dist
|
- | 임시폴더(.pub)내의 파일을 산출물제출(배포)용으로 저장합니다. |
build |
compile, sitemap:save, dist, sitemap:dist, guide:build
|
- | 저장된 위치의 파일을 전체 산출물제출(배포)용으로 저장합니다. |
사이트맵 수집
- 개발환경 실행
npm run dev후 사이트맵으로 빠른 이동을 시킬수 있습니다. - 사이트맵은 http://localhost:3000/sitemap.html 로 접근 가능 합니다.
- 사이트맵은 PAGEDOC 형식으로, 작성되면 개발환경 실행시 자동으로 크롤링 됩니다.
- 수동으로 가져오는 경우는
npm run sitemap로 재수집 할수 있습니다.
가이드 작성
- 가이드는 http://localhost:3000/@guide/index.html 로 접근 가능 합니다.
- 가이드작성에 관한 내용은 Guide를 참고하세요.
- 수동으로 내보낼때는
npm run guide로 내보낼 수 있습니다.
폴더구조
작업환경 폴더구조
./
+-- /.pub // ./src 에서 컴파일된 결과물 임시저장소, 개발서버의 루트,
+-- /build // 완료후 산출물 제출을 위해, 순수 html,css,js 로 컴파일 되는 곳
+-- /gulp_modules // gulp 실행을 위한 설정 및 실행모듈들
| +-- @Types // gulp 환경용 types
| +-- servers // 서버실행
| +-- tasks // 컴파일 등 실행함수
| +-- util // gulp 공통함수
| +-- config.ts // gulp 환경설정 (가장중요)
+-- /src // 실제 퍼블리싱을 하는 소스의 위치 (아래 참고)
소스 폴더구조
./src
+-- /@guide // 웹퍼블리싱 가이드
| +-- /assets // 가이드에 사용되는 css 등
| | +-- /lib // 코드스니핏 및 markdown css
| +-- index.md // 가이드 인덱스 마크다운
+-- /assets
| +-- /scss // scss을 모아주는(@import) 엔트리 성격의 scss
| +-- /ts // typescript을 모아주는(import) 엔트리 성격의 ts
| +-- /lib // 라이브러리 들
+-- /layouts
| +-- /header // 헤더 공통 영역
| +-- /footer // 풋터 공통 영역
+-- /pages // 페이지
| +-- /main // 메인 페이지
| +-- /sub // 서브 페이지 들
+-- /uikit // 컴포넌트 모음
+-- index.html // 초기 접속페이지
+-- sitemap.html // 사이트맵
QA
Q. npx를 실행하면 아래같은 에러가 나와요.
npm ERR! path C:\Users\사용자명\AppData\Roaming\npm
npm ERR! errno -4058
npm ERR! enoent ENOENT: no such file or directory ...
- npm이 처음 설치되었거나, 글로벌 설치가 한번도 없었어서 그렇습니다.
- 정확하겐,
C:\Users\사용자명\AppData\Roaming\npm폴더가 없어서 그래요.
npm i gulp-cli -g
- 위의 구문을 터미널에서 실행해주세요. (gulp 글로벌 설치 입니다.)
- gulp 설치가 완료되면,
npx create-ejs-web my-web로 재설치 해보세요.
Q. gulp 가 실행할수 없는 프로그램 이래요.
gulp : 'gulp' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다. 이름이 정확한지 확인하고 경로가 포함된 경우 경로가 올바른지 검증한 다음 다시 시도하십시오.
위치 줄:1 문자:1
+ gulp
+ ~~~~
+ CategoryInfo : ObjectNotFound: (gulp:String) [], CommandNotFoundException
+ FullyQualifiedErrorId : CommandNotFoundException
-
npm i gulp-cli -g로 gulp 을 글로벌설치 및 실행구문으로 등록해주세요. -
Gulp Task 중, dev 는 사실
npm run dev로도 실행 할수 있어요.
Q. gulp 에서 보안오류가 나와요.
gulp : 이 시스템에서 스크립트를 실행할 수 없으므로 *** 파일을 로드할 수 없습니다.
+ gulp dev
+ ~~~~
+ CategoryInfo : 보안 오류: (:) [], PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess
- 검색에 powershell 을 찾고, "관리자 권한으로 실행" 을 눌러주세요.
-
Set-ExecutionPolicy RemoteSigned을 입력하시고 엔터. - "y" 하시고 엔터 하시면 됩니다.
Q. ** vulnerabilities (* moderate, ** high) 이런식으로 나와요.
- CSS의 프로퍼티를 정렬해주는 라이브러리(gulp-csscomb) 가 오래된거라(...) 그렇습니다.
Q. ".pub" 폴더랑 "build" 폴더가 생겼어요.
- ".pub" 폴더는 개발서버용 임시 폴더 입니다.(임시 이지만, 중요한 폴더예요. src보다 더 중요할수도 있음)
- "build" 폴더는 배포용폴더 라고 하는데, 웹퍼블리싱 완료 후에 산출물 제출용이예요.
Q. "./index.html"이 build 되지 않아요.
- 기본 설정상 "./" 하위에 있는 파일은 build 되지 않습니다.
- "./page/" 하위에 있는 파일만 빌드됩니다. (config.ts의 htmlDistOptions 변수를 확인해주세요.)
- 기본 설정 상 사이트맵(sitemap.html)만 별도의 설정을 통해 build 됩니다. (config.ts의 sitemapHtml 변수를 확인해주세요.)
참고하세요.
typescript(.ts)의 import
본 프로젝트에서 ".src/" 하위의 typescript(.ts) 의 import는 기존과 다릅니다.
본래는 ts파일의 export 된 객체(모듈)을 가져와 사용하는 개념이지만, 웹퍼블리싱은 보통 번들링을 하지 않고, 브라우저 자체에서의 import 기능을 쓰지 않기 때문에, 번들링이 아닌, 합치기(include) 개념으로 동작합니다.
ejs 와 html
본 프로젝트는 ejs와 html은 동일하게 취급합니다. 즉 html파일 안에 ejs을 사용해도 둥일하게 동작하며, 모든 ejs의 구문이 사용가능합니다. 단, "./src" 폴더 내에 사용된 ".ejs" 파일은 compile 시에 ".pub" 폴더 안에 ".html" 파일로 변경되서 저장됩니다.
html 의 <include> 구문 (확장된 엘리먼트)
ejs의 include 구문을 적용하면 에디터(ex : vscode)의 팔로우링크(Ctrl+클릭)시 해당 파일이동이 동작하지 않습니다.
해서 임의적으로 <include src="경로" options="전달객체"></include>를 추가적으로 커스텀(확장 엘리먼트 생성)해서 넣었습니다.
# "./src/sub/sub.html" 의 <include> 문 (컴파일 전, html 확장형식, 팔로우링크 가능)
<include src="./_inc/subCommon.html" options="{param:'sub.html 에서 파라매터 전달'}"></include>
# "./.pub/sub/sub.html" 의 <%- include %> 문 (컴파일 후, ejs 형식, 팔로우링크 불가)
<%-include(`./_inc/subCommon.html`,{param:'sub.html 에서 파라매터 전달'}) %>
제공환경
v0.9.x 업데이트 이력
v0.9.x 진행중 (TO-DO or TASKs)
- "@src" 을 통한 src path 기능이 구현중입니다.
-
./src/assets/ts안에서 js 파일 호환가능 -
./src/assets/scss안에서 css 파일 호환가능
v0.9.0 업데이트 이력
- 가이드 기능이 강력해졌습니다!
- 이제 소스폴더(./src) 내에서 어떤 폴더든 *.guide.md 파일로 설명서를 만들수 있습니다.
- 가이드 파일은 markdown 이지만, ejs 이기도 합니다! (include가 된다는 말입니다.)
- 자세한 사항은 guide를 참고하세요.
- 예제는 btn.guide.md 을 참고하세요.
앞으로 만들어질 기능들
- sitemap:save 될 때 PAGEDOC 누락파일 검사
- build 될 때 스크립트 오류 페이지 결과 리포트
- build 될 때 W3C 검사도 함께 리포트