Upgrade guide

This guide provides instructions on how to upgrade your existing BuilderKit project to the latest version.

01. Stay informed

BuilderKit is actively maintained and regularly updated to ensure compatibility with the latest versions of Angular and to introduce new features and improvements. All updates, improvements, and breaking changes will be documented in the changelog. Make sure to check it before updating.

02. Track your changes

Since BuilderKit is meant to be customized, it is recommended to version control your project so you can clearly see what has changed on your side before applying any updates.

03. Follow the official Angular update guide

Before updating BuilderKit, make sure your Angular project is using the latest compatible version of Angular, Angular CLI, Angular Material, Angular CDK, and Angular Aria. This ensures that any necessary migrations are applied and your environment is fully aligned with the version supported by BuilderKit.

Use the official Angular Update Guide to get exact steps for your project: https://angular.dev/update-guide

This step is important to avoid version mismatches or skipped migrations that could lead to runtime errors or broken layouts. Once your project is upgraded and all migrations have been run successfully, you can proceed with updating BuilderKit.

04. Update BuilderKit

There are two ways to apply the update:

• With an AI agent lets your coding agent bring BuilderKit current and apply the changes for you.
• Manually gives you the latest release to diff and merge yourself.

With the BuilderKit skill installed, updating is a request: tell your agent to update BuilderKit. It does not matter how the project was started, you can install the skill at any point.

The agent refreshes its BuilderKit snapshot to the latest release, compares it against what is in your project, and applies the Core changes while leaving your customizations in place. Anything it cannot merge cleanly is flagged for you to decide on. Commit before you start so the update arrives as a diff you can review, and restore anything you want back.

Blocks are not part of this. Once a block is copied into your project it is your code, so the update does not touch it. If a newer version of a block looks better, copy it again and adapt it as your own decision.

The skill itself is a separate piece: run npx skills update now and then so the instructions your agent follows stay current as well.

Check the @builderkit/builderkit repository for the latest release and pull the changes into the cloned repository you created when you first set up BuilderKit. If you did not clone the repository before, you can either clone it now or manually download the ZIP file of the latest release and unzip it into a temporary folder.

Because BuilderKit is meant to be customized, there is no one-click update solution. Instead, you will need to manually apply the changes from the latest version to your project.

If you have a strict "no customization" policy, you can simply replace your existing BuilderKit files with the new ones. However, if you have made customizations, you will need to carefully merge the changes from the latest version into your existing files.

Best way to do this is to use a diff tool to compare your project's BuilderKit against the latest version of BuilderKit. This will help you identify the files that have changed and the specific changes that were made. Using the same diff tool, you can then manually apply the changes to your project, ensuring that you do not overwrite any of your customizations.