이 확장은 내 사이트 소스를 내 컴퓨터에서 고치고, 눈으로 확인한 뒤, 올리는 것까지를 돕습니다. 왼쪽 잘커라 아이콘을 누르면 자주 쓰는 항목이 나옵니다. F1(명령 팔레트)에서 “잘커라”로 검색하면 전부 나옵니다 — 「미리보기 다시 시작」처럼 팔레트에만 있는 것도 있습니다.

처음 한 번만 하는 것

1. 로그인

「로그인」을 누르면 브라우저가 열립니다. 평소 잘커라 콘솔에 쓰시는 계정 그대로입니다. 브라우저에서 승인하면 편집기로 돌아옵니다.

「로그아웃」하시면 이 컴퓨터의 로그인을 서버에서도 끊습니다. 다른 컴퓨터의 로그인은 그대로입니다.

2. 사이트 고르기

「사이트」 아래 줄을 눌러 작업할 사이트를 고릅니다. 사이트가 여럿이면 여기서 바꿔 가며 씁니다. 고른 사이트는 그룹 이름 옆에 흐린 글씨로 늘 보입니다.

3. 소스 가져오기 — 넷 중 하나

순서가 아니라 택일입니다. 지금 상황에 맞는 하나만 고르시면 됩니다.

  언제
소스 다운로드 지금 사이트에 올라가 있는 소스를 빈 폴더로 내려받아 이어서 고친다.
예제 zip 다운로드 아직 소스가 없다. 예제를 zip 파일로 받아 「zip 으로 시작」으로 푼다.
zip 으로 시작 개발사·AI 에게 받은 zip 이 있다. 그것을 빈 폴더에 푼다.
사이트에 연결 이미 가지고 있는 소스를 이 사이트에 붙인다(파일은 안 움직입니다).

「zip 다운로드」 둘은 파일 하나로 옵니다. 폴더에 풀리는 것은 「소스 다운로드」와 「zip 으로 시작」입니다.

빈 폴더에 받습니다. 이미 파일이 있는 폴더에는 받지 않습니다 — 고치던 것을 덮어쓰지 않기 위해서입니다. (편집기가 만든 .vscode 폴더와, 저희 연결 표시만 든 .zalkera 폴더만 있는 폴더는 빈 폴더로 봅니다.)

AI 에게 시켜 고치기 — 먼저 하나 깔아야 합니다

말로 고치시려면 AI 편집기 확장이 하나 더 필요합니다. 잘커라 확장은 소스를 받고 보여 주고 올리는 일을 하지, 소스를 고치지는 않습니다. 고치는 것은 AI 몫입니다.

셋이 각각 다른 층이라 헷갈리기 쉬운데, 이렇게 나뉩니다.

  하는 일
잘커라 확장 (이 확장) 소스 받기 · 미리보기 · 배포 · 이전 버전으로 되돌리기
AI 확장 (Claude Code / Codex) 소스를 읽고 고칩니다
내 데이터 보여 주기 AI 가 서버에 붙는 통로 — 조회 · 소스 고치기 · 발행

어느 것을 깔까요

둘 중 아무거나 하나면 됩니다. 이미 쓰시는 구독이 있으면 그쪽이 낫습니다.

  설치 로그인
Claude Code 확장 탭에서 Claude Code 검색 Anthropic 계정 (Pro / Max 구독에 포함)
Codex 확장 탭에서 Codex 검색 ChatGPT 계정 (Plus / Pro 구독에 포함)

둘 다 까셔도 충돌하지 않습니다. 서로 다른 아이콘으로 나란히 뜨고, 같은 폴더를 각자 읽습니다. 하나로 고치고 다른 하나에게 검토시키는 식으로 쓰셔도 됩니다.

⚠ 「내 데이터 보여 주기」는 지금 Claude Code 형식으로만 적어 드립니다(폴더의 .mcp.json). Codex 로 그 연결을 쓰시려면 지금은 손으로 설정하셔야 합니다. 소스를 읽고 고치는 것은 둘 다 됩니다 — 그쪽은 폴더만 있으면 되고, 저희가 규약 파일을 두 벤더 모두에 맞춰 둡니다.

AI 이용료는 잘커라와 무관합니다. 쓰시는 분 구독으로 돕니다. 그래서 어떤 AI 를 쓰시든, 아예 AI 없이 직접 고치시든, 그다음 흐름은 똑같습니다. 저희 도구에 묶이지 않습니다.

실제로 하는 모습

  1. 잘커라 확장 → 소스 다운로드
  2. 잘커라 확장 → 미리보기 시작 — 열린 브라우저 탭은 그대로 두십시오
  3. AI 에게 말합니다 — “메인 페이지 큰 제목을 ‘이번 주 신상 입고’로 바꿔줘”
  4. AI 가 파일을 고쳐 저장하면 브라우저가 알아서 바뀝니다
  5. 마음에 들 때까지 3–4 를 반복합니다
  6. 잘커라 확장 → 배포 전 검사 → 새 버전 배포 → 사이트에서 확인

3–4 를 오가는 것이 실제 작업입니다. 이 흐름에서 AI 는 파일만 고칩니다 — AI 확장은 사장님 컴퓨터의 폴더만 알지 잘커라 서버를 모르기 때문입니다. 배포는 6에서 사장님이 누르십니다.

⚠ 「내 데이터 보여 주기」를 켜시면 달라집니다. 그때부터 AI 가 서버에 붙어 소스를 고치고 발행까지 합니다(아래 그 절 참조). 배포를 손에 두고 싶으시면 그 문을 안 여시면 됩니다.

매일 쓰는 흐름

   고친다  →  미리보기 시작  →  배포 전 검사  →  새 버전 배포  →  사이트 확인

미리보기 시작

내 컴퓨터에서 사이트를 띄우고 실제 브라우저 탭으로 엽니다. 편집기 안 미리보기 창이 아닌 이유는, 그 창은 쿠키와 보안 정책이 실제 탭과 달라 “여기선 됐는데 올리니 다르다”가 생기는 자리이기 때문입니다.

첫 실행은 몇 분 걸립니다. 사이트를 띄우는 데 필요한 부품(의존성)을 처음 한 번 받아 두기 때문입니다. 두 번째부터는 빠릅니다. 진행 중에 또 누르셔도 두 개가 뜨지는 않습니다.

준비하는 동안에는 로그아웃과 초기화가 잠시 거절됩니다. 준비가 끝나면 다시 하실 수 있습니다 — 로그아웃한 뒤에 미리보기가 뒤늦게 뜨는 일이 없게 하기 위해서입니다.

준비가 시간 안에 끝나지 않으면 뜨다 만 서버까지 정리하고 알려 드립니다. 안 떴다고 알린 것이 뒤에서 계속 도는 일은 없습니다.

자리를 비우실 때는 「미리보기 중지」를 눌러 주십시오. 미리보기는 상용 데이터를 읽습니다.

중지는 내 컴퓨터의 서버를 멈춥니다. 미리보기용 서버 열쇠는 그것으로 사라지지 않고 유효기간 (최대 12시간)까지 삽니다 — 지금 바로 없애시려면 로그아웃하십시오. 그때 받아 둔 열쇠를 전부 폐기합니다. 「미리보기 다시 시작」은 중지와 시작을 한 번에 합니다.

