Skip to content
Shadcnblocks.com Docs

Updates and Upgrades

Keeping your Sanityblocks project updated ensures you have access to the latest features, bug fixes, and improvements. This guide covers the recommended approach for managing updates while preserving your customizations.

Fork-Based Update Strategy

We recommend starting your project by forking the Sanityblocks repository rather than cloning it directly. This approach provides the cleanest path for receiving updates while maintaining your customizations.

Benefits of Forking

  • Clean merge process: Minimize conflicts when pulling updates
  • Version control: Track your customizations separately from upstream changes
  • Selective updates: Choose which updates to apply and when
  • Backup safety: Your fork serves as a backup of your customizations

Initial Setup

1. Fork the Repository

  1. Visit the Sanityblocks repository on GitHub
  2. Click the Fork button in the top-right corner
  3. Choose your GitHub account as the destination
  4. Clone your fork locally:
Terminal window
git clone https://github.com/YOUR_USERNAME/sanityblocks.git
cd sanityblocks

2. Add Upstream Remote

Add the original Sanityblocks repository as an upstream remote to fetch updates:

Terminal window
git remote add upstream https://github.com/serge-0v/sanityblocks.git

Verify your remotes are set up correctly:

Terminal window
git remote -v

You should see:

origin    https://github.com/YOUR_USERNAME/sanityblocks.git (fetch)
origin    https://github.com/YOUR_USERNAME/sanityblocks.git (push)
upstream  https://github.com/serge-0v/sanityblocks.git (fetch)
upstream  https://github.com/serge-0v/sanityblocks.git (push)

Receiving Updates

1. Fetch Latest Changes

Before updating, fetch the latest changes from the upstream repository:

Terminal window
git fetch upstream

2. Check for Updates

View what’s changed since your last update:

Terminal window
git log HEAD..upstream/main --oneline

This shows commits you haven’t merged yet.

3. Merge Updates

There are two approaches for merging updates:

Creates a merge commit that clearly shows when updates were applied:

Terminal window
git checkout main
git merge upstream/main

Option B: Rebase (Advanced)

Replays your changes on top of the latest updates:

Terminal window
git checkout main
git rebase upstream/main

Note: Only use rebase if you understand Git well and haven’t pushed your changes yet.

4. Resolve Conflicts

If conflicts occur during merging:

  1. Review conflict files: Git will mark conflicted files
  2. Edit conflicted files: Choose which changes to keep
  3. Mark as resolved: Run git add <filename> for each resolved file
  4. Complete the merge: Run git commit (for merge) or git rebase --continue (for rebase)

Common Conflict Scenarios

Most conflicts will occur in these areas:

  • Custom block additions: Your custom blocks vs. new upstream blocks
  • Package.json: Dependency version differences
  • Configuration files: Environment or build configuration changes
  • Generated files: studio/schema.json and frontend/sanity.types.ts

Generated Files - Don’t Resolve Manually

Two files that commonly show conflicts during updates should never be resolved manually:

studio/schema.json

  • Auto-generated file containing compiled Sanity schema definitions
  • Created by running pnpm typegen or Sanity CLI commands
  • Contains serialized versions of all your schema types

frontend/sanity.types.ts

  • Auto-generated TypeScript definitions based on your Sanity schemas
  • Provides type safety between Sanity content and React components
  • Created by the Sanity TypeScript code generation

How to Handle These Files During Conflicts

❌ Don’t do this:

Terminal window
# Don't manually edit these files during merge conflicts
git add studio/schema.json
git add frontend/sanity.types.ts

✅ Do this instead:

Terminal window
# Remove the conflicted generated files
git rm studio/schema.json
git rm frontend/sanity.types.ts


# Complete the merge
git commit


# Regenerate the files
pnpm typegen

Why this approach works:

  • Generated files will always reflect your current schema state
  • Avoids invalid/corrupted type definitions
  • Ensures consistency between schema and TypeScript types
  • Prevents runtime errors from mismatched types

Best Practices for Minimal Conflicts

Follow these guidelines to reduce merge conflicts:

1. Use Custom Naming Convention

Always suffix your customizations with -custom:

// ✅ Good - Safe from future conflicts
export default defineType({
  name: "hero-14-custom",
  title: "Hero 14 Custom",
  // ...
});


// ❌ Avoid - Will conflict if we release hero-14 later
export default defineType({
  name: "hero-14",
  title: "Hero 14",
  // ...
});

2. Keep Customizations Separate

  • Don’t modify existing files: Copy and rename instead
  • Create new directories: For completely new block categories
  • Use dedicated custom folders: Group your customizations together

3. Document Your Changes

Maintain a CUSTOM_CHANGES.md file documenting your modifications:

# Custom Changes


## Custom Blocks Added


- `hero-12-custom`: Custom hero with additional CTA field
- `testimonial-carousel`: New testimonial block with carousel


## Modified Files


- `frontend/components/blocks/index.tsx`: Added custom block imports
- `studio/schema.ts`: Added custom schemas


## New Dependencies


- `swiper`: Added for carousel functionality

Update Checklist

When applying updates, follow this checklist:

Pre-Update

  • Commit your changes: Ensure your work is saved
  • Create a backup branch: git checkout -b backup-before-update
  • Test current state: Ensure everything works before updating
  • Review release notes: Check what’s changed in the update

During Update

  • Fetch upstream changes: git fetch upstream
  • Review changes: git log HEAD..upstream/main --oneline
  • Merge updates: git merge upstream/main
  • Resolve conflicts: Address any merge conflicts carefully
  • Update types: Run pnpm typegen after schema changes

Post-Update

  • Install dependencies: pnpm install for any new packages
  • Test functionality: Verify both frontend and studio work
  • Check custom blocks: Ensure your customizations still work
  • Update documentation: Note any changes to your custom setup
  • Deploy: Push changes to your deployment

Troubleshooting Updates

Large Number of Conflicts

If you encounter many conflicts:

  1. Reset and start over: git merge --abort
  2. Review your customizations: Consider if they follow best practices
  3. Apply updates incrementally: Merge smaller ranges of commits

Broken Functionality After Update

If something breaks after updating:

  1. Check console errors: Look for TypeScript or runtime errors
  2. Regenerate types: Run pnpm typegen
  3. Clear cache: Clear Next.js and dependency caches
  4. Review schema changes: Check if field names or structures changed
  5. Test in isolation: Create a minimal reproduction of the issue

Reverting Updates

If you need to undo an update:

Terminal window
# Find the merge commit
git log --oneline -n 10


# Revert the merge (replace HASH with actual commit hash)
git revert -m 1 HASH


# Or reset to previous state (loses changes!)
git reset --hard HEAD~1

Advanced Update Strategies

Update Branches

Create dedicated branches for testing updates:

Terminal window
git checkout -b test-updates
git merge upstream/main
# Test everything works
git checkout main
git merge test-updates

Remember: Following the Custom Blocks best practices significantly reduces update conflicts and makes the process smoother.