# Updating your TanStack Start Prisma Starter Kit

> Learn how to update your TanStack Start Prisma Starter Kit to the latest version and resolve merge conflicts.

*Canonical: https://makerkit.dev/docs/tanstack-prisma/installation/updating-codebase*

---

This guide will walk you through the process of updating your codebase by pulling the latest changes from the GitHub repository and merging them into your project. This ensures you're always equipped with the latest features and bug fixes.

If you've been following along with our previous guides, you should already have a Git repository set up for your project, with an `upstream` remote pointing to the original repository.

Updating your project involves fetching the latest changes from the `upstream` remote and merging them into your project. Let's dive into the steps!

{% sequence title="Steps to update your codebase" description="Learn how to update your TanStack Start Prisma Starter Kit to the latest version." %}
[Stashing your changes (if any)](#0.-stashing-your-changes-(if-any))

[Refresh the `upstream` remote](#1.-refresh-the-remote)

[Resolve any conflicts](#2.-resolve-any-conflicts)

[Run a health check on your project](#run-a-health-check-on-your-project-after-resolving-conflicts)

[Merge the changes](#3.-merge-the-changes)
{% /sequence %}

## 0. Stashing your changes (if any)

If you have uncommited changes, before updating your project, it's a good idea to stash your changes to avoid any conflicts during the update process. You can stash your changes by running:

```bash
git stash
```

This will save your changes temporarily, allowing you to update your project without any conflicts. Once you've updated your project, you can apply your changes back by running:

```bash
git stash pop
```

If you don't have any changes to stash, you can skip this step and proceed with the update process.

Alternatively, you can commit your changes.

## 1. Refresh the `upstream` remote

Create a new branch for your updates from the `main` branch:

```bash
git checkout -b update-codebase-<date>
```

In this way, you can keep track of your updates and visualize the changes in the branch before merging them into your main branch.

Now, fetch the latest changes from the `upstream` remote. You can do this by running the following command:

```bash
git pull upstream main
```

When prompted the first time, opt for **merging instead of rebasing**.

Now, run `pnpm i` to update the dependencies:

```bash
pnpm i
```

## 2. Resolve any conflicts

Encountered conflicts during the merge? No worries! You'll need to resolve them manually. Git will highlight the files with conflicts, and you can edit them to resolve the issues.

**Recommended tools for conflict resolution:**

- **WebStorm/IDE diff tools** - WebStorm and other JetBrains IDEs have excellent built-in merge conflict resolution tools. Use `Git > Resolve Conflicts` to visually compare and merge changes.
- **AI assistants** - Tools like GitHub Copilot, Claude, or Cursor can help resolve conflicts. However, always review AI-suggested resolutions carefully to ensure they preserve your custom logic and don't introduce bugs.

### 2.1 Conflicts in the lock file "pnpm-lock.yaml"

If you find conflicts in the `pnpm-lock.yaml` file, accept either of the two changes (avoid manual edits) or just delete the file, then run the install command to update the dependencies:

```bash
pnpm i
```

Your lock file will now reflect both your changes and the updates from the `upstream` repository.

### 2.2 Conflicts in Prisma schema or migrations

If you have modified the Prisma schema or created your own migrations in `packages/database/src/prisma/`, you may encounter conflicts.

**For schema conflicts:**

1. Carefully review both versions of the schema file (`packages/database/src/prisma/schema.prisma`)
2. Merge the changes manually, ensuring you keep both your additions and the upstream changes
3. After resolving, create and apply a new migration if needed:

```bash
pnpm --filter "@kit/database" prisma:migrate
```

**For migration conflicts:**

Prisma migrations (`.sql` files) live in timestamped directories under `packages/database/src/prisma/migrations/`. If you encounter conflicts:

1. Accept both sets of migrations (yours and upstream)
2. Ensure migration directory names don't clash. Prisma uses a timestamp prefix for each migration directory (e.g. `20260629091122_name/`).
3. Check the migration order is correct (migrations run in ascending directory-name order, so timestamps sort chronologically)
4. If the database state is inconsistent, you may need to reset and re-migrate:

```bash
pnpm run db:reset
pnpm --filter "@kit/database" prisma:migrate
```

**Warning:** Resetting the database will delete all data. Only do this in development.

### Run a health check on your project after resolving conflicts

After resolving the conflicts, it's time to test your project to ensure everything is working as expected. Run your project locally and navigate through the various features to verify that everything is functioning correctly.

You can run the following commands for a quick health check:

```bash
pnpm run typecheck
```

And lint your code with:

```bash
pnpm run lint
```

## 3. Merge the changes

If everything looks good, commit the changes and push them to your remote repository:

```bash
git commit -m "COMMIT_MESSAGE"
git push origin update-codebase-<date>
```

Once the changes are pushed, you can create a pull request to merge the changes into the `main` branch, assuming all is working fine.

Your project is now up to date with the latest changes from the `upstream` repository.

## Best Practices for Avoiding Conflicts

1. **Pull frequently** - The more often you pull from upstream, the smaller and easier the merges will be
2. **Keep customizations isolated** - When possible, extend rather than modify core files
3. **Document your changes** - Keep track of which files you've modified to make conflict resolution easier
4. **Use feature branches** - Work on features in separate branches, making it easier to isolate and resolve conflicts
5. **Review changelogs** - Check the MakerKit changelog before updating to understand what's changed

---

**Previous:** [Running the Project →](./running-the-project)