소스를 고치고 저장하면 브라우저가 알아서 바뀝니다. 미리보기를 다시 시작할 필요 없습니다.

배포 전 검사

올리기 전에 짚을 만한 것을 알려 줍니다. 조언입니다 — 올리기를 막지 않습니다. 경고가 있어도 올리실 수 있고, 판단은 쓰시는 분 몫입니다.

새 버전 배포

지금 폴더의 소스를 묶어 잘커라에 올리고, 그것으로 사이트를 바꿉니다.

이 단추가 곧 배포입니다. 올린 소스는 방문자가 보는 사이트가 됩니다. 누르기 전에 「미리보기 시작」으로 확인해 주십시오 — 확인하실 자리는 그곳입니다.

되돌리실 수 있습니다. 「버전」의 버전 전환에 지난 판이 나오고, 고르시면 사이트가 그 판으로 돌아갑니다.

확인창이 어느 사이트를 바꾸는지 먼저 알려 드립니다. 여러 사이트를 다루실 때 꼭 확인해 주십시오.

정적 사이트는 올리는 즉시 게시됩니다. Next 소스는 서버가 먼저 만들고(사이트 종류에 따라 몇 분), 만드는 데 성공하면 그때 게시됩니다. 편집기가 그동안 진행을 보여 주고, 끝나면 알려 드립니다 — 사이트 주소를 아는 경우에는 그 주소가 적힌 열기 단추(「내-사이트.zalkera.com」 열기)도 함께 드립니다 — 어디로 가는지 보시고 누르시라고 주소를 단추에 씁니다.

  • 방문자에게 반영되기까지 잠시 걸립니다. 눌러서 바로 안 바뀌어 보이면 조금 뒤 새로고침해 보십시오.
  • 사이트 주인이 서빙을 중단해 둔 사이트에 위임받은 계정으로 올리시면, 새 버전은 만들어지지만 손님 화면은 그대로입니다 — 켜는 것은 사이트 주인만 할 수 있고, 무엇을 해야 하는지는 서버 안내가 말합니다. 그때는 게시됐다고 알리지 않고 그 안내를 그대로 보여 드립니다.
  • 올리는 중에 그만두실 수 있습니다. 보내는 도중에 멈추시면 새 버전은 만들어지지 않습니다 — 사이트도 그대로입니다.
  • 다만 서버가 확인을 시작한 뒤에 누르시면 그 버전이 만들어졌을 수 있습니다. 그때는 기다리기만 그만두는 것이라, 이미 게시된 버전이면 그렇게 알려 드리고 아직 만드는 중이면 준비되는 대로 게시됩니다. 결과를 못 받았으면 단정하지 않고 연결 오류로 알려 드립니다.
  • 기다리는 창의 취소는 기다리기만 그만두는 것입니다. 빌드는 서버에서 계속되고 끝나면 게시됩니다 — 다만 그 사이에 다른 판을 올리시면 그쪽이 켜집니다.
  • 서버가 만들지 못하면(소스에 문제가 있으면) 이유를 알려 드립니다. 그때는 사이트가 그대로입니다 — 실패한 버전이 손님에게 가지는 않습니다.

🔴 AI 가 서버에서 고쳐 둔 것이 있으면 올리기가 막힙니다.

「내 데이터 보여 주기」를 켜 두고 AI 에게 소스를 고치게 하시면, 그 편집은 발행 전 상태로 서버에 쌓입니다. 그 상태에서는 「새 버전 배포」도 「버전 전환」도 거절됩니다 — 「아직 발행하지 않은 편집이 있어 올릴 수 없습니다」라고 나옵니다.

처분하는 길이 둘입니다: 그 편집을 새 버전으로 발행하거나, 편집을 되돌리기. 잘커라 콘솔의 「사이트 소스」 화면에서, 또는 사이트에 연결한 AI 에게 말해서 하실 수 있습니다.

⚠ 사이드바는 그 상태를 미리 보여 주지 않습니다 — 누르셔야 알게 됩니다.

올릴 때 빼는 것이 있습니다. 사이트가 되는 데 필요 없거나, 올라가면 안 되는 것들입니다.

  무엇
부품·산출물 node_modules · .next · dist · out · .turbo · .vercel — 서버가 다시 만듭니다
비밀 .env 로 시작하거나 .env 로 끝나는 파일(.envrc · .env~ 포함 · 값이 빈 .env.example 류는 예외) · .pem .key .p12 .pfx .p8 · .netrc _netrc · .git-credentials · .npmrc · .yarnrc.yml · credentials.json · service-account*.json · *firebase-adminsdk*.json · SSH 키(id_rsa id_dsa id_ecdsa id_ed25519)
편집기·도구 설정 .vscode · .idea · .mcp.json · .claude · .git
저희가 만든 표식 .zalkera 안의 기록 파일들 — 이 폴더가 어느 버전에서 왔는지 적어 둔 자리입니다. 폴더째 빠지지는 않습니다(그 안의 라이선스 고지 같은 것은 실립니다)
자격증명 폴더 .ssh · .aws — 폴더째 빠집니다
OS 부스러기 .DS_Store

표는 자주 보시는 것만 적었습니다 — 실제로는 kubeconfig · secrets.json · .pgpass 처럼 표에 없는 이름도 빠집니다.

비밀로 판단해 뺀 것은 이름을 알려 드립니다. 「출력」 패널의 잘커라 채널에 남습니다 (많으면 앞의 몇 개만 대고 나머지는 셉니다). 다만 node_modules · .vscode · .ssh 처럼 언제나 빠지는 것은 목록에 안 적힙니다 — 목록이 짧다고 적게 빠진 것은 아닙니다. 이름만 비슷할 뿐 비밀이 아닌 파일(예: turkey.key)이 빠졌다면 이름을 바꿔 다시 올리십시오 — 규칙을 느슨하게 하는 것보다 그쪽이 안전합니다. 폴더도 마찬가지입니다 — config.env 같은 이름의 폴더는 통째로 빠지고, 그것도 이름을 알려 드립니다.

⚠ .env.example·.env.sample·.env.template 은 값이 비어 있으면 그대로 실립니다. 채워 넣으라고 배포하는 안내문이라 소스의 일부입니다.

다만 그 안에 실제 열쇠를 채워 두시면 그 파일은 빠집니다 — 알려진 형식(잘커라 열쇠·AWS· 개인키·결제 라이브 키 등)을 값 자리에서 찾으면 이름과 이유를 알려 드리고 뺍니다. 주석으로 가려 두셔도 마찬가지입니다. 열쇠는 .env.local 에 두시고, 예시 파일은 비워 두십시오.

