GuideThe GatsbyJS & NextJS Cleanup Roadmap

If you have a GatsbyJS or NextJS code base that has become messy and difficult to maintain, it can be overwhelming to know where to start in cleaning it up. However, with a clear plan and roadmap in place, it is possible to get your code base back in order and improve its overall health. Here are six phases to consider when tackling a cleanup project:

The first step in cleaning up a code base is to make non-destructive removals, such as removing unnecessary console.log statements and unused variables and imports. It is important to establish some basic guidelines for this phase, such as measuring the number of issues for an A/B test to see the impact of the changes and creating new git branches for each category of change. It is also a good idea to have different developers work on each category of change, as this can help to ensure that all areas of the code base are thoroughly cleaned up.

While you are making these non-destructive removals, it is important to continue shipping new features and fixing any critical issues that arise, especially if the messy code base is causing a lot of bugs in production. You should also consider creating different branches for different types of changes, as this can help to keep your code base organized and easy to manage.

In addition to removing console.log statements and unused variables and imports, you should also consider cleaning up any unused dependencies and config files. However, be careful when using tools to find unused dependencies, as it can be dangerous if the tool doesn't recognize specific dependencies throughout the code base and returns a lot of false positives.

Once you have made the non-destructive removals, it is time to move on to the next phase: setting up a basic end-to-end testing setup. This is an important step, as it allows you to safely make more substantial changes to the logic in your code base without risking breaking any essential functionality.

To do this, you should create a basic testing suite that covers all essential user flows. For example, if you are working on an ecommerce site with GatsbyJS / NextJS and headless Shopify, you might include tests for the following user flows:

1. User can enter the site
2. User can enter a collection page
3. User can enter a product page
4. User can add a product to cart
5. User can go checkout
6. User can complete purchase

It is important to note that no changes to logic or "dangerous" code should be made before this phase is complete, as testing allows you to safely make more complex code changes in later phases while still ensuring that the basic functionality of the site is intact.

In the third phase of the cleanup process, you should focus on fixing any broken dependencies and removing any unused third party tools and libraries. This can help to streamline your code base and reduce the number of unnecessary dependencies that you are maintaining.

In the fourth phase of the cleanup process, it is time to focus on unifying the code base. This can involve standardizing file names, formatting, and naming conventions for React components, as well as ensuring that GraphQL queries are in the same location. There are many well-established conventions that you can follow, or you can create your own guidelines based on the needs of your specific code base.

The goal of this phase is to make the code base more consistent and easier to understand, which can help to improve readability and maintainability.

The fifth phase is all about establishing and protecting the health of the base code base. This can involve a number of different tasks, such as cleaning up the git history if environmental variables are committed to git, implementing Husky and linting-staged to lint commits at commit and PR time, and controlling error handling throughout the code base.

Other tasks that might be included in this phase include extracting React components from large files and using composition, extracting SVG elements into their own components, and removing unused files. It is important to be careful when using tools to find unused files, as it can be dangerous if the tool doesn't recognize specific usages of files throughout the code base and returns a lot of false positives.

In addition to these tasks, you should also check that functions are being used as intended (for example, no 'find' method as a supplement for the 'forEach' method), ensure that props aren't spread unnecessarily and are used in a specific manner, and consider converting some functions into pure functions to improve performance and readability.

In the final phase of the cleanup process, it is time to upgrade to the latest possible versions of GatsbyJS / NextJS, any other dependencies, and source plugins and external systems (such as updating from Strapi v3 to v4). This can help to ensure that your code base is using the most up-to-date technologies and is as efficient and effective as possible.

Once you have completed all six phases of the cleanup roadmap, it is important to measure the impact of the changes and show the results to your client. Be sure to communicate the business effects of the cleanup process, such as being able to ship features much faster and more cost-effectively, and not risking errors and outages that could hurt profitability and customer relationships. By following this roadmap, you can help to get your code base back in order and improve its overall health and maintainability.

If you have a large overwhelming cleanup project at hand and would like guidance or help, please feel free to reach out to us.