Shopify 앱 개발 프로젝트를 시작하면, 루트 폴더 안에 여러 개의 익숙하지 않은 설정 파일들이 자동으로 생성되어 있는 것을 볼 수 있습니다. 이 파일들은 대부분 Shopify CLI가 앱을 생성할 때 자동으로 만들어주는 기본 구조의 일부이며, 각각의 파일은 특정한 목적과 역할을 가지고 있습니다. 이 파일들의 기능과 내용, 그리고 수정 시 주의할 점을 알고 있어야 프로젝트를 안정적으로 유지하고 에러를 방지할 수 있습니다.
가장 핵심적인 파일은 package.json입니다. 이 파일은 Node.js 기반 프로젝트의 중심 역할을 하며, 어떤 외부 라이브러리를 사용하는지, 어떤 명령어로 앱을 실행하는지 등의 정보를 담고 있습니다. 앱이 실행되지 않거나 빌드에 실패할 경우 가장 먼저 이 파일의 설정을 점검해야 합니다.
remix.config.js는 Remix 프레임워크의 구조를 설정하는 파일입니다. 페이지 라우팅, 빌드 대상 디렉토리, 무시할 파일들을 정의하며, 잘못 설정할 경우 앱 전체가 정상적으로 동작하지 않을 수 있습니다. React와 함께 작동하는 Remix는 이 파일을 기반으로 내부 구조를 판단하기 때문에 중요도가 높습니다.
만약 TypeScript를 사용하는 앱이라면 tsconfig.json 파일도 생성됩니다. 이 파일은 어떤 폴더를 검사하고 어떤 문법을 허용할지 등 TypeScript의 컴파일 방식을 정의합니다. 실수로 잘못된 설정을 추가하거나 경로를 잘못 지정하면 컴파일 오류가 발생할 수 있습니다.
보안을 위한 중요한 파일 중 하나는 .env입니다. 이 파일에는 Shopify API 키, 비밀 키, 인증 범위(SCOPES), 데이터베이스 주소 등의 민감한 정보가 저장됩니다. 따라서 절대로 GitHub와 같은 공개 저장소에 업로드되어서는 안 되며 .gitignore 파일을 통해 관리 대상에서 제외되어야 합니다.
.gitignore 파일은 Git으로 소스코드를 관리할 때 추적하지 않을 파일 목록을 정의합니다. 예를 들어 node_modules, .env, .DS_Store 같은 불필요하거나 민감한 정보가 담긴 파일들을 Git 기록에서 제외할 수 있습니다. 실수로 중요한 파일을 무시하지 않도록 조심해야 합니다.
또한 shopify.app.toml은 Shopify CLI가 앱을 실행하고 배포할 때 사용하는 설정 파일입니다. 앱 이름, 인증 범위, 웹훅 설정, 확장 프로그램 정의 등 다양한 항목이 포함되어 있습니다. 이 파일이 잘못 구성되면 앱이 인증되지 않거나 실행 자체가 되지 않을 수 있기 때문에 조심스럽게 다뤄야 합니다.
마지막으로 README.md 파일은 프로젝트의 설명서 역할을 합니다. 앱을 설치하고 실행하는 방법, 구조 설명, 협업을 위한 메모 등이 이곳에 정리됩니다. 실제 코드 실행에는 영향을 주지 않지만 협업 시 매우 중요한 문서이므로 최신 상태를 유지하는 것이 좋습니다.
이처럼 루트 폴더에 있는 설정 파일들은 단순한 보조 도구가 아니라, 앱이 제대로 작동하도록 해주는 핵심적인 구성 요소입니다. 각 파일의 역할을 이해하고, 실수로 삭제하거나 잘못 편집하는 일이 없도록 주의하면서 개발을 진행해야 합니다.
이제 아래의 표를 통해 각 파일의 이름, 기능, 주요 설정 내용, 그리고 주의할 점까지 구체적으로 확인해보시기 바랍니다.
| 파일 이름 | 설명 | 주요 내용/역할 | 주의 사항 |
|---|---|---|---|
| package.json | Node.js 프로젝트의 핵심 설정 파일로, 앱 이름, 의존성 라이브러리, 실행 명령어 등을 정의합니다. | dependencies, scripts, name, version, devDependencies 등이 포함되어 있습니다. |
수정 시 오타나 버전 충돌로 앱이 실행되지 않을 수 있으며, 직접 수정할 때는 주의가 필요합니다. |
| remix.config.js | Remix 프레임워크의 작동 방식을 설정하는 파일입니다. | appDirectory, ignoredRouteFiles, serverBuildTarget 등 앱의 경로 및 빌드 방식 정의 |
경로가 잘못 설정되면 앱이 로드되지 않거나, 라우팅에 오류가 발생할 수 있습니다. |
| tsconfig.json | TypeScript를 사용할 경우 컴파일 규칙을 정의하는 설정 파일입니다. | 코드 검사, 모듈 시스템, 변환 대상 디렉터리 등을 설정합니다. | 대상이 잘못되면 타입 오류가 발생하거나 빌드가 실패할 수 있습니다. |
| .env | API 키, 비밀키 등 민감한 정보를 저장하는 환경 변수 파일입니다. | Shopify API key, secret, SCOPES, SHOP, DATABASE_URL 등 저장 | 절대 깃허브에 업로드해서는 안 되며 .gitignore에 반드시 포함되어야 합니다. |
| .gitignore | Git 버전 관리에서 추적하지 않을 파일이나 폴더를 지정하는 파일입니다. | node_modules, .env, .DS_Store 등 불필요한 파일 제외 |
중요한 파일이 실수로 누락되지 않도록 주의해야 합니다. |
| shopify.app.toml | Shopify CLI가 사용하는 앱 설정 파일로, 앱 이름, URL, 확장 기능 등을 정의합니다. | name, scopes, build, extensions, webhooks, auth 등 설정 포함 |
잘못 수정하면 CLI 실행이나 앱 인증이 실패할 수 있습니다. |
| README.md | 앱에 대한 소개와 실행 방법을 적은 문서 파일입니다. | 설치 방법, 구조 설명, 실행 예시 등 포함 | 기술적 오류는 없지만, 문서 내용은 항상 최신 상태로 유지하는 것이 좋습니다. |