이 자리들을 고치기 시작하시거나 열어 보시면 한 번 알려 드립니다. 막지는 않습니다 — 소스는 손님 것입니다. 여는 것도 보는 이유는, 쓰시는 AI 가 파일을 직접 고쳐 두었을 때 손님이 그것을 아실 기회가 그때뿐이기 때문입니다. 다만 되돌리기 어려운 자리라 처음 손대실 때 한 번만 말씀드립니다(같은 조언이 반복해서 뜨지 않습니다). 자격증명(.env) 안내는 사이트마다 한 번씩 나오고, 나머지 둘은 기계에서 한 번입니다. 다시 보고 싶으시면 초기화를 누르시면 기록이 지워집니다.

왜 .vscode 와 .mcp.json 까지 빼나요. 둘 다 저희가 만드는 파일이고, 그 안에는 어느 사이트로 작업 중인지와 연결하신 AI 도구 설정이 들어 있습니다. 사이트가 되는 데는 쓰이지 않는데, 소스에 실려 나가면 그 소스를 받아 여신 분의 편집기가 엉뚱한 사이트를 가리킬 수 있습니다.

이름이 비슷할 뿐인 평범한 소스(environment.ts, keyboard.ts 같은)는 그대로 올라갑니다.

서버 쪽이 앞서 나갔을 때 — 다시 받기

받은 폴더에는 저희가 파일 둘을 넣어 둡니다. 둘 다 올릴 때는 빠집니다.

파일 무엇
.vscode/settings.json 이 폴더가 어느 사이트인지 — 열면 바로 이어집니다
.zalkera/source.json 어느 버전에서 왔는지 — 같은 판을 또 받으려 할 때 알려 드리는 근거입니다

이미 settings.json 을 쓰고 계시면 그 안의 다른 설정은 그대로 두고 사이트 항목만 더합니다. 주석이 섞여 있거나 읽을 수 없으면 아무것도 쓰지 않고 알려 드립니다 — 그때는 새 폴더를 연 뒤 「사이트에 연결」을 한 번 눌러 주세요.

콘솔에서 고쳤거나, 다른 컴퓨터에서 올렸거나, AI 가 새 판을 만들었으면 서버가 내 폴더보다 앞서 있습니다. 그럴 때 잘커라: 소스 다운로드 를 다시 쓰시면 됩니다. 처음 받을 때와 같은 명령입니다.

소스가 들어 있는 폴더는 바뀌지 않습니다. 받기는 빈 폴더로 갑니다 — 옆에 새 폴더를 만들어 드리고(예: 내사이트-v13), 거기로 받습니다. 그 이름이 이미 있으면 비켜서 다른 이름을 씁니다.

빈 폴더를 열어 두셨다면 그 폴더에 바로 받으시겠는지 먼저 여쭙습니다 — 새 폴더를 따로 만드실 필요가 없습니다. 「사이트에 연결」만 해 둔 빈 폴더도 같습니다. 같은 판을 이미 받아 두셨으면 그 사실을 먼저 알려 드립니다.

받은 폴더는 그 사이트에 미리 연결해 둡니다. 폴더를 열면 바로 이어집니다.

고치시던 것은 옛 폴더에 그대로 남습니다. 두 폴더를 합쳐 드리지는 않습니다 — 필요한 파일은 직접 옮기십시오. 안 쓰는 폴더는 지우셔도 됩니다. 서버에 남아 있는 판은 언제든 다시 받을 수 있습니다.

AI 연결은 따라오지 않습니다. 새 폴더에서 AI 연결 → 내 데이터 보여 주기 를 한 번 더 눌러 주세요.

사이드바의 내려받기 셋 — 「소스 다운로드」·「소스 zip 다운로드」·「예제 zip 다운로드」 — 은 파일로 받거나 빈 폴더로 갑니다. 소스가 들어 있는 폴더는 안 건드립니다.

소스가 들어 있는 폴더를 덮어쓰는 것은 작업 폴더 묶음뿐이고, 그중 둘입니다 — 「zip 으로 교체」와 「서버 판으로 교체」. 재료만 다릅니다.

아직 안 되는 것도 메뉴에는 보입니다

사이드바의 묶음 — 사이트 · 미리보기 · AI 연결 · 배포 · 내려받기 · 작업 폴더 · 버전 · 도움 — 은 언제나 보입니다. 소스를 아직 안 받으셨어도 묶음과 단추는 그대로입니다 — 상태를 알려 드리는 줄만 그때그때 답니다.

아직 안 되는 것을 누르시면 무엇이 필요한지 알려 드리고, 그 자리로 가는 단추를 함께 드립니다. 예를 들어 소스가 없을 때 「미리보기 시작」을 누르시면 무엇이 필요한지 말씀드리고 소스 다운로드 단추를 함께 드립니다.

메뉴가 상황에 따라 나타났다 사라지면, 안 보일 때 설치가 잘못된 것으로 읽힙니다. 그래서 있다는 것은 늘 보이고, 안 되는 이유는 누르실 때 말씀드립니다.

버전

맨 위 두 줄이 지금 서버에 켜져 있는 것과 지금 로컬 폴더를 나란히 보여 드립니다.

서버 — 969a61e0 / 버전 4
로컬 — 969a61e0
  • 앞의 여덟 글자가 그 판에 담긴 소스를 가리킵니다. 두 줄의 글자가 같으면 같은 소스입니다 — 지금 「새 버전 배포」를 누르시면 같은 소스를 한 번 더 올리는 셈입니다.
  • 버전 4 는 올릴 때마다 1씩 느는 번호입니다. 언제 올렸는지만 말하고 무엇이 담겼는지는 말하지 않습니다 — 되돌리시면 번호는 새것인데 앞의 여덟 글자는 그대로입니다. 게시하실 때 뜨는 안내와 콘솔 버전 목록이 말하는 번호가 이것과 같습니다.
  • 줄 앞 표시: 체크 같음 · 연필 다름 · 폴더 아직 대조할 수 없음.
  • 지문 없음 이 보이는 경우는 둘입니다.
    1. 그 판이 이 기능이 생기기 전에 올라갔습니다.
    2. 저희가 지문 규칙을 바꾼 뒤 그 판을 아직 다시 세지 않았습니다 — 곧 채워집니다.

    둘 다 한 번 더 올리시면 그때부터 대조됩니다.

  • 로컬 줄에는 그 번호가 없습니다 — 올릴 때 서버가 붙여 주는 것이라 아직 올리지 않은 폴더는 가질 수 없습니다.

「버전」 옆에 결론이 한 낱말로 적힙니다.

  • 「일치」 — 이 폴더와 서버가 같은 소스입니다. 지금 올리셔도 사이트는 안 바뀝니다.
  • 「수정 중」 — 마지막으로 맞추신 뒤 이 폴더를 고치셨습니다.
  • 「서버가 더 최신」 — 서버에 켜진 판이 이 폴더 내용보다 버전 목록에 나중에 나타난 것입니다.
  • 「로컬이 더 최신」 — 이 폴더 내용이 서버에 켜진 판보다 버전 목록에 나중에 나타난 것입니다.
  • 「다름」 — 두 소스가 다릅니다. 어느 쪽이 나중인지는 알 수 없습니다.
  • 「확인 필요」 — 아무것도 안 고치셨는데 서버와 다릅니다. 도구 쪽 사정일 수 있습니다.
  • 「대조 불가」 — 서버 판에 지문이 없어 견줄 수가 없습니다.
  • 「확인 중」 — 이 폴더를 다시 세고 있습니다.

