빌드 옵션
스타터, 기존 앱의 SDK 연결, 직접 HTTP 호출 중 알맞은 방법을 선택합니다.
빌드 옵션
스타터에서 시작하거나 기존 앱에 SDK를 추가하고, 필요한 경우 HTTP로 직접 호출하세요. 프런트엔드는 직접 만들고 호스팅합니다.
빌드 경로 선택
| 시작점 | 시작 방법 | 설정 도구가 제공하는 것 |
|---|---|---|
| 새 Next.js 앱 | npm create 01-software-app@0.2.5 | 등록된 스타터를 복사하고 의존성을 설치한 뒤 워크스페이스 연결을 제공합니다. 스타터 선택지는 명령에서 확인하세요. |
| 기존 JavaScript 또는 TypeScript 앱 | npx @01.software/init@0.14.3 | 대상을 감지하거나 질문한 뒤 SDK 설정을 추가합니다. 파일 충돌은 질문을 통해 처리합니다. |
| Astro, Remix, SvelteKit 또는 다른 프레임워크 | npx @01.software/init@0.14.3 | 앞의 세 프레임워크는 감지하며, 그 외에는 Other를 선택합니다. SDK 설치와 client/server 예제를 출력하고 프레임워크 설정 파일을 생성하지 않은 채 종료합니다. |
| 다른 언어나 실행 환경 | API 참조 | HTTP로 직접 호출할 각 작업의 인증과 요청 요건을 확인합니다. |
스타터 명령은 등록된 Next.js 프로젝트를 제공합니다. 임의의 프레임워크나 버전에 맞는 앱을 생성하지는 않습니다. Init의 대상에는 Next.js, Vite 기반 React, Webpack 또는 CRA 기반 React, 브라우저용 vanilla JavaScript, Node.js/Bun/Deno, Edge가 있습니다. 이 선택지가 해당 실행 환경의 모든 버전과 호환된다는 뜻은 아닙니다.
다음 init 릴리스의 이벤트 스타터 변경
다음 init 릴리스에서는 이벤트 스타터를 --template events로 통합해
무료 RSVP·승인제 신청과 유료 입장권을 지원합니다. 기본 live 요구 기능은
Events + Ecommerce이며 고객 계정을 선택하면 Customers가 추가됩니다.
--template events-rsvp는 종료 코드 1로 실패하고 --template events를 안내합니다.
대화형 선택과 --help에서도 폐기된 스타터는 제외됩니다.
이미 생성한 앱과 과거에 게시된 init 버전은 바뀌지 않습니다.
아래 고정 버전 구성은 과거의 검증 기록이며 다음 init 릴리스의 검증 결과가 아닙니다.
전환하기 전에 실제 게시 버전을 확인하세요.
로컬 빌드를 확인한 구성
다음 예제는 Node.js 24.15.0, npm 11.12.1로 빌드했습니다. 확인한 조합이며 모든 프레임워크의 최소 지원 버전을 뜻하지 않습니다.
2026-10-20 관찰 기준입니다. create 0.2.5는 init을 ^0.14.3 범위에서 고르며, 기존 앱에 SDK가 없어 추가할 때 init은 최신 SDK를 설치합니다. init·SDK가 게시되거나 설정 시 다른 버전이 선택되면 실제 버전과 lockfile, 이 예제를 다시 검증하세요. 출력되는 --connect 명령도 @latest를 사용합니다.
| 경로 | 설정 패키지 | SDK | Next.js / React | 검증한 스타터(init 포함 소스) |
|---|---|---|---|---|
| 새 앱 | create 0.2.5 → init 0.14.3 | 0.65.0 (생성 시 고정) | 16.3.8 / 19.2.4 | Ecommerce 0.1.24, Events RSVP 0.1.21 |
| 기존 App Router 앱 | init 0.14.3 | 0.65.1 | 16.3.8 / 19.2.4 | 기존 앱 사용 |
빠른 시작의 createClient import와 commerce.product.listingPage 호출은 위 두 SDK 버전에서 동작합니다. 스타터 버전은 init에 포함된 소스의 버전이며 별도 npm 패키지가 아닙니다. 데모 빌드에도 실제 키나 별도 데모 설정이 필요할 수 있습니다. Ecommerce는 기본적으로 production 모드 빌드에서 mock provider를 차단합니다. 로컬 데모 검증용 mock 허용은 실제 운영 설정 안내가 아닙니다. 데모 빌드 성공만으로 실제 워크스페이스 연결이나 고객 로그인을 검증할 수는 없습니다. 배포 후 해당하는 실제 호출은 배포에 따라 확인하세요.
새 앱 연결과 복구
브라우저 승인은 기존 워크스페이스를 연결합니다. 선택한 실제 환경을 확인하세요. 개발용 키가 로컬 작업과 해당 환경의 데이터를 격리하거나 Sandbox를 만들지는 않습니다. 생성 도구는 자격 증명 없는 프로젝트 파일을 만들고 의존성 설치를 마친 뒤, 인증을 마친 워크스페이스 관리자에게 개발 앱 승인을 요청합니다. 성공한 뒤에만 기존 pk01_와 새 개발용 sk01_가 담긴 .env.local을 만듭니다. Human CLI의 pat01_를 앱의 Secret Key로 사용하지 않습니다.
--no-install에서는 자격 증명을 만들지 않습니다. 출력된 설치 명령을 실행한 뒤, 출력된 정확한--connect명령을 실행하세요.--connect에는 같은 설정으로 생성되고 설치를 마친, 자격 증명 없는 프로젝트가 필요합니다. 기존 또는 상태가 불분명한.env.local때문에 연결이 막히면 덮어쓰지 말고 보존한 채 복구 안내를 따르세요.--auth manual은 올바른 기존pk01_와 개발용sk01_쌍을 받습니다.--auth skip은 워크스페이스 연결 없이 데모 데이터를 사용합니다. 데모 결과가 보이는 것만으로는 백엔드 연결을 확인할 수 없습니다.
기존 앱의 자격 증명
Init은 질문으로 진행하는 별도 명령이며 플래그를 받지 않습니다. 새 앱의 브라우저 승인을 열지 않습니다. SDK 자격 증명 설정과 선택형 AI 도구 설정은 별개입니다. 키를 묻는 대상에서는 AI 도구를 선택하지 않아도 **Enter manually(직접 입력)**이나 **Skip for now(나중에 설정)**을 고를 수 있습니다.
| 대상 | 자격 증명 설정 |
|---|---|
| Next.js | Publishable Key와 개발용 Secret Key 직접 입력 또는 건너뛰기. 기본 env 파일은 .env.local입니다. |
| React 브라우저 대상 | Publishable Key 직접 입력 또는 건너뛰기. 기본 env 파일은 .env입니다. |
| Node.js/Bun/Deno | Publishable Key와 개발용 Secret Key 직접 입력 또는 건너뛰기. 기본 env 파일은 .env입니다. |
| 브라우저용 vanilla JavaScript | 키를 묻지 않습니다. 생성된 코드의 Publishable Key 자리표시자를 앱 설정에 맞게 바꾸세요. |
| Edge | Publishable Key와 개발용 Secret Key 직접 입력 또는 건너뛰기. 생성된 코드는 실행 환경의 바인딩을 사용합니다. |
| 프레임워크 수동 안내 | 호출에 필요한 키를 해당 프레임워크의 규칙에 맞춰 설정합니다. |
Init은 설치나 파일 변경 전에 수동 입력과 선택한 기존 env 파일의 비어 있지 않은 앱 자격 증명을 검사합니다. pat01_, 형식이 잘못된 값, 중복 선언, 불완전한 서버 키 쌍은 기존 파일을 변경하지 않고 거부합니다. 표시된 입력 문제를 해결한 뒤 다시 시도하세요.
자격 증명 경계
Publishable Key는 브라우저 코드에서 사용할 수 있습니다. 워크스페이스를 호출할 각 브라우저 origin을 등록하세요. Secret Key는 신뢰할 수 있는 서버 코드와 서버 설정에만 둡니다. 공개 환경 변수, 브라우저 번들, 명령 인자, URL, 커밋에 넣지 마세요. Human CLI의 PAT와 앱 키는 별개입니다.
배포할 때는 권한 있는 서버 작업에 필요한 경우에만 운영용 Secret Key를 별도로 발급하세요. 자세한 내용은 인증과 키, 연동과 키 관리를 참고하세요.
배포 책임
프레임워크와 호스트의 절차로 배포하고, 배포에서 자격 증명·origin·고객 로그인 설정을 확인하세요. Next.js의 환경 변수 이름이 모든 실행 환경에 적용되지는 않습니다.