Migration Guide from Knapsack V3 to V4

Prerequisites

To successfully migrate to Knapsack V4, ensure you have the following:

  • Node.js 18
  • npm version 7 or higher

Introduction

Welcome to the Knapsack Migration Guide! 🎉 We're excited to announce the release of Knapsack V4, which comes with more features, improved performance, and an enhanced user experience.

We know that change can sometimes be daunting, but our team has worked hard to make this transition as seamless as possible. This document will guide you through the process of migrating from V3 to V4, ensuring that you can swiftly enjoy all the new benefits.

Contents

  1. Preparation
  2. Data Backup
  3. V4 Migration Process
  4. Verifying Migration
  5. Troubleshooting and Support

1. Preparation — Code Freeze

IMPORTANT: Transitioning the codebase from V3 to V4 constitutes a significant, breaking change!

To safeguard your data and preserve the invaluable efforts of your design system team, we strongly advise implementing a “code freeze” prior to transitioning to the new version.

  • A 'code freeze' is a mutually agreed-upon period during which your team finalizes and integrates all existing and ongoing work into the main branch of the workspace repository. This agreement essentially halts any new development temporarily, ensuring stability and integrity during the migration process.
  • The move from V3 to V4 involves a major transformation of structured data. Failing to instigate a code freeze and consolidate all ongoing work before the upgrade could lead to intricate merge conflicts that can be challenging to resolve.
  • Given the potential complexity of these changes, we highly recommend that your first action should be to create a new branch specifically to handle the transition. This approach will provide a dedicated space to manage the upgrade, ensuring a clear pathway for a smooth and successful transition to Knapsack V4.

2. Data Backup — Create a new branch

Although the migration process is designed to be safe, we strongly recommend your first action should be to create a new branch specifically to handle the transition. This will protect your data from unforeseen circumstances.

3. V4 Migration Process

To ensure a smooth migration from V3 to V4, please follow these steps:

  1. Create a New Branch: Start by creating a new branch in your local workspace.
    1. You could name it something like: migrate-v4
  2. Run Yarn Install: Before you start, ensure you have all the necessary Knapsack packages.
    1. You can do this by running: yarn install
  3. Execute the Updater: Start the update process with the command npx @knapsack/update@latest
    1. If your terminal requests permission to install the npm package, please grant it by typing “y” and then pressing “enter”
  4. Review Changes: Upon completion of the script, take time to review the sections where updates were made. These include:
    • Design Tokens: Now follow the new format recommended by the W3C Community Group, which is being increasingly adopted as a standard across various tools.
    • Content Blocks: These are now centrally located in db.yml and referenced within individual pages as keys.
    • Demos and UI Configurations: Both of these have been converted to align with our new V4 data API.
    • Navigation: The structure has been enhanced to significantly reduce the likelihood of merge conflicts.
    • Markdown Blocks: These have been converted to our new Text Block.
  5. Run Yarn Install Again: Now, run yarn install once more to ensure all updates are properly installed.
  6. Clean Your Local Workspace: To ensure a clean slate, execute yarn clean from the root directory.
  7. Build Freshly: Follow the cleaning with a fresh build using the command yarn build .

4. Verifying Migration

Once the migration process is complete, it's important to verify if the migration has been successful. This includes ensuring that all your data has been migrated correctly and all the features are working as expected.

  1. Validate the Update: If the build from the last step was successful, you can now run yarn start to validate the update.
    1. Review your docs, components, demos, and design tokens to ensure everything works as expected.
    • If you encounter any issues, don't hesitate to contact us at help@knapsack.cloud, and we'll be glad to assist!
  2. Commit and Push Your Work: Once everything is in order, commit your changes and push your work to the repository.
  3. Create a PR and Merge: Finally, create a Pull Request, follow your internal review processes, and then merge your updates.

Congratulations! You've successfully migrated to Knapsack V4. 🎉

5. Troubleshooting and Support

If you encounter any issues during your migration or require further assistance, don't hesitate to reach out to our support team at help@knapsack.cloud.

Conclusion

We hope this guide helps make your transition from V3 to V4 as smooth as possible. We're confident that you'll find V4 to be a significant upgrade, and we can't wait for you to experience all the new features and improvements. Welcome to Knapsack V4!

Related Articles