「나중」은 올린 순서가 아니라 버전 목록에 그 내용이 처음 나타난 자리입니다. 되돌리시면 큰 번호에 옛 내용이 들어가기 때문입니다 — 「버전 5」인데 내용은 3번 때 것일 수 있습니다. 번호만 보고 판단하지 않으시도록 그 경우에는 줄에 · 3번 내용 그대로 를 함께 적습니다.

  • 「더 최신」은 두 줄 사이의 이야기입니다. 올려 두고 아직 켜지 않은 버전이 있으면 그것은 이 비교에 안 들어갑니다.
  • 버전 5 · 3번 내용 그대로 처럼 적히면, 5번으로 올라간 그 판의 내용이 3번 때 올린 것과 같다는 뜻입니다. 5번을 3번으로 «빌드했다»는 뜻이 아니라, 그 둘에 담긴 소스가 같다는 뜻입니다. 되돌리셨을 때 그렇게 됩니다. 「되돌렸다」가 아니라 「내용이 같다」로 적는 이유는, 같은 소스를 한 번 더 올리셔도 값이 같아지기 때문입니다.
  • 로컬 — … / 4번 내용 그대로 는 이 폴더가 4번 판과 같은 내용이라는 뜻입니다.
  • 지문이 없는 옛 판이 사이에 있으면 방향을 말씀드리지 않습니다. 그 판이 무엇이었는지 모르는 채로 순서를 말하면 틀릴 수 있어서, 그때는 「다름」까지만 적습니다.
  • 어느 쪽으로 맞추실지는 사장님이 정하십니다 — 이 폴더 것을 올리시려면 「새 버전 배포」, 서버 것을 가져오시려면 「서버 판으로 교체」입니다.

올린 직후 「포장 갭」이라는 안내가 뜨면 그것은 사장님 잘못이 아닙니다. 저희 도구가 예상한 값과 서버가 저장한 값이 다르다는 뜻이고, 도구 쪽 문제입니다. 「자세히」를 누르시면 두 값이 나옵니다 — 그대로 알려 주시면 고치겠습니다. 올리신 것 자체는 정상으로 끝났습니다.

  • 버전 이력 — 지금까지 올린 버전을 봅니다. ▶ 표시가 지금 켜져 있는 버전입니다. 읽기만 합니다. 아무것도 바뀌지 않습니다.

  • 버전 전환 — 켜져 있지 않은 판 중 하나를 골라 사이트를 그 판으로 바꿉니다. 지금 켜져 있는 판은 목록에 없습니다. 누르면 방문자가 보는 화면이 바로 바뀝니다.

    목록에는 켤 수 있는 버전만 나옵니다. 아직 만들어지는 중이거나 실패한 버전은 보이지 않습니다 — 고를 수 없는 것을 보여 주고 나서 거절하지 않으려고 그렇게 했습니다.

    앞으로 가는 것과 뒤로 가는 것이 같은 일이라 하나로 두었습니다. 어제 판으로 물러나는 것도, 물러났다가 다시 앞 판으로 오는 것도 여기서 합니다. 지금 켜져 있는 버전은 목록에 나오지 않습니다 — 이미 그것이기 때문입니다.

소스를 zip 으로 주고받기

개발사에서 사이트 소스를 zip 으로 받으셨다면 「zip 으로 시작」을 쓰십시오. 압축을 손으로 푸실 필요가 없습니다 — 빈 폴더를 고르시면 거기에 바로 풀리고, 맥에서 만들어지는 부스러기나 한 겹 더 감싸인 폴더도 알아서 정리합니다. 사이트 소스가 아니면 풀지 않고 말씀드립니다.

한글 파일 이름이 든 zip 은 멈출 수 있습니다. zip 은 파일 이름의 인코딩을 표시하게 돼 있는데, 그 표시가 없으면 저희는 추측해서 풀지 않고 멈춥니다. 압축 도구에 따라 표시를 안 남기는 것이 있습니다.

그때는 파일 이름을 영문으로 바꾸시면 확실히 됩니다. 다른 압축 도구로 다시 압축해도 됩니다.

추측하지 않는 이유는, 이름을 잘못 읽으면 이미지가 안 뜨는데 원인이 화면에 안 보이기 때문입니다. 멈추는 편이 낫습니다.

새 판을 다시 받으셨다면 — 「zip 으로 교체」

개발사가 고친 zip 을 다시 보내오면, 폴더를 손으로 비우지 마시고 명령 팔레트에서 「zip 으로 교체」를 부르십시오. 지금 열려 있는 폴더를 그 zip 으로 갈아 끼웁니다.

  • 그대로 두는 것: .git · .env · .env.local 같은 실제 환경 파일 · .vscode · .idea · .ssh · .aws · .npmrc · .mcp.json · .claude · 인증서 파일. 받으신 zip 에는 이것들이 없으므로(포장할 때 일부러 뺍니다) 건드리지 않습니다. 무엇을 남기는지는 확인 창에 그때그때 계산해서 보여 드립니다.
  • ⚠ .env.example 류는 남기지 않습니다 — 소스의 일부라 받으신 zip 의 것으로 바뀝니다. 그 zip 에 없으면 사라집니다. 값을 채워 쓰시던 것이면 .env.local 로 옮겨 두십시오.
  • 다시 만들어지는 것은 지웁니다: node_modules · .next 등. 남기면 옛 의존이 새 소스에 섞여 미리보기가 원인 없이 깨질 수 있습니다.
  • 사라지는 것: 그 밖의 모든 파일. 로컬에서 직접 고치신 것이 있으면 먼저 빼 두십시오.
  • 폴더 바로 아래만 지킵니다 — 하위 폴더 안의 .env.local 같은 것은 못 지킵니다.

출처 표시 — 이 zip 이 어느 사이트 것인가

여러 사이트를 다루시면 다른 사이트의 zip 을 잘못 넣는 사고가 가장 큽니다. 그래서 갱신은 확인 창에서 먼저 말씀드립니다.

보이는 글 뜻 하실 일
이 사이트에서 내보낸 소스로 표시되어 있습니다 표시가 이 폴더의 사이트와 같습니다 그대로 진행
⚠ 다른 사이트에서 내보낸 것으로 표시되어 있습니다 표시가 다릅니다 멈추고 확인하십시오 — 버튼 문구도 바뀝니다
출처 표시 없음 — 도구는 알 수 없습니다 표시가 아예 없습니다 파일 이름과 보낸 곳으로 직접 확인

「표시 없음」은 흔하고 정상입니다. 시작 소스 팩에서 만든 소스에는 표시가 없습니다. 받은 zip 을 잘커라 확장으로 풀면 그 파일이 디스크에 안 남으므로, 그 폴더를 다시 묶어도 표시가 없습니다(범용 압축 도구로 푸셨다면 남아서 따라갈 수 있습니다). 없다고 잘못된 zip 이라는 뜻이 아닙니다 — 도구가 대신 봐 줄 수 없으니 사람이 본다는 뜻입니다.

