Installation

Requirements

Create a project

폴더 구조만 생성합니다. 이 단계에서는 설치나 실행을 하지 않습니다.

npx create-meerkit my-app

프로젝트 안으로 이동해 세팅을 실행합니다. 의존성 설치, 환경 변수 생성, DB 실행, 마이그레이션, 서버 실행까지 한 번에 진행됩니다.

cd my-app
npx @snackcup/meerkit setup

What setup does

1. Node, Python, uv, Docker가 있는지 확인합니다. 없으면 설치 안내 후 멈춥니다.
2. frontend에서 npm install을 실행합니다.
3. backend에서 uv sync를 실행합니다.
4. .env.example을 .env로 복사하고 JWT 비밀키를 생성합니다. 이미 있으면 덮어쓰지 않습니다.
5. docker compose up -d --wait로 로컬 DB를 띄웁니다.
6. Alembic 마이그레이션을 적용하고 시드 관리자 계정을 만듭니다.
7. 백엔드와 프론트엔드 서버를 시작하고 접속 주소를 출력합니다.

각 단계는 한 줄로 진행 상황을 보여 주고, 전체 로그는 meerkit-setup.log에 저장됩니다. 다시 실행해도 안전합니다(이미 끝난 단계는 건너뜁니다).

Local URLs

Environment variables

프론트엔드 frontend/.env에서 설정합니다. 운영 환경에 올릴 때의 값은 Deployment 페이지를 보세요.

Existing project

이미 있는 Next.js 프로젝트에 킷의 프론트 부분만 가져오려면 다음 순서로 진행합니다.

1. Tailwind v4와 shadcn/ui를 설정합니다. components.json의 hooks 별칭은 @/meerkit/auth로 둡니다.
2. 필요한 패키지를 설치합니다.
3. src/meerkit/과 src/components/ui/를 복사합니다.
4. 루트 레이아웃을 <MeerkitProvider>로 감쌉니다.
5. 토큰 파일을 globals.css에서 불러옵니다.

npm install zustand @tanstack/react-query axios radix-ui \
  class-variance-authority clsx tailwind-merge lucide-react sonner

import { MeerkitProvider } from "@/meerkit";

export default function RootLayout({ children }) {
  return (
    <html lang="ko">
      <body>
        <MeerkitProvider>{children}</MeerkitProvider>
      </body>
    </html>
  );
}

@import "tailwindcss";
@import "../meerkit/styles/tokens.css";

Troubleshooting