# Deployment Guide

This guide covers deploying both your Sanity Studio and your Next.js frontend to Vercel.

---

# Frontend Deployment (Vercel)

This guide will help you deploy your Next.js frontend to Vercel.

## Prerequisites

- A Vercel account (you mentioned you have one)
- Your Sanity project credentials
- Node.js installed locally (for CLI method)

## Method 1: Deploy via Vercel Dashboard (Recommended for First Time)

### Step 1: Prepare Your Repository

Make sure your code is pushed to a Git repository (GitHub, GitLab, or Bitbucket). Vercel works best with Git-based deployments.

### Step 2: Import Project to Vercel

1. Go to [vercel.com](https://vercel.com) and sign in
2. Click **"Add New..."** → **"Project"**
3. Import your Git repository
4. Vercel will auto-detect it's a Next.js project

### Step 3: Configure Project Settings

**Root Directory**: Set to `frontend` (since your Next.js app is in the frontend folder)

**Build Command**: `npm run build` (or leave default)

**Output Directory**: `.next` (default, should auto-detect)

**Install Command**: `npm install` (default)

### Step 4: Add Environment Variables

In the Vercel project settings, add these environment variables:

**Required:**
- `NEXT_PUBLIC_SANITY_PROJECT_ID` - Your Sanity project ID
- `NEXT_PUBLIC_SANITY_DATASET` - Your Sanity dataset name (usually "production")
- `SANITY_API_READ_TOKEN` - Your Sanity API read token (get this from your Sanity project settings)

**Optional:**
- `NEXT_PUBLIC_SANITY_API_VERSION` - API version (defaults to "2025-09-25" if not set)
- `NEXT_PUBLIC_SANITY_STUDIO_URL` - Studio URL (defaults to "http://localhost:3333" if not set)

### Step 5: Deploy

Click **"Deploy"** and wait for the build to complete. Vercel will provide you with a URL like `your-project.vercel.app`.

## Method 2: Deploy via Vercel CLI

### Step 1: Install Vercel CLI

```bash
npm i -g vercel
```

### Step 2: Login to Vercel

```bash
vercel login
```

### Step 3: Navigate to Frontend Directory

```bash
cd frontend
```

### Step 4: Deploy

```bash
vercel
```

The CLI will ask you:
- **Set up and deploy?** → Yes
- **Which scope?** → Select your account
- **Link to existing project?** → No (for first deployment)
- **What's your project's name?** → Enter a name or press Enter for default
- **In which directory is your code located?** → `./` (since you're already in frontend)

### Step 5: Add Environment Variables

After the first deployment, add environment variables:

```bash
vercel env add NEXT_PUBLIC_SANITY_PROJECT_ID
vercel env add NEXT_PUBLIC_SANITY_DATASET
vercel env add SANITY_API_READ_TOKEN
```

Or add them via the Vercel dashboard (recommended).

### Step 6: Redeploy with Environment Variables

```bash
vercel --prod
```

## Getting Your Sanity Credentials

If you need to find your Sanity credentials:

1. Go to [sanity.io/manage](https://sanity.io/manage)
2. Select your project
3. Go to **API** → **Tokens** to create a read token
4. Your **Project ID** and **Dataset** are shown in the project overview

## Updating Your Frontend

### Via Git (Automatic)

If you connected your Git repository, Vercel will automatically deploy when you push to your main branch.

### Via CLI

```bash
cd frontend
vercel --prod
```

## Deploying from a Different Branch (e.g., "dev")

By default, Vercel deploys from the `main` branch. To deploy from the `dev` branch instead:

### Method 1: Via Vercel Dashboard (Recommended)

1. Go to your project on [vercel.com](https://vercel.com)
2. Click on **Settings** → **Git**
3. Under **Production Branch**, change it from `main` to `dev`
4. Click **Save**

Now your production deployments will use the `dev` branch. Any push to `dev` will trigger a production deployment.

### Method 2: Via Vercel CLI

```bash
cd frontend
vercel git connect
```

Then follow the prompts, or use:

```bash
vercel project ls
vercel project <project-name>
```

You can also manually deploy a specific branch:

```bash
vercel --prod --branch dev
```

### Branch-Specific Deployments

- **Production deployments**: Will use the branch you set in Settings → Git → Production Branch
- **Preview deployments**: Vercel automatically creates preview deployments for all other branches and pull requests

## GitLab CI/CD Setup (Automatic Deployments)

You can set up GitLab CI/CD to automatically deploy to Vercel whenever you push to your `dev` branch (or any branch). This eliminates the need to manually deploy.

### Step 1: Get Your Vercel Token

1. Go to [vercel.com/account/tokens](https://vercel.com/account/tokens)
2. Click **"Create Token"**
3. Give it a name (e.g., "GitLab CI/CD")
4. Copy the token (you won't be able to see it again!)

### Step 2: Configure GitLab CI/CD Variables

1. Go to your GitLab project
2. Navigate to **Settings** → **CI/CD** → **Variables**
3. Click **"Expand"** next to Variables
4. Add the following variables:

   **Required:**
   - `VERCEL_TOKEN` - Paste the token you created in Step 1
   - `VERCEL_PROJECT_NAME` - Your Vercel project name (the part before `.vercel.app` in your URL)
   - `VERCEL_TEAM` - Your Vercel team/username (optional, only needed if you're in a team)

   **Optional (if not set in Vercel dashboard):**
   - `NEXT_PUBLIC_SANITY_PROJECT_ID` - Your Sanity project ID
   - `NEXT_PUBLIC_SANITY_DATASET` - Your Sanity dataset
   - `SANITY_API_READ_TOKEN` - Your Sanity API token

   **Note:** For each variable, you can:
   - Check **"Protect variable"** to only use it in protected branches
   - Check **"Mask variable"** to hide it in job logs (recommended for tokens)

### Step 3: Push the CI/CD Configuration

The `.gitlab-ci.yml` file is already configured in your repository. It will:

- **Run tests** on all branches and merge requests (type checking and linting)
- **Deploy to production** when you push to the `dev` branch
- **Create preview deployments** for other branches and merge requests

### Step 4: Test It Out

1. Make a small change to your code
2. Commit and push to the `dev` branch:
   ```bash
   git add .
   git commit -m "Test CI/CD deployment"
   git push origin dev
   ```
3. Go to your GitLab project → **CI/CD** → **Pipelines**
4. Watch the pipeline run! It will:
   - Run tests
   - Deploy to Vercel automatically
   - Show you the deployment URL

### How It Works

- **On `dev` branch push**: Runs tests → Deploys to Vercel production
- **On other branches**: Runs tests → Creates a preview deployment
- **On merge requests**: Runs tests → Creates a preview deployment for review

### Customizing the CI/CD Pipeline

If you want to change which branch triggers production deployments, edit `.gitlab-ci.yml` and change:

```yaml
only:
  - dev  # Change this to 'main' or any other branch name
```

### Troubleshooting CI/CD

**Problem**: Pipeline fails with "VERCEL_TOKEN not found"
- **Solution**: Make sure you've added `VERCEL_TOKEN` as a CI/CD variable in GitLab

**Problem**: Deployment fails with authentication error
- **Solution**: Verify your `VERCEL_TOKEN` is correct and hasn't expired

**Problem**: Tests pass but deployment doesn't happen
- **Solution**: Check that your branch name matches the `only:` section in `.gitlab-ci.yml`

**Problem**: Want to skip CI/CD for a commit
- **Solution**: Add `[skip ci]` or `[ci skip]` to your commit message

## Troubleshooting

**Problem**: Build fails with "Missing environment variable"
- **Solution**: Make sure all required environment variables are set in Vercel project settings

**Problem**: Build fails with typegen errors
- **Solution**: The `prebuild` script runs typegen automatically, but ensure your Sanity credentials are correct

**Problem**: Site loads but shows errors
- **Solution**: Check that `SANITY_API_READ_TOKEN` is set correctly and has read permissions

---

# How to Deploy Your Sanity Studio

This guide will help you put your Sanity Studio online so you can access it from anywhere.

## What You Need

- A computer with the project files
- Terminal or command line access
- Your Sanity account login

## Step-by-Step Instructions

### Step 1: Open Your Terminal

Open the terminal on your computer and navigate to the studio folder:

```bash
cd studio
```

### Step 2: Make Sure Everything is Installed

Install all the required pieces (if you haven't already):

```bash
npm install
```

### Step 3: Log In to Sanity

Tell Sanity who you are:

```bash
npx sanity login
```

This will open your web browser. Sign in with your Sanity account.

### Step 4: Deploy Your Studio

Push your studio to the internet:

```bash
npm run deploy
```

The first time you do this, Sanity will ask you a few questions:
- **Project ID**: Choose the project you want to deploy (or create a new one)
- **Hostname**: Pick a name for your studio URL (like `my-studio.sanity.studio`)

### Step 5: Wait for It to Finish

The deployment will take a minute or two. You'll see messages in your terminal showing progress.

### Step 6: Visit Your Studio

Once it's done, you'll see a URL in your terminal. Open that URL in your web browser to see your studio online!

## Updating Your Studio

Whenever you make changes to your studio and want to update the online version, just run:

```bash
npm run deploy
```

That's it! Your changes will be live in a few minutes.

## Troubleshooting

**Problem**: "Command not found" or "npm not found"
- **Solution**: Make sure Node.js is installed on your computer

**Problem**: "Not logged in"
- **Solution**: Run `npx sanity login` again

**Problem**: "Build failed"
- **Solution**: Check that all your files are saved and there are no errors in your code

## Need Help?

If something goes wrong, check the [Sanity documentation](https://www.sanity.io/docs/deployment) or ask for help from your team.