그리고 표시는 선언이지 증명이 아닙니다. 「일치」가 떠도 그건 「그렇게 적혀 있다」까지입니다.

표시는 「zip 으로 내보내기」와 「새 버전 배포」가 찍습니다. 연결 안 된 폴더에서 내보내면 안 찍습니다 — 없는 정체성을 지어내지 않습니다. 이 표시는 소속이 아니라서, 받아서 푸신 분의 확장이 그 사이트로 끌려가는 일은 없습니다.

  • 서버 판으로 교체는 같은 일을 하되 재료가 서버에 켜져 있는 판입니다. zip 을 따로 받아 두실 필요가 없고, 갈아 끼운 뒤 이 폴더의 버전 표시도 그 판으로 맞춰 드립니다.
  • 「서버 판으로 교체」의 확인 창에는 「zip 으로 내보내기 먼저」 단추가 있습니다 — 지금 폴더를 챙겨 두고 싶으실 때 누르시면 내보내기로 가고, 갈아 끼우지는 않습니다. ⚠ 「zip 으로 교체」에는 그 단추가 없습니다. 챙겨 두시려면 먼저 「zip 으로 내보내기」를 누르신 뒤에 교체하십시오.
  • 「서버 판으로 교체」에서, 이 폴더가 이미 서버와 같은 버전으로 표시돼 있으면 확인 창의 첫 줄이 그 사실을 말씀드립니다. 막지는 않습니다 — 폴더가 망가져 같은 판을 새로 받으실 때는 그대로 진행하시면 됩니다. 그때 사라지는 것은 그 판 위에서 손대신 내용입니다.
  • 갈아 끼우다 실패로 멈추면 원래 소스로 되돌립니다. 되돌리기까지 실패하면 원래 소스가 어디 있는지 알려 드립니다. 다만 갈아 끼우는 중에 창을 닫거나 편집기가 꺼지면 그 되돌리기가 돌지 못합니다 — 폴더 옆에 .zalkera-stash- 로 시작하는 숨은 폴더가 남고 원래 소스가 그 안에 있습니다. 그런 폴더가 있으면 창을 열 때 저희가 알려 드립니다. 다만 지워 드리지는 않습니다 — 그 안이 원래 소스의 유일한 사본일 수 있어서, 옮기실 것을 옮기신 뒤 사람이 지우는 편이 안전합니다.
  • 사이트 소속은 지켜지므로 갱신 뒤에 「사이트에 연결」을 다시 하실 필요가 없습니다.

사이드바 「작업 폴더」 묶음에 있습니다. 명령 팔레트에서도 부르실 수 있습니다.

지금 어느 폴더로 일하고 있나

「작업 폴더」 묶음 이름 옆에 그 폴더가 적혀 있습니다. 묶음을 접어 두셔도 보입니다. 마우스를 올리시면 경로가 나옵니다(아주 긴 경로는 뒤가 잘립니다). 열어 두신 폴더가 없으면 「열린 폴더 없음」이라고 적힙니다.

저희가 「이 폴더」라고 말씀드리는 곳들 — 「사이트에 연결」, 「새 버전 배포」 확인 창 — 이 가리키는 것이 바로 그 폴더입니다.

다른 폴더로 옮기기

「작업 폴더 변경」을 누르시면 이 창을 다른 폴더로 옮깁니다. 받아 두신 폴더를 저희가 알고 있으면 그것부터 보여 드리고, 아니면 폴더를 고르는 창이 열립니다.

이 단추는 아무것도 적지 않습니다. 폴더가 어느 사이트 것인지를 바꾸는 것은 「사이트에 연결」 하나입니다. 옮기기만 하고 소속은 그대로 둡니다.

처음 받은 소스를 사이트에 붙이기

푼 다음에는 폴더를 열고 「사이트에 연결」로 어느 사이트의 소스인지 알려 주십시오. 그때부터 미리보기·올리기가 되고, 그 폴더가 자기 사이트를 기억합니다.

「사이트 선택」 화면에서 「받은 zip 으로 시작」으로 오신 경우에는 저희가 그 사이트로 적어 둡니다 — 그 화면에서 사이트를 고르셨기 때문입니다. 결과는 완료 알림이 말해 드립니다: 붙었으면 폴더만 열어 주시면 되고, 고르신 폴더가 이미 다른 사이트에 연결돼 있으면 소속을 바꾸지 않고 그 사실을 알려 드립니다.

반대로 소스를 넘기실 때는 「zip 으로 내보내기」를 쓰십시오.

폴더를 그냥 압축해서 보내지 마십시오. .env.local 에는 미리보기 열쇠가 들어 있어, 받는 쪽이 그 열쇠로 사이트 데이터에 닿을 수 있습니다. 「zip 으로 내보내기」는 그런 파일과 node_modules 같은 빌드 부스러기를 빼고 담습니다. 무엇이 빠졌는지는 출력 패널에 적힙니다.

다만 저희가 발급한 열쇠와 널리 쓰이는 자격증명 파일 이름까지가 저희가 아는 범위입니다. 고객님이 직접 만드신 이름(예: config/secrets.yaml)은 저희가 알 수 없으니, 넘기시기 전에 출력 패널의 목록을 한 번 봐 주십시오. 올릴 때 빠지는 것과 같은 기준입니다.

여러 사이트를 다루실 때

소스를 받으신 폴더는 그 사이트의 것으로 기억됩니다. 그 뒤로는 폴더가 자기 사이트를 압니다. (발행하신 폴더, 「사이트에 연결」로 이으신 폴더도 같습니다. 예제 zip 다운로드만 하신 폴더는 아직 어느 사이트의 것도 아닙니다 — 처음 올리실 때 정해집니다.)

그래서 사이트를 바꾸는 것은 폴더를 바꾸는 일입니다. 「사이트 선택」으로 다른 사이트를 고르시면 지금 열린 폴더는 그대로 두고, 고르신 사이트로 어떻게 갈지 고르는 화면을 드립니다.

  • 폴더 열기 — 받아 두신 폴더를 저희가 기억하고 있을 때. 그 폴더가 딛고 있는 버전과 서버의 버전이 다르면 두 번호를 함께 보여 드립니다 — 맞추실 때는 「서버 판으로 교체」입니다 (알 수 없을 때는 아무 말도 하지 않습니다)
  • 소스 다운로드 — 빈 폴더로 받습니다. 지금 열어 두신 폴더가 비어 있으면(연결만 해 둔 빈 폴더 포함) 거기로 받자고 여쭙는데, 그 폴더가 다른 사이트에 연결돼 있으면 사이트가 바뀐다는 사실을 먼저 말씀드립니다
  • 로컬본 폴더 직접 고르기 — 받아 두신 폴더를 저희가 못 찾을 때, 직접 알려 주십시오. 그 폴더의 .vscode/settings.json 을 저희가 읽지 못하면(주석이 들어 있는 경우가 그렇습니다) 아무것도 적지 않고 열어 드립니다 — 읽지 못한 것을 저희 값으로 덮지 않기 위해서입니다
  • 받은 zip 으로 시작 — 개발사에서 zip 을 받으셨거나, 아직 올린 소스가 없을 때. 풀 폴더는 소스 폴더를 열어 두셨으면 옆자리를 제안해 드리고(직접 고르셔도 됩니다), 푼 뒤에는 고르신 사이트로 붙여 둡니다 — 「사이트에 연결」을 다시 하실 필요가 없습니다. zip 에 다른 사이트의 출처 표시가 있으면 붙이기 전에 여쭙습니다(막지는 않습니다)

