03442025년 11월 11일

[SvelteKit] SvelteKit 프로젝트의 package.json Scripts 완전 정리

| 서론

안녕하세요, 팡일입니다!

오늘은 Re:Log 프로젝트의 package.json 파일을 살펴보다가, scripts 항목이 어떤 역할을 하는지 하나씩 정리해보았습니다.

SvelteKit은 Vite 기반이라 구조가 단순해 보이지만, 각 스크립트가 하는 일에는 분명한 목적이 있었습니다.

이번 글에서는 개발, 빌드, 배포, 코드 품질 관리까지 전반적인 흐름을 정리합니다.

bash

"scripts": {
  "dev": "vite dev",
  "build": "vite build",
  "preview": "vite preview",
  "prepare": "svelte-kit sync || echo ''",
  "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
  "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
  "format": "prettier --write .",
  "lint": "prettier --check . && eslint ."
}

| 주요 스크립트 해설

1. dev — 개발 서버 실행

: 로컬 개발 환경을 구동하는 명령어입니다.

vite dev로 실행되며, 코드가 저장될 때마다 자동으로 새로고침 없이 화면이 업데이트됩니다.기본적으로 http://localhost:5173 포트에서 실행됩니다.
핫 리로드(Hot Reload) 기능 덕분에 페이지 전체를 새로고침하지 않고, 수정된 부분만 갱신됩니다.
이는 Svelte가 컴파일 단계에서 변경된 DOM만 다시 렌더링하기 때문에 가능한 구조입니다.

참고- 개발 모드에서는 성능 최적화보다 빠른 피드백이 우선입니다.- 로그가 많이 출력되고 빌드 속도가 느리더라도, 디버깅에는 오히려 더 유리합니다.

2. build — 배포용 정적 파일 생성

: vite build 명령은 프로덕션 빌드(Production Build) 를 수행합니다.

SvelteKit이 모든 페이지를 HTML, CSS, JS 형태로 정적 컴파일하여build 혹은 .svelte-kit/output 폴더에 결과물을 생성합니다.
이 결과물은 실제 배포 환경에서 사용되는 코드입니다.
이 파일들이 Firebase Hosting, Netlify, Vercel 같은 정적 호스팅 서버에 올라가게 됩니다.

주의할 점- 빌드 후에는 Hot Reload가 적용되지 않습니다.- vite.config.ts에서 base 경로나 adapter 설정이 올바르지 않으면 리소스 로딩이 실패할 수 있습니다.- 빌드 결과물은 반드시 preview 명령으로 확인해보는 습관을 들이세요.

3. preview — 배포 전 미리보기

: 빌드된 결과물을 로컬 서버에서 테스트하는 명령어입니다.

vite preview는 실제 배포 환경처럼 정적 파일을 서빙해줍니다.Firebase Hosting, Netlify, AWS S3 같은 정적 호스팅 환경을 미리 체험할 수 있습니다.
“배포 전 리허설 단계”라고 보면 됩니다.
개발 모드에서는 잘 작동하던 코드가, 빌드 후 깨질 수 있기 때문에 반드시 npm run preview로 테스트하는 것이 중요합니다.

예시 시나리오- Firebase Hosting 배포 직전에 화면이 잘 뜨는지 확인- import 경로나 static 자원 접근이 올바른지 테스트- base path, favicon, icon 폴더 경로 문제를 미리 점검

4. prepare — 내부 동기화

: svelte-kit sync 명령으로 라우팅, 환경 설정, 타입 정의(tsconfig) 등을 자동으로 갱신합니다.

npm install 직후, 의존성을 새로 추가했을 때, 혹은 라우트 구조가 바뀌었을 때 실행해주면 좋습니다.
라우팅 관련 오류(Cannot find module ..., Invalid route)가 발생했다면,
npm run prepare 한 번으로 대부분 해결됩니다.

참고- SvelteKit은 파일 기반 라우팅을 사용하기 때문에, 새로운 페이지를 추가하거나 폴더 구조를 바꿀 때마다 sync가 필요할 수 있습니다.- Git pull 후 동료의 코드가 추가된 경우에도 실행하는 것이 안전합니다.

5. check / check:watch — 타입 및 오류 검사

: svelte-check는 TypeScript와 Svelte 파일을 동시에 검사하는 유용한 도구입니다.

종류
- check: 한 번만 검사하고 종료
- check:watch: 파일 변경을 감지해 실시간으로 검사
개발 중 타입 에러, props 누락, import 불일치 등을 빠르게 탐지할 수 있습니다.

활용 팁- VSCode 확장보다 더 엄밀하게 검사하기 때문에, CI/CD 파이프라인에서도 자주 사용됩니다.- "--tsconfig 옵션"으로 지정한 설정이 잘못되면 false positive(잘못된 에러)가 날 수 있으니 주의하세요.

6. format — 코드 자동 정렬

: prettier --write . 명령으로 전체 프로젝트 코드를 자동 포맷팅합니다.

들여쓰기, 세미콜론, 따옴표, 줄바꿈 등을 통일시켜줍니다.
협업 시 코드 스타일을 통일하는 데 필수입니다.

Tip- .prettierrc.cjs 파일을 만들어 규칙을 프로젝트별로 커스터마이징할 수 있습니다.- Git 커밋 전에 자동 포맷팅이 적용되도록 pre-commit 훅에 추가하면 더 깔끔합니다.

7. lint — 코드 규칙 검사

: prettier --check .로 포맷이 맞는지 확인한 후, eslint . 명령으로 문법 오류나 코드 규칙 위반을 검사합니다.

팀 개발 시 일관된 코드 품질을 유지하기 위한 단계입니다.

활용 팁- ESLint는 Svelte, TypeScript 전용 플러그인을 함께 설정해야 합니다.- “prettier-plugin-svelte”, “eslint-plugin-svelte” 조합을 사용하면 포맷과 규칙을 모두 잡을 수 있습니다.

| 결론

이번에 각 명령을 직접 실행해보면서, 단순히 “코드를 돌린다”가 아니라, “프로젝트 전체의 생명주기를 관리한다”는 느낌을 받았습니다.

npm run dev로 시작해 npm run build로 마무리하기까지의 과정은 단순한 기술 명령이 아니라 개발자의 사고 흐름을 담고 있는 것 같습니다.

“명령어를 외우는 게 아니라, 그 의미를 이해하는 개발자.”