아직 아무것도 올리지 않으신 사이트에는 다운로드가 나오지 않습니다 — 받을 것이 없기 때문입니다. 그때는 zip 으로 시작하시면 됩니다.

폴더를 열지 않은 창(VS Code 를 새 창으로 여신 경우)에서도 같은 화면을 드립니다. 그때는 아직 일할 자리를 안 정하신 것이라, 위와 같은 선택지에서 고르시면 됩니다.

닫으시려면 Esc 를 누르십시오. 폴더는 아무것도 바뀌지 않습니다. 폴더를 열어 두신 창이면 이 창의 사이트도 그대로입니다 — 폴더가 없는 창에서는 방금 고르신 사이트가 그대로 남습니다(사이드바에 보입니다).

상태바 왼쪽 아래에 지금 작업 사이트가 보입니다. 폴더와 고르신 사이트가 다르면 색이 바뀌고, 누르시면 이 폴더의 사이트로 돌아갑니다.

⚠ 미리보기가 도는 동안에는 그 자리를 미리보기가 씁니다 — 사이트 이름도 경고색도 그동안은 안 보입니다. 미리보기를 멈추시면 돌아옵니다.

폴더가 자기 사이트를 아는데 다른 사이트로 미리보기·올리기를 하려 하시면 막고 말씀드립니다. 두 가지 중에서 고르실 수 있습니다.

  • 「이 폴더의 사이트로 돌아가기」 — 이 폴더에서 그대로 계속하실 때. 사이드바에도 나옵니다.
  • 「소스 다운로드」 — 고르신 사이트로 작업하실 때. 빈 폴더로 받습니다.

빈 폴더를 열어 두고 받으시면 그 폴더에 바로 받으시겠는지 먼저 여쭙습니다 — 새 폴더를 따로 만드실 필요가 없습니다. 「로컬본 폴더 직접 고르기」로 빈 폴더를 연결해 두셨다면 그 다음이 「소스 다운로드」입니다.

폴더가 속한 사이트를 정말로 바꾸셔야 하면 「사이트에 연결」을 쓰십시오. 그때는 이 폴더의 소스가 어느 사이트로 올라가게 되는지 먼저 여쭙습니다.

이 표식은 폴더 안 .zalkera/source.json 에 있습니다. 비밀이 아니고, 올리는 꾸러미에는 들어가지 않습니다.

내 데이터 보여 주기 — AI 를 서버에 붙이기

무엇이 달라지나요

AI 는 파일을 이미 읽습니다. 폴더를 열어 뒀으니까요. 이 기능이 여는 것은 파일에 없는 것 — 지금 등록된 상품, 올린 글, 사이트 설정 같은 서버 쪽 데이터와 서버에 있는 소스입니다.

🔴 이름보다 넓은 문입니다. 조회만 열리는 것이 아니라 소스 고치기 · 새 버전 발행 · 이전 판으로 되돌리기가 함께 열립니다. AI 에게 「올려 줘」라고 말씀하시면 손님이 보는 사이트가 그 자리에서 바뀝니다 — 확인을 한 번 더 묻지 않습니다. 잘못 나갔으면 사이드바 「버전 전환」에서 되돌리시면 됩니다.

차이가 이렇게 납니다.

  “상품 목록 페이지 만들어줘” 라고 했을 때
연결 없이 AI 가 그럴듯한 가짜 상품을 지어냅니다. 실제 데이터 모양과 안 맞아 붙이면 깨집니다.
연결 후 AI 가 실제 상품을 조회해서, 그 모양에 맞는 화면을 만듭니다.

한 번만 하면 됩니다

  1. 「AI 연결」 → 내 데이터 보여 주기 를 누릅니다
  2. 폴더에 파일 셋이 생깁니다
    • .mcp.json — 어디에 연결할지
    • AGENTS.md — AI 가 지킬 규약 (정본은 llms.txt 를 가리킵니다)
    • CLAUDE.md — 위 파일을 참조하라는 한 줄
  3. AI 확장을 껐다 켭니다 — 이걸 안 하시면 반영되지 않습니다
  4. AI 가 처음 이 도구를 쓸 때 브라우저 로그인이 한 번 뜹니다 (잘커라 계정입니다)

⚠ 여기서 적어 드리는 .mcp.json 은 Claude Code 형식입니다. Codex 를 쓰시면 이 절차를 그대로 따라가셔도 연결이 안 붙습니다 — 손으로 설정하셔야 합니다. 소스를 읽고 고치는 것은 Codex 도 그대로 됩니다(위 AGENTS.md 가 벤더를 안 가립니다).

그 뒤로는 그냥 말하시면 됩니다.

“지금 등록된 상품 종류를 보고, 그에 맞는 목록 페이지를 만들어줘” “지금 사이트 설정을 보고, 거기 맞춰 소개 페이지를 고쳐 줘”

AI 가 알아서 필요한 도구를 골라 조회합니다.

알아 두실 것

  • .mcp.json 에 열쇠는 안 들어갑니다. 로그인해서 그때그때 받습니다. 그래서 이 파일을 동료와 나눠 가지셔도 안전하고, 각자 자기 계정으로 로그인해 씁니다.
  • 연결은 편의이지 필수가 아닙니다. 연결하지 않고 직접 고쳐 「새 버전 배포」만 쓰셔도 똑같이 동작합니다.

.env.local 은 무엇인가요

미리보기가 내 사이트 데이터를 불러오려면 주소와 열쇠가 필요합니다. 그 다섯 줄이 여기 적힙니다.

칸 뜻
ZALKERA_API_BASE 잘커라 서버 주소
ZALKERA_TENANT 내 사이트 코드
ZALKERA_STOREFRONT_KEY 미리보기용 열쇠 (oqsk_…)
ZALKERA_SITE_URL 사이트 주소
NEXT_PUBLIC_ZALKERA_PREVIEW 미리보기 모드 표시

이 다섯 칸만 확장이 손대고, 직접 적어 두신 다른 줄은 그대로 둡니다.

  • 이 파일은 절대 올라가지 않습니다. 열쇠가 들어 있기 때문입니다.
  • 열쇠는 한 번에 한 대에서만 유효합니다. 다른 컴퓨터에서 미리보기를 켜면 이쪽이 끊깁니다. 알림은 새로 켠 컴퓨터에 뜹니다(“다른 곳에서 켜 둔 미리보기 N개가 해제되었습니다”). 끊긴 쪽에서는 미리보기 화면이 데이터를 못 불러오는 것으로 나타납니다.
  • 열쇠에는 기한이 있습니다. 남은 기한은 사이드바에 보이고, 미리보기를 켜 둔 동안 알아서 갱신됩니다.
  • 로그아웃하면 서버에서 폐기됩니다 — 미리보기를 먼저 멈추셨거나 편집기를 껐다 켜셨어도 마찬가지입니다. 파일에서 그 줄을 지우는 것은 그 폴더를 연 창에서 합니다. 다른 폴더를 연 창에서 로그아웃하면 그 폴더의 줄은 남습니다(이미 폐기된 열쇠라 쓸 수는 없습니다).

git 과 함께 쓰기

소스의 변경 이력을 git·GitHub 로 관리하시는 분을 위한 절입니다. 이 확장은 GitHub 에 접속하지 않고, 커밋·푸시를 만들지 않으며, 누르지 않은 git 명령을 돌리지 않습니다(VS Code 의 Git 확장을 통해 상태를 읽고, 「git 태그 만들기」를 누르셨을 때만 태그를 만듭니다). git 은 VS Code 의 소스 제어(Source Control) 뷰와 GitHub 확장이 하고, 이 확장은 그 옆에서 소스를 받고 올리는 일만 합니다. 둘이 만나는 자리는 아래뿐입니다.

  • .git 폴더를 지우거나 갈아 끼우지 않습니다. 올릴 때 빠지고, 「zip 으로 교체」·「서버 판으로 교체」가 갈아 끼울 때도 자리에 남습니다. 그 안에 쓰는 것은 둘뿐입니다 — .git/info/exclude 에 .zalkera/source.json 한 줄(이 폴더가 레포의 맨 위이고 .git 이 폴더일 때 · 아래), 그리고 누르신 태그.
  • .env.local 은 .gitignore 에 넣어 드립니다. 미리보기를 켤 때와 「새 버전 배포」를 누를 때 그 줄을 보장합니다(.gitignore 가 있으면 그 줄만 더하고, 없으면 폴더에 .git 이 있을 때만 만듭니다). 미리보기 열쇠가 커밋되는 사고를 막는 자리입니다. 그 밖에는 .gitignore 를 만지지 않습니다.
  • .zalkera/source.json 은 커밋하지 마십시오. 이 컴퓨터가 어느 버전에서 왔는지 적어 둔 기록이라, 남의 것이 커밋을 타고 넘어오면 「버전」 묶음이 남의 상태를 내 것으로 말합니다. 시작 소스 팩의 .gitignore 에는 이미 들어 있고, 그 밖의 소스에서는 확장이 이 폴더가 레포의 맨 위이고 .git 이 폴더일 때 .git/info/exclude 에 그 줄을 적어 둡니다(.gitignore 는 안 건드립니다) — 적는 때는 버전 기록을 쓸 때(받기·연결·배포·교체)와 「zip 으로 교체」·「서버 판으로 교체」·「새 버전 배포」를 누를 때입니다. 받은 뒤에 git init 을 하셨다면 그중 하나를 지나기 전까지는 아직 없으니, 첫 커밋 전에 소스 제어 뷰에서 .zalkera/source.json 이 보이면 넣지 마십시오. 레포 맨 위가 이 폴더보다 위(한 레포에 여러 폴더)이거나 .git 이 파일(워크트리)이면 적지 않으니 그때는 직접 .gitignore 에 넣으십시오.
  • 「새 버전 배포」가 올리는 것은 커밋이 아니라 지금 폴더의 파일입니다. 커밋하지 않은 변경도 같이 올라갑니다. 그래서 「zip 으로 교체」·「서버 판으로 교체」·「새 버전 배포」의 확인 창 맨 아래에 git: main @ 1a2b3c4 · 커밋하지 않은 변경 3개 처럼 지금 git 상태를 한 줄 적어 드립니다. 막지는 않습니다 — 「이 커밋이 라이브」라고 말하시려면 커밋한 뒤에 배포하십시오.
  • 깨끗한 상태에서 배포하셨으면 완료 알림에 「git 태그 만들기」 단추가 뜹니다. 누르면 배포한 커밋에 zalkera/내사이트/v5 같은 태그가 생깁니다 — 이 컴퓨터에만 생기고, 원격에 올리는 것은 「태그 푸시」입니다. 커밋하지 않은 변경이 있었으면 단추가 안 뜨고, 배포한 뒤 커밋을 옮기셨거나 고친 것이 있으면 눌러도 만들지 않고 손으로 찍는 명령을 알려 드립니다(그 태그는 라이브가 아닌 커밋을 가리키게 되기 때문입니다). 미추적 파일을 숨기는 git 설정(git.untrackedChanges: hidden)이 켜져 있으면 셀 수 없다고 적고 단추도 안 뜹니다. 누르지 않으면 아무것도 쓰지 않습니다.
  • 편집기 밖에서 바뀐 파일도 알아챕니다. git pull·브랜치 전환·AI 의 직접 쓰기 뒤에도 「버전」 묶음이 「확인 중」을 거쳐 새 결론으로 갑니다 — 저장했을 때와 같습니다. VS Code 설정 files.watcherExclude 로 감시에서 빼 두신 경로는 못 봅니다.
  • git 상태 한 줄은 git 이 보여 주는 만큼입니다. 미추적 파일이나 서브모듈을 숨기는 git 설정 (git.untrackedChanges: hidden · git.ignoreSubmodules)이 켜져 있으면 「셀 수 없음」이라 적고 태그 단추도 안 뜹니다. .gitignore 로 git 이 무시하는 파일은 이 줄에 안 세어지지만 배포에는 올라갑니다.

「서버 판으로 교체」 뒤에 소스 제어 뷰를 보면 서버 판과 내 마지막 커밋의 차이가 그대로 뜹니다 — git 을 쓰시면 남이 올린 판을 받아 보는 가장 편한 길입니다. 다만 .github/workflows/ 아래 파일은 서버가 저장하지 않아 삭제로 뜨니 되살리시면 됩니다. 순서 전체는 사용 매뉴얼(PDF)의 5장 「git · GitHub 와 함께 쓰기」에 있습니다.

확장 자신에 관한 것

새 판이 나오면

확장이 서버와 인사할 때 이 판으로도 되는지 물어봅니다. 더 나은 판이 있으면 알림이 한 번 뜨고, 「업데이트」를 누르시면 VS Code 의 확장 화면에서 이 확장이 열립니다. 설치는 VS Code 가 합니다 — 저희가 파일을 내려받아 갈아 끼우지 않습니다.

  • 같은 소식은 하루에 한 번만 뜹니다. 창을 여러 번 열어도 다시 묻지 않습니다.
  • 새 판이 또 나오면 그때는 바로 알려 드립니다.
  • 계약이 아예 안 맞는 낡은 판이면 알림이 아니라 하던 일이 멈추고 이유를 말합니다. 그때는 업데이트하셔야 이어집니다.

업데이트가 안 될 때

VS Code 는 확장을 스스로 갱신합니다. 새 판이 안 온다 싶으면 이 한 줄로 맞추십시오. 지우지 않으니 안전합니다.

code --install-extension zalkera.zalkera-devtools --force

그래도 그대로면 설정에서 extensions.autoUpdate 를 확인하십시오.

Cursor·Windsurf 같은 포크에는 아직 올리지 못했습니다. 그쪽에서는 .vsix 파일로 까셔야 하고 자동 갱신이 오지 않으니, 새 판이 나오면 파일을 다시 받아 까셔야 합니다.

미리보기가 쓰는 엔진

Node.js 를 따로 까실 필요는 없습니다. 없으면 없는 대로 뜹니다.

이 컴퓨터에 Node.js 가 있으면 미리보기가 더 빠른 엔진(Turbopack)으로 알아서 바뀌고, 없으면 다른 엔진(webpack)으로 뜹니다. 고르실 것은 없습니다.

⚠ 낡은 Node.js 가 깔려 있으면 오히려 안 뜰 수 있습니다. 저희는 그 이름이 잡히는지만 보고 판본은 안 봅니다 — 낡은 것이 잡히면 빠른 엔진이 뽑히는데 그 엔진이 요즘 소스를 못 돌립니다. 미리보기가 안 뜨면 터미널에서 node -v 를 쳐 보십시오.

진단으로는 이것을 못 보십니다. 진단이 적는 Node 는 편집기가 품고 있는 것이라 늘 최신입니다 — 미리보기가 고르는 것은 이 컴퓨터의 PATH 에 잡히는 쪽이고, 그 값은 지금 어디에도 안 보입니다.

어느 npm 으로 설치할까요

의존성을 내려받을 때 쓸 npm 을 고르실 수 있습니다. 설정에서 zalkera.npm 입니다.

값 하는 일
bundled (기본) 확장이 품고 있는 npm 을 씁니다. 컴퓨터에 npm 이 없어도 됩니다.
system 이 컴퓨터에 깔린 npm 을 씁니다. 사내 레지스트리·별도 설정을 쓰실 때.
auto 깔린 npm 이 조건에 맞으면(9 이상) 그것을, 아니면 품은 것을 씁니다.

고른 것을 못 쓰면 말하고 멈춥니다. 조용히 다른 npm 으로 바꿔 돌리지 않습니다 — 그러면 결과만 남고 무엇이 돌았는지 아무도 모릅니다. 지금 무엇을 쓰는지는 진단에 경로까지 나옵니다.

어느 쪽을 고르시든 저희는 찾아 둔 경로를 그대로 실행합니다. 이름(npm)으로 부르면 어느 프로그램이 뜰지를 운영체제가 정하고, 그 탐색은 지금 열어 둔 폴더부터 시작합니다 — 받으신 소스 안에 같은 이름의 파일이 있으면 그것이 돕니다. 그래서 이름으로 부르지 않습니다. 같은 이유로 bundled 로 두시면 이 컴퓨터의 npm 은 찾지도 실행하지도 않습니다.

이 설정은 컴퓨터 단위입니다. 폴더마다 다르게 둘 수 없습니다 — 받아서 여는 소스가 「어떤 프로그램을 실행할지」를 정하면 안 되기 때문입니다.

설치 스크립트는 돌리지 않습니다

의존성을 받을 때 꾸러미가 딸려 보내는 설치 스크립트를 실행하지 않습니다(--ignore-scripts). 그 설치는 방금 받으신 소스 폴더 안에서 돌기 때문에, 그 폴더가 시키는 것은 무엇이든 그대로 실행됩니다.

설치 스크립트가 필요한 꾸러미가 이 프로젝트에 있으면 이름을 대고 알려 드립니다 — 그 꾸러미가 제대로 안 설 수 있습니다.

잘 안 될 때

진단

지금 무엇이 없어서 안 되는지 한 번에 봅니다. 문의하실 때 이 결과를 함께 보내 주시면 가장 빠릅니다.

초기화

처음 상태로 되돌립니다.

  • 지웁니다 — 로그인 · 작업 사이트 설정 · 미리보기 열쇠(서버에서도 폐기)
  • 남깁니다 — 받은 소스 폴더와 그 안의 내용

소스는 지우지 않습니다. 폴더까지 지우고 싶으시면 초기화 뒤 안내에 나오는 「폴더 위치 열기」로 찾아 직접 지우십시오. 도구가 사람 파일을 지우지 않는 편이 낫다고 보아 그렇게 두었습니다.

자주 있는 것

「이 계정에 연결된 사이트가 없습니다」 계정은 맞는데 사이트 소속이 없을 때 나옵니다. 잘커라에 문의해 주십시오.

「받을 폴더가 비어 있지 않습니다」 받으려는 폴더에 이미 파일이 있습니다. 오류 문장이 무엇이 있는지 이름을 말씀드립니다. 빈 폴더를 새로 만들어 그곳에 받으십시오. 그 폴더가 사이트 소스라면, 소스를 그대로 쓰실 때는 「사이트에 연결」, 서버 판으로 바꾸실 때는 그 폴더를 열고 「서버 판으로 교체」입니다.

미리보기가 안 열립니다 첫 실행이면 몇 분 기다려 주십시오. 그 뒤에도 안 되면 「진단」을 먼저 보십시오. 아래 「출력」 패널의 잘커라 채널에 진행 내역이 그대로 남습니다.

「받은 파일이 폴더 밖을 가리킵니다」·「받은 파일에 항목이 너무 많습니다」 받은 꾸러미가 정상이 아닙니다. 멈추면서 받다 만 파일은 저희가 지웁니다 — 폴더는 원래대로 돌아갑니다. 그대로 잘커라에 알려 주십시오.

개시한 사이트를 검색에 알리기

사이트가 robots.txt·sitemap.xml 을 내면, Google Search Console·네이버 서치어드바이저·Bing 웹마스터 도구에 등록 → 소유 확인 → 사이트맵 제출 을 하시면 됩니다. 등록할 주소는 콘솔 「커스텀 도메인」의 대표 주소입니다 — 플랫폼 주소(*.zalkera.com)는 색인이 막혀 있습니다. 구글은 DNS 레코드로(DNS 를 못 만지면 「URL 접두어」 속성으로 HTML 파일 확인), Bing 은 구글에서 가져오기로, 네이버는 콘솔 「환경변수」에 NEXT_PUBLIC_NAVER_SITE_VERIFICATION 을 넣어 확인합니다. GA4 측정 ID 는 같은 자리의 NEXT_PUBLIC_GA4_ID 입니다. 순서 전체는 사용 매뉴얼(PDF)의 시나리오 F 에 있습니다.

안 지키는 약속은 적지 않습니다

  • 소스는 쓰시는 분 것입니다. 언제든 통째로 내려받아 다른 곳에서 고치실 수 있습니다.
  • 이 확장이 없어도 콘솔에서 zip 업로드로 같은 일을 하실 수 있습니다. 여기서 편해질 뿐입니다.
  • 되돌리기 어려운 자리를 만지면 막지 않고 알려만 드립니다. 판단은 쓰시는 분이 하십니다.

이 문서의 최신본은 https://zalkera.github.io/zalkera-devtools/ 에 있습니다. 확장에 함께 담긴 사본은 인터넷이 안 될 때를 위한 것이라, 웹 쪽이 더 새로울 수 있습니다.