How To Deal With Big Tooling Upgrades In Large Organizations

 The process of upgrading large third-party packages in equally large organizations is rarely, if ever, as easy as running an npm update and calling it a day in this context. Joran Quinten shares valuable lessons from his team’s experiences in upgrading third-party code that affects codebases across the entire organization.

If you work in software development, you probably know a thing or two about using and maintaining third-party packages. While third-party tooling has its fair share of downsides, there are plenty of advantages as well. The efficiency you get from code that someone else has already written speeds up development and is hard to deny. Sure, there are all sorts of considerations to take in before plopping code from a third party — accessibility, technical debt, and security, to name a few — but the benefits may make taking on those considerations worthwhile for your team.

Upgrades are also part of that set of considerations. Usually, your team may treat this sort of maintenance as a simple task or chore: upgrading dependencies and (automatically) validating that all of the features keep functioning as expected. You probably even have automated checks for keeping all package versions up to date.

But what if the third-party tooling you adopt is big? I mean big, big. That’s common in large organizations. I happen to work for a fairly large organization that leverages big third-party resources, and upgrading those tools is never as simple as running a package update and moving on. I thought I’d share what’s involved in that process because there are many moving pieces that require ample planning, strategy, and coordination. Our team has learned a lot about the process that I hope will benefit you and your team as well.

Some Context On My Organization

I work for Jumbo Supermarkten in the Jumbo Tech Campus (JTC), which is a department of over 350 developers working in agile teams on a range of digital products that help facilitate our core grocery and e-commerce processes.

We have a variety of responsibilities, where 70% of the work is allocated to the primary objectives for each team, and the remaining 30% is dedicated to anything a team wants, as long as it is beneficial to the JTC, which is very useful if you want to deliver value outside of your own team.

When we look at maintaining tooling and packages, balancing the goals of each team with the goals of JTC means that teams effectively maintain their own codebases while also collectively maintaining internally shared codebases that serve as the tooling and foundation of our applications.

Centralized Code As A Bottleneck

To build our applications with consistent standards, we rely on an internal design system and the component library we call Kompas (Dutch for “Compass”). We have built this system ourselves and rely on Vue to render our components and build interactions. Kompas is a hard dependency for virtually all of our applications to ensure uniformity.

This project was not allocated to a dedicated team. Instead, we adopted a strategy that introduced plenty of guidance to allow all front-end developers to contribute. Any developer can add new components to the library as well as features to existing components and keep everything in sync with the designs.

Teams normally work on business features since product owners love delivering customer value. The way we set up our process would allow a team to, in one sprint:

• Make the required change in Kompas,
• Have it reviewed by peers from both inside and outside a particular team,
• Publish the latest version of the component library, and
• Use that version in that team’s own application to deliver to the end user.

We can only do this with automation on repetitive processes — linting, formatting, quality assurance, testing, visual comparisons, and publishing — in order to provide enough room for developers to contribute to the process. Our component library is very much a living document of our design system, with multiple minor releases and patches a week. With semantic versioning, we can keep our own applications up to date easily and with confidence.

For bigger undertakings, such as setting up visual snapshot tests, we established temporary working groups alongside our existing teams that we called “front-end chapters” where members join on a voluntary basis. In these meetings, we discuss what needs to be done, and in the available 30% of free time we are allotted, the members of these teams carry out the work and report back to the chapter.

As you can imagine, we’ve spent a lot of time and effort ensuring the quality and making it a reliable part of our landscape.

This all began when Vue was in Version 2. That’s the version we baked into Kompas, which means we effectively forced our whole application landscape to follow suit. This worked perfectly for us; people could focus on their team’s needs while leaning on the support of the entire front-end chapter that works on Kompas.

Following the Vue ecosystem that we introduced, Vuex and Nuxt became part of our environment. And then Vue 3 was announced, and it was a massive breaking change from Vue 2! With the announcement, the end-of-life date for Vue 2 was set for December 31, 2023. We still have some time as of this writing, but the news had a massive impact that cascaded throughout our organization.

We Needed A Strategy

We needed to upgrade Vue from 2 to 3. The first thing that we needed to figure out was when we could reasonably start the process. To assess and strategize, we formed a small virtual team of developers consisting of members from various teams so that multiple perspectives were represented.

We figured that there would be a period of time when we would need to support both versions in order to allow time for migrating between teams. It would be nearly impossible to orchestrate a monolithic release. Thus, we prefer gradual incrementing over massive sweeping changes. On the other hand, having to maintain two versions of Vue for, basically, the same business feature presented costs in time and complexity.

So, in order to execute this process as responsibly as possible, we set out to figure out when we could start, taking into account the longevity of maintaining two codebases while getting early experience from upgrading. We started to map the different tech stacks for each team and plotted out potential bottlenecks for the sake of making the process of our work as widely visible as possible. At this time, our organization had a very flat structure, so we also needed to get internal stakeholders (i.e., product owners, architects, and managers) involved and convey the effect this upgrade would have on teams across the board.

Creating A Map

With our starting point set, we move on to establish a direction. Not having a dedicated team did pose some challenges because it meant that we needed to align everybody in a democratic way. This is, in Dutch culture, also known as polderen:

We try to find consensus in a way where everybody is equally happy, or unhappy, about the final direction.

And this can be challenging in a department that consists of many cultures!

One thing we knew we could rely on was the published best practices from official Vue resources to guide our decision-making process. Referencing the documentation, we did notice opportunities for incremental upgrades. The release of Vue 2.7 (Naruto) was really helpful in the sense that it backported features from Vue 3 back to a Vue 2-compatible version.

We also noted that in our landscape, not all applications were actually using Nuxt. A stable release of Nuxt 3 would be a prerequisite for those applications to even be considered for migration since the Vue major version is tightly coupled with the Nuxt major version. Luckily, some applications in our landscape are standalone Vue apps. These are ideal candidates for the first Vue 3-compatible components.

But first, we would need to have components that were compatible with Vue 3.

The Big Divide

By this point, we were confident enough to get to work. We had a plan and clear strategy, after all. The first order of business was to make sure that our component library was compatible with Vue 3, preferably while minimizing duplicative efforts.

We found a really nice way of doing this:

We created a new workspace called “Kompas-next” next to the regular components folder, which was scaffolded out using Vue 3. Then we imported the components from the original library.

“

This only works because:

• The backported features in Vue 2.7 allowed us to move closer toward the Vue 3 composition API (among other things).
• The component syntax between Vue 2 and Vue 3 isn’t radically different anymore.
• Vue Demi allowed us to convert components, one by one, to be compatible with both versions.
• We made sure that Kompas-next runs isolated tests to ensure stability.

We did have to slightly modify each and every component to adapt to the new standards. We’ll get to that process in a minute.

That said, we were able to publish two versions of our component library: one that is compatible with Vue 2 (Kompas) and one that is compatible with Vue 3 (Kompas-next). This, in turn, meant that the teams that did not have Nuxt as a dependency could potentially start migrating!

Getting Organized

Up to this point, most of the groundwork had been done in a relatively small team. We were in charge of the investigations, communication, and alignment. But we still needed to get stuff done — a lot of stuff!

With every developer being able to contribute, we came to an agreement that fits with the way everybody was already contributing to the component library:

If you touch a component that is not yet compatible, convert it to be compliant with both Vue 2 and Vue 3 using Vue-demi. Add the existing component with tests to the imports of the Kompas-next folder.

Having communicated this strategy early in the process, we immediately saw the Kompas-next library growing. The Vue core team has put so much effort into closing the gap between the two versions, which made our lives much easier.

Feedback From Early Adopters

The teams that were not blocked by a Nuxt 3 release could spend their time migrating their complete app to Vue 3, providing feedback along the way on how we were setting up our packages and converting components.

Seeing the first applications using Vue 3 was a milestone we could all be proud of since we managed to reach it together, collaboratively, and with a united strategy. The strategy worked for us because it closely resembled the way we were already working.

There were indeed some components that were not migrated using this strategy, which indicated to us that they were stale in terms of development. We reasoned that “stale” equals “stable” and that it would be perfectly fine to migrate them by manual assignment and distribution since we can expect it to be close to a one-off migration per component.

We also started to add Vue 3-specific capabilities to our component library, such as our own composables. I think that’s a nice testament to the investment and adoption by our front-end chapter.

With the component library now supporting Vue, we cleared a significant migration hurdle in our organization. We enabled teams to start migrating to Vue 3, and we encouraged new applications to use the latest standards. As a result, we could start thinking about a deprecation path for our Vue 2 codebase. We were cautiously optimistic and aligned the end-of-life date for Kompas with the same date for Vue 2: December 31, 2023.

So, yes, we are not yet finished and still have work to do. In fact, we had…

Two (Minor) Elephants In The Room

To support communication between micro-applications that run on our e-commerce domain, we had resorted to using Vuex in the past. We used to register stores globally so other applications could dispatch actions and retrieve a shared state. This is now gradually being migrated in the sense that we are replacing Vuex with Pinia for internal state management.

For cross-app communication, we are in the process of decoupling Vuex as an external interface and promoting the use of custom events tied to a specific domain. This prevents us from locking ourselves out of future state management tooling.

We are also in the process of preparing our Nuxt applications to be cleared for migration as well. Within our e-commerce domain, we’ve been building specific modules that take a lot of overhead out of our hands: They handle tasks like setting meta headers, security, and analytics. These are being rewritten to use plugins rather than modules. The impact of this breaking change is smaller because it is limited to the teams that use these modules. We see that these teams are using a similar strategy, albeit on a smaller scale, to organize and structure the tasks at hand.

Looking Back

I believe we have a few key takeaways from how we upgraded (and continue to upgrade) from one version of a large third-party resource to another within our large network of teams and shared codebases. I believe the lessons we learned are relevant beyond Vue and can be applied to the processes of other large organizations migrating between versions of a core piece of architecture.

Let’s review what we learned:

• Ensure the transition period is clear and as short as possible.
• Facilitate breaking the work down into small steps that progress iteratively and solicit feedback from those involved in the process as early and as often as possible.
• Onboard key stakeholders to make sure your team has ample time and resources to do the work.
• Define a strategy that fits with your organization’s culture.
• Foster a collaborative mindset and establish clear communication between teams.
• Celebrate wins, even the smallest ones!

The Work Is Never Done, Really

As I mentioned earlier, maintenance is a never-ending piece of the software development process. As Vue creator Evan You stated in the State of the Vuenion 2023, Vue plans to ship more frequent updates and releases. This will keep impacting our work, but that’s okay. We have a plan and blueprint for future releases.

We’re not there yet, but we now know how to get there!

Amazon permanently holding funds for a wide range of “sins”

 

If your Amazon seller account gets suspended, will you get your funds?

Maybe not. Amazon is now permanently holding funds for a wide range of “sins”.

For years, Amazon dispersed the funds for closed accounts in almost every case. Fraud and counterfeit were the occasional exceptions.

But now, Amazon is permanently attaching sellers’ funds for a wide range of alleged violations of its Business Services Agreement. And frankly, some of these offenses seem quite minor. While the seller’s mistakes may have warranted account deactivation, our team has been shocked that they have resulted in permanent loss of earned revenues.

 

First, here are some basics. When a seller’s account is deactivated, Amazon stops disbursing funds. The account balance just sits there while the seller tries to get back on the platform. If Amazon refuses to reactivate the account, funds are supposed to be released after 60 days. This allows for any A-to-z claims, returns and other fees to be debited from the seller’s balance. After the magical 60 days, remaining funds are sent to the seller’s bank account. (It’s important to know that Amazon’s calculation of when the 60 days starts is somewhat confusing. It’s usually when the company decides to permanently block the seller for the last time – which can be months after the original suspension.)

But then came the decisions to not release funds. The first volley in this new offensive was somewhat predictable. Sellers of e-cigs and vaping accessories had long abused the platform by creating bogus listings, selling a few units, and deleting the listings. This would be repeated ad nauseum, until Amazon caught the seller and suspended their account.

These sellers would then create a new account and repeat the entire process over again. Amazon got tired of the rule-breaking and held funds permanently for these folks – thus stopping the cycle of launching yet more new accounts in the vaping space.

Over the last few months, however, much more typical – and seemingly harmless – suspensions have resulted in permanent holds. We will start with the most egregious seller sins, and then move to the lesser ones:

• Counterfeit goods. Amazon will (rightly) hold your funds, destroy your inventory, and block you from the platform. (This does beg the question of how Amazon can keep the funds from the sale of counterfeit goods, rather than turning them over to the Secret Service or another government agency. But that’s an Amazon rant for another day.)
• Forged documents. It’s tempting to believe that this is the same as counterfeit goods. But alas, it is not. Many forged documents suspensions we are seeing relate to invoices submitted for ungating, rather than in response to a suspension or Seller Performance inquiry. Since the seller probably wasn’t ungated based on their forged invoice, they are essentially suspended for items never sold. When funds are then held, it’s based on an assumption of counterfeit by Amazon – even though counterfeit goods likely were never involved. Just wow. Also, there are more false positive suspensions for forged docs than you would like to believe – sadly.
• Inauthentic. In the past, only having your products labeled as “counterfeit” would trigger a funds and inventory hold. But now, Amazon is refusing to return funds in many cases when products were labeled as inauthentic – a lesser crime than counterfeit in the Amazon hierarchy of broken dreams. In the cases of our clients, the products generally were authentic goods. Our clients bought gray market or otherwise couldn’t provide good invoices, so Amazon slapped them with the inauthentic label and decided to keep their money and their FBA inventory. Forever.
• Linked accounts. This is perhaps the most surprising reason for holding funds we have seen thus far. Clients with more than one account on Amazon – without permission – have seen a denial when they requested a release of their funds. Amazon specifically stated in the notice that this was a consequence of having multiple accounts. Perhaps an argument can be made that this is similar to the vaping situation mentioned above. Yet in some cases we have worked, there was no major rule-breaking going on.
• Fraudulent and systematic abuse of customers. Recently, a client was denied funds for this stated reason. We had thoroughly reviewed his account and were absolutely baffled as to how his mistakes led to such a strongly worded denial. Fortunately, we were able to get the account reinstated and his nearly $400,000 in funds released for disbursement just a few days later. What did he do wrong? There was definitely poor customer service, as well as serious product quality problems. But the account was suspended for suspected inauthentic – which we disproved with invoices and a strong letter from the seller’s supplier. What was Amazon Payments thinking? We still don’t know.

Unfortunately, we anticipate that the list of reasons for holding funds – permanently – is only going to grow.

How can sellers protect themselves?

1. Shore up your sourcing. Make sure your invoices meet Amazon’s standards, and that you have authorization letters whenever possible.
2. Keep good banking records. If an invoice shows a balance, it helps to prove that you paid it. This is one more step toward convincing Amazon you have valid relationships with quality suppliers.
3. Don’t open multiple accounts. If you want a second account, get Amazon’s approval. Just do it the right way.
4. Don’t submit forged documents – for any purpose. This means don’t alter a date, a quantity, a product, an address – nothing. If it’s not an original invoice, please don’t submit it to Amazon.
5. Be on your game with customers. Tempted to circumvent the opt-out? Thinking about yelling at an abusive customer? Just don’t. Create great template email responses and outsource customer service to experts who have the time to follow through with every transaction.
6. Monitor your ASINs. Do you have problematic ASINs that make up a significant portion of your returns or customer complaints? Pull those suckers and solve the problems. Amazon is going to hold you responsible if they perceive your products are fraudulent.

No, Virginia, there isn’t a 30-day grace period before Amazon suspension.

 

The updated Business Solutions Agreement may signal minor operational changes like a “grace period”, but Risk Management still prevails.

This week, Amazon announced changes to the Amazon Services Business Solutions Agreement. This is essentially the “terms of service” under which third-party sellers operate. Almost immediately, many in the Amazon seller community began hailing the changes as a 30-day “grace period” before account suspension. I’m here to tell you – that simply is not what the new agreement says.

A review of the red-lined version reveals these changes:

1. Amazon has upped its game for account verification. No longer can you simply sign up or provide only a driver’s license/passport and utility bill. Amazon now says you must provide “any other information we may request.” Takeaway? They are making it much harder to establish the kind of duplicate/second accounts that so many sellers have created in the past.
2. Amazon will give you 30 days’ notice before terminating your “use of services” or Business Solutions Agreement. Sounds nice, right? But if you read a little more, Amazon gives itself every possible out. They can suspend or terminate your use of any services immediately for:
   • Material breach of the BSA. That is about as broad as it gets.
   • Failure to cure within seven days of a cure notice. In other words, if you get a warning in performance notifications, and you don’t fix it, you’re done. This is already the standard for many suspensions.
   • You exposed Amazon to liability toward a third party. That could mean a rights owner/brand owner who filed an IP claim, anyone complaining about fake merchandise, product liability issues, customers not receiving orders, etc.
   • Your account has been or “may be used” for deceptive, fraudulent or illegal activity. Again, this can include so many things: inauthentic merchandise, counterfeit merchandise, not shipping products, platform manipulation, fake reviews and more. If you don’t have pristine invoices that Amazon accepts, you fall into this bucket.
   • You have harmed or “might harm” other sellers, customers, or “Amazon’s legitimate interests.” Again, this is terribly broad. Amazon could claim that ANY seller “might harm” Amazon’s legitimate interests.
3. Amazon will tell you about suspension or termination, including the reason and any options to appeal. Amazon already does this.
4. Amazon will not tell you the reason for suspension or termination if they believe it will “hinder the investigation or prevention of deceptive, fraudulent, or illegal activity, or will enable you to circumvent our safeguards.” In other words, Amazon is not going to provide information that will put its risk management practices in jeopardy.
5. Amazon retains the right to halt any of your transactions, prevent or restrict access to services, or take any other action to restrict access or availability of any inaccurate listing, any inappropriately categorized items, any unlawful items, or any items otherwise prohibited.
6. You have 30 days to appeal A-to-z claims.
7. The language for FBA reimbursements has changed from “reimburse” to “compensate.” In other words, they will decide how much you deserve to be paid for your inventory – not you. This has always been the case. Now it’s in writing.
8. Amazon can immediately dispose of your inventory if they decide it is a safety risk, or a liability risk; if you engaged in fraudulent or illegal activity; or if Amazon terminated your account and is exposed to liability. In other words, if you cannot prove the inventory is valid and authentic, they can throw it away. Right now. Amazon has always had the right to destroy inventory they believed was risky. Again, nothing has changed.
9. You have 30 days to appeal customer returns that you think were made in error.
10. Everything in the prior agreement regarding MWS has been replaced with language about the API. I haven’t analyzed this and will take more time to read it later. It’s long and complex.

So, as you can see, Amazon still retains all of the power.

Why? Risk management. Amazon must control the platform to prevent fraud and abuse. Will Amazon’s SOP change? Maybe a little. They might edit some emails or timeframes as well.

But overall, very little will change. It’s still Amazon’s platform. Don’t fall for the “grace period.” And no, Virginia, it’s not a kinder, gentler platform.

Designing A Better Design Handoff File In Figma

 Practical tips to enhance the handoff process between design and development in product development. With guidelines for effective communication, documentation, design details, version control, and plugin usage.

Creating an effective handoff process from design to development is a critical step in any product development cycle. However, as any designer knows, it can be a nerve-wracking experience to send your carefully crafted design off to the dev team. It’s like waiting for a cake to bake — you can’t help but wonder how it will evolve in the oven and how it will taste when you take it out of the oven.

The relationship between designers and developers has always been a little rocky. Despite tools like Figma’s Inspect feature (which allows developers to inspect designs and potentially convert them to code in a more streamlined way), there are still many barriers between the two roles. Often, design details are hidden within even more detailed parts, making it difficult for developers to accurately interpret the designer’s intentions.

For instance, when designing an image, a designer might import an image, adjust its style, and call it done. More sophisticated designers might also wrap the image in a frame or auto layout so it better matches how developers will later convert it to code. But even then, many details could still be missing. The main problem here is that designers typically create their designs within a finite workspace (a frame with a specific width). In reality, however, the design elements will need to adapt to a variety of different environments, such as varying device sizes, window widths, screen resolutions, and other factors that can influence how the design is displayed. Therefore, developers will always come back with the following questions:

• What should be the minimum/maximum width/height of the image?
• What is its content style?
• What effects need to be added?

As in reality, these are the details needed to be addressed.

Designers, let’s face the truth: there’s no perfect handoff.

Every developer works, thinks, and writes code differently, which means there is no such thing as the ideal handoff document. Instead, our focus should be on creating a non-perfect but still effective and usable handoff process.

“

In this article, we will explore how to create a design handoff document that attempts to strike the right balance between providing developers with the information they need while still allowing them the flexibility to bring the design to life in their own way.

How Can The Handoff Files Be improved?

1. Talk To Developers More Often

Design is often marked as complete once the design handoff file is created and the developers start transforming it into code. However, in reality, the design is only complete when the user finds the experience pleasant.

Therefore, crafting the design handoff file and having the developer help bring your design to the user is essentially another case study on top of the one you have already worked on. To make it perfect, just as you would talk to users, you also need to communicate with engineers — to better understand their needs, how they read your file, and perhaps even teach them a few key things about using Figma (if Figma is your primary design tool).

Here are a few tips you can teach your developers to make their lives easier when working with Figma:

Show Developers The Superpower Of The Inspect Panel #

Figma’s Inspect feature allows developers to see the precise design style that you’ve used, which can greatly simplify the development process. Additionally, if you have a design library in place, Inspect will display the name of each component and style that you’ve used. This can be incredibly helpful for developers, especially if they’re working with a style guide, as they can use the component or style directly to match your design with ease.

In addition to encouraging developers to take advantage of the Inspect panel, it’s sometimes helpful to review your own design in a read-only view. This allows you to see precisely what the developers will see in the Inspect panel and ensures that components are named accurately, colors are properly linked to the design system, and other vital details are structured correctly.

Share With Developers The Way To Export Images/Icons

Handling image assets, including icons, illustrations, and images, is also an essential part of the handoff process, as the wrong format might result in a poor presentation in the production environment.

Be sure to align with your developers on how they would like you to handle the icons and images. It could either be the case where they would prefer you to export all images and icons in a single ZIP file and share it with them or the case where they would prefer to export the images and icons on their own. If it’s the latter, it’s important to explain in detail the correct way to export the images and icons so that they can handle the export process on their own!

Encourage Them To Use Figma’s Commenting Feature

It’s common for developers to have questions about the design during the handoff process. To make it easier for everyone involved, consider teaching them to leave comments directly in Figma instead of sending you a message. This way, the comments are visible to everyone and provide context for the issue at hand. Additional features, such as comment reactions and the “mark as resolved” button, further enable better interaction between team members and help everyone keep track of whether an issue has been addressed or not.

Leverage Cursor Chat

If you and the developers are both working within the same Figma file, you can also make use of the cursor chat feature to clarify any questions or issues that arise. This can be a fun and useful way to collaborate and ensure that everyone is on the same page.

Use Figma Audio Chat

If you need to discuss a complex issue in more detail, consider using Figma’s audio chat feature. This can be a quick and efficient way to clarify any questions or concerns arising during the development process.

It’s important to keep in mind that effective collaboration relies on good communication. Therefore, it’s crucial to talk to your developers regularly and understand their approach to reading and interpreting your designs, especially when you first start working with them. This sets the foundation for a productive and successful partnership.

2. Documenting Design Decisions For You And Developers

We have to be honest, the reason why building our design portfolios often takes a lot of time is the fact that we do not document every design decision along the way, and so we need to start building the case studies later by trying our best to fetch the design files and all the stuff we need.

I find it useful to document my decisions in Figma, not only just designs but, if appropriate, also competitor analysis, problem statements, and user journeys, and leave the links to these pages within the handoff file as well. The developer might not read it, but I often hear from the developers in my team that they like it as they can also dig into what the designers think while working on the design, and they can learn tips for building a product from us as well.

3. Don’t Just Leave The Design There. Add The Details

When it comes to design, details matter — just leaving the design “as is” won’t cut it. Adding details not only helps developers better understand the design, but it can also make their lives easier. Here are some tips for adding those crucial design details to your handoff.

Number The Frame/Flow If Possible

I really like the Figma handoff template that Luis Ouriach (Medium, Twitter) created. The numbering and title pattern makes it easy for developers to understand which screen belongs to which flow immediately. However, it can be complicated to update the design later as the numbering and title need to be manually updated.

Note: While there are plugins available (like, for example, Renamed), which can help with renaming multiple frames and layers all at once, this workflow can still be inconvenient when dealing with more complicated naming patterns. For instance, updating “1. Welcome → 2. Onboarding → 3. Homepage” into “1. Welcome → 2. Onboarding → 3. Sign up → 4. Homepage” can become quite a hassle. Therefore, one alternative approach is to break down the screens into different tickets or user journeys and assign a number that matches each ticket/user journey.

Name The Layers If Possible

We talked about numbering/naming the frames, but naming the layers is equally important! Imagine trying to navigate a Figma file cluttered with layers and labels like “Frame 3123,” “Rectangle 8,” and “Circle 35.” This can be confusing and time-consuming for both designers and developers, as they need to sift through numerous unnamed layers to identify the correct one.

Well-named layers facilitate better collaboration, as team members can quickly locate and comprehend the purpose of each element. This also helps ensure consistency and accuracy when translating designs into code.

If you search around in Figma, you will find a number of plugins that can help you with naming the layers in a more systematic way.

Add The Details For Interaction: Make Use Of Figma’s Section Feature #

This might seem trivial, but I consider it important. Design details shouldn’t be something like “This design does X, and if you press that, it will do Y.” Instead, it’s crucial to include details like the hover state, initial state, max width/height, and the outcome of different use cases.

For this reason, I appreciate the new section feature that Figma has released. It allows me to have a big design at the top so that developers can see all of the design at once and then look at the section details for all the design and interaction details.

Make Use Of The Interactive Prototype And FigJam Features To Show The User Flow #

Additionally, try to share with the developers how the design screens connect to one another. You can use the interactive prototype feature within Figma to connect the screens and make them move so that developers can understand the logic. Alternatively, you can use FigJam to connect the screens, allowing developers to see how everything is connected at a glance.

4. The Secret Weapon Is Adding Loom Video

Loom video is a lifesaver for us. You only need to record it once, and then you can share it with anyone interested in the details of your design. Therefore, I highly recommend making use of Loom! For every design handoff file, I always record a video to walk through the design. For more complicated designs, I will record a separate video specifically describing the details so that I don’t need to waste other people’s time if they’re not interested.

To attach the Loom video, I use the Loom plugin and place it right beside the handoff file. Developers can play it as many times as needed without even disturbing you, asking you more questions, and so on.

→ Download the Loom Embed Figma plugin

5. The Biggest Fear: Version Control

In an ideal world, the design would be completely finalized before developers start coding. But in reality, design is always subject to adjustments, even after development has already begun. That’s why version control is such an important topic.

Although Figma has a branching feature for enterprise customers to create new designs in a separate branch, I find it helpful to keep a few extra things in your design file.

Have A Single Source Of Truth

Always ensure that the developer handoff file you share with your team is the single source of truth for the latest design. If you make any changes, update the file directly, and keep the original as a duplicate for reference. This will prevent confusion and avoid pointing developers to different pages in Figma.

If you have access to the branching feature in Figma, it can be highly beneficial to utilize it to further streamline your workflow. When I need to update a handoff file that I have already shared with the developers, my typical process is to create a new branch in Figma first. Then I update the developer handoff file in that branch, send it to the relevant stakeholders for review, and finally merge it back into the original developer handoff file once everything is confirmed. This ensures that the link to the developer handoff file remains unchanged for the developers.

Changelogs/Future Plan

Include a changelog in the handoff file to help developers understand the latest changes made to the design.

Similarly to changelogs, if you already know of future plans to adjust the design, write them down somewhere in Figma so that the developers can understand what changes are to be expected.

6. Make Use Of Plugins

There are also a number of plugins to help you with creating your handoff:

• EightShapes Specs
  EightShapes Specs creates specs for your design automatically with just one click.
  → Download the EightShapes Spec Figma plugin
• Autoflow
  Autoflow allows you to connect the screens visually without using FigJam.
  → Download the Autoflow Figma plugin
• Style Organizer
  Style Organizer allows you to make sure all of your styles are linked to your component/style so that developers won’t need to read hex code in any case.
  → Download the Style Organizer Figma plugin

7. The Ultimate Goal Is To Have A Design System

If you want to take things a step or two further, consider pushing your team to adopt a design system. This will enable the designs created in Figma to be more closely aligned with what developers expect in the code. You can match token names and name your layers/frames to align with how developers name their containers and match them in your design system.

Here are some of the benefits of using a design system:

• Consistency
  A design system ensures a unified visual language across different platforms, resulting in a more consistent user experience.
• Efficiency
  With a design system in place, designers and developers can reuse components and patterns, reducing the time spent on creating and updating individual elements.
• Collaboration
  A design system facilitates better communication between designers and developers by establishing a shared language and understanding of components and their usage.

Note: If you would like to dig deeper into the topic of design systems, I recommend reading some of the Smashing Magazine articles on this topic.

Conclusion: Keep Improving The Non-perfect

Ultimately, as I mentioned at the beginning, there’s no one-size-fits-all approach to developer handoff, as it depends on various factors such as product design and the engineers we work with. However, what we can do is work closely with our engineers, communicate with them regularly, and collaborate to find solutions that make everyone’s lives easier. Just like our designs, the key to successful developer handoff is prioritizing good communication and collaboration.

Further Reading

• “Design Handoffs,” Interactive Design Foundation
  Design handoff is the process of handing over a finished design for implementation. It involves transferring a designer’s intent, knowledge, and specifications for a design and can include visual elements, user flows, interaction, animation, copy, responsive breakpoints, accessibility, and data validations.
• “A Comprehensive Guide to Executing The Perfect Design-to-Development Handoff,” Phase Mag
• “Design Handoff 101: How to handoff designs to developers,” Zeplin Blog
  Before we had tools like Figma, design handoff was a file-sharing nightmare for designers. When UI designs were ready for developers to start building, nothing could begin until designers manually added redlines to their latest local design file, saved it as a locked Sketch or Photoshop file or a PDF, and made sure developers were working on the correct file after every update. But those design tools completely changed the way teams collaborate around UI design — including the way design handoff happens.
• “How to communicate design to developers (checklist),” Nick Babich
• “A Front-End Developer’s Ode To Specifications,” Dmitriy Fabrikant, Smashing Magazine
  In the physical world, no one builds anything without detailed blueprints because people’s lives are on the line. In the digital world, the stakes just aren’t as high. It’s called “software” for a reason: when it hits you in the face, it doesn’t hurt as much. But, while the users’ lives might not be on the line, design blueprints (also called design specifications or specs) could mean the difference between a correctly implemented design that improves the user experience and satisfies customers and a confusing and inconsistent design that corrupts the user experience and displeases customers. (Editor’s Note: Before tools like Figma were on the rise, it was even more difficult for designers and developers to communicate and so tools such as Specctr — which this article mentions — were much needed. As of today, this article from 2014 is a bit of a trip into history, but it will also give you a fairly good idea of what design blueprints are and why they are so important in the designer-developer handoff process.)
• “Everything Developers Need To Know About Figma,” Jurn van Wissen, Smashing Magazine
  Unlike most design software, Figma is free and browser-based, so developers can easily access the full design files making the developer handoff process significantly smoother. This article teaches developers who have nothing but a basic understanding of design tools everything they need to know to work with Figma.
• “Penpot, An Open-Source Design Platform Made For Designers And Developers Alike,” Mikołaj Dobrucki, Smashing Magazine
  In the ever-evolving design tools landscape, it can be difficult to keep up with the latest and greatest. In this article, we’ll take a closer look at Penpot, the first design and prototyping tool that’s fully open-source and based on open web standards, making it an ideal choice for both designers and developers. (Editor’s Note: Today, it’s not always “There’s only Figma.” There are alternatives, and this article takes a good look at one of them — Penpot.)
• “The Best Handoff Is No Handoff,” Vitaly Friedman, Smashing Magazine
  Design handoffs are inefficient and painful. They cause frustration, friction, and a lot of back and forth. Can we avoid them altogether? Of course, we can! Let’s see how to do just that.

Gating: Amazon gets Tough on Topicals

 

Amazon appears to have launched a new gating initiative. This time, the target is topicals, and the timeline looks to be rapid.

Like most Amazon gating initiatives, the requirements differ greatly by seller. The current push to the target is topicals and gate them by December 8th, seems to be an extension of some efforts from last fall. If we had to guess, Amazon is generating data from customer-reported safety issues and turning that into programmatic action to:

• Restrict highly risky items
• “Screen” sellers who are in the topicals space

While we suspect some of this may be algorithmic, the results are too inconsistent to be solely driven by a tool. We get the feeling there is probably a larger, more restrictive push coming for the Health & Personal Care arena, but we are not yet sure what that looks like.

In the meantime, this latest move seems like a quest to pick some low-hanging, obvious compliance problems fruit.

Looking at this situation, we have some general information and thoughts to offer.

Documentation requests for resellers
Most resellers are being asked for some combination of manufacturer’s invoices, MSDS pages, FDA certification and more.

In many cases, sellers are seeing their invoices rejected. Just like with counterfeit investigations, Amazon wants traditional invoices with:

• Complete contact information for the manufacturer, including email address and phone number
• Billing and shipping addresses for the buyer, as well as email address and phone number
• Quantity and description of items purchased
• Proof of payment

While we don’t think Amazon (especially Seller Support) has a clear “watchlist” of manufacturers, they are looking for inconsistencies:

• Incomplete/missing contact information for the manufacturer
• Missing dates, or dates that are 6 months or older
• Evidence the documents are altered
• Inconsistent address, name, or ship-to info when comparing the seller’s account details to the invoice/documents

If the invoice type is not the issue, and it has all the relevant information on it that Amazon is requesting, then the problem could be the supplier/manufacturer. Again, as far as we know, there are no codified processes for Seller Support to check for “bad” manufacturers who have been censured, lost their FDA credentials, and so on. But since the Category managers drive gating, it is likely they have added some checks to look for bad actors in the manufacturing space.

The challenge for private label sellers
Amazon is aware that it has a safety testing/compliance gap in its growing private label (PL) seller ranks. That’s why many PL sellers are being asked for documents and, in some cases, are being rejected. Amazon specifies to sellers what documentation they need. We are guessing some sellers do not have this, even for their own brands.

Here is a breakdown of what each item must contain:

Certificate of Analysis (COA):

• Manufacturer information
• Dated within 240 days
• List lot number and ingredients
• Be signed by the supplier

Good Manufacturing Practices (GMP) certificate:

• Include PL seller’s name and address
• Contain registration number, certification date and expiration date

Proof of FDA Registration / FDA Orange Book Application Number:

• Include FDA website screenshot
• Show name and address of the manufacturer. If you are the manufacturer, your name must match the legal business name and address in Seller Central
• List Registration Number
• State that the FDA Registration is “Valid”
• If you provide an FDA Orange Book Number, your legal business name in Seller Central must match

What’s a seller to do?

Whether you sell in topicals, supplements, baby or another risky category, let Amazon’s current actions be a warning to you:

• Do your research. Understand that Amazon cannot allow sellers to continue offering products that do not follow governmental and safety testing standards.
• Does your product require safety or other testing? Make sure you’ve ordered the testing, and that you’ve created an ongoing testing schedule.
• Do you use a contract manufacturer? Ensure they have all the FDA certifications on-hand, updated and available at all times.
• Don’t rely on your contract manufacturer or testing facilities to keep the paperwork. Maintain all your own records, so they are available at an instant’s notice.

A Guide To Redux Toolkit With TypeScript

 The Redux Toolkit documentation calls the library a better way to write Redux logic for React apps and a simple and efficient toolkit for Redux development. In this article, you will learn about the Redux toolkit by building an app that tracks project issues.

If you are a React developer working on a complex application, you will need to use global state management for your app at some point. React Redux is one of the most popular libraries for state management used by many developers. However, React Redux has a complex setup process that I’ve found inefficient, not to mention it requires a lot of boilerplate code. The official developer of Redux developed the Redux Toolkit to simplify the process.

This article is for those with enough knowledge of React and TypeScript to work with Redux.

About Redux

Redux is the global state management library for React applications. If you have used useState() hooks for managing your app state, you will find it hard to access the state when you need it in the other parts of the application. With useState() hooks, the state can be passed from the parent component to the child, and you will be stuck with the problem of prop drilling if you need to pass it to multiple children. That’s where Redux comes in to manage the application state.

Introducing Redux Toolkit

Redux Toolkit is a set of opinionated and standardised tools that simplify application development using the Redux state management library.

The primary benefit of using Redux Toolkit is that it removes the overhead of writing a lot of boilerplates like you’d have to do with plain Redux.

“

It eliminates the need to write standard Redux setup code, such as defining actions, reducers, and store configuration, which can be a significant amount of code to write and maintain.

Jerry Navi has a great tutorial that shows the full Redux setup process.

Why I Prefer Redux Toolkit Over Redux

The Redux Toolkit has several key features which make me use this library over plain Redux:

1. Defining reducers
   With Redux Toolkit, you can specify a slice with a few lines of code to define a reducer instead of defining actions and reducers separately, like Redux.
2. Immutability helpers
   Redux Toolkit includes a set of utility functions that make it easy to update objects and arrays in an immutable way. This makes writing code that follows the Redux principles of immutability simpler.
3. Built-in middleware
   Redux Toolkit includes built-in middleware that can handle asynchronous request tasks.
4. DevTools integration
   Redux Toolkit includes integration with the Redux DevTools browser extension, which makes it easier to debug and analyse Redux code.

Using Redux Toolkit To Build A Project Issue Tracker

I think the best way to explain the value and benefits of using Redux Toolkit is simply to show them to you in a real-world context. So, let’s develop an app with it that is designed to create and track GitHub issues.

You can follow along with the code examples as we go and reference the full code anytime by grabbing it from GitHub. There is also a live deployment of this example that you can check out.

Start creating a new React app with the following command:

yarn create react-app project_issue_tracker --template typescript

This generates a folder for our project with the basic files we need for development. The –template typescript part of the command is used to add TypeScript to the stack.

Now, let’s install the dependencies packages required for our project and build the primary UI for the application before we implement Redux Toolkit. First, navigate to the project_issue_tracker project folder we just created:

cd project_issue_tracker

Then run the following command to install Material UI and Emotion, where the former is a design library we can use to style components, and the latter enables writing CSS in JavaScript files.

yarn add @mui/material @emotion/react @emotion/styled

Now we can install Redix Toolkit and Redux itself:

yarn add @reduxjs/toolkit react-redux

We have everything we need to start developing! We can start by building the user interface.

Developing The User Interface

In this section, we will be developing the UI of the app. Open the main project folder and create a new components subfolder directly in the root. Inside this new folder, create a new file called ProjectCard.tsx. This is where we will write the code for a ProjectCard component that contains information about an open issue in the project issue tracker.

Let’s import some design elements from the Material UI package we installed to the new /components/ProjectCard.tsx file to get us started:

import React from "react";
import { Typography, Grid, Stack, Paper} from "@mui/material";
interface IProps {
    issueTitle: string
}
const ProjectCard : React.FC<IProps> = ({ issueTitle }) => {
    return(
        <div className="project_card">
            <Paper elevation={1} sx={{p: '10px', m:'1rem'}}>
                <Grid container spacing={2}>
                    <Grid item xs={12} md={6}>
                        <Stack spacing={2}>
                            <Typography variant="h6" sx={{fontWeight: 'bold'}}>
                                Issue Title: {issueTitle}
                            </Typography>
                            <Stack direction='row' spacing={2}>
                                <Typography variant="body1">
                                    Opened: yesterday
                                </Typography>
                                <Typography variant="body1">
                                    Priority: medium
                                </Typography>
                            </Stack>
                        </Stack>
                    </Grid>
                </Grid>
            </Paper>
        </div>
    )
}
export default ProjectCard;

This creates the project card that displays an issue title, issue priority level, and the time the issue was “opened.” Notice that we are using an issueTitle prop that will be passed to the ProjectCard component to render the issue with a provided title.

Now, let’s create the component for the app’s HomePage to display all the issues. We’ll add a small form to the page for submitting new issues that contain a text field for entering the issue name and a button to submit the form. We can do that by opening up the src/HomePage.tsx file in the project folder and importing React’s useState hook, a few more styled elements from Material UI, and the ProjectCard component we set up earlier:

import React, { useState } from "react";
import { Box, Typography, TextField, Stack, Button } from "@mui/material";
import ProjectCard from "./components/ProjectCard";
const HomePage = () => {
    const [textInput, setTextInput] = useState('');
    const handleTextInputChange = (e:any) => {
        setTextInput(e.target.value);
    };
    return(
        <div className="home_page">
            <Box sx={{ml: '5rem', mr: '5rem'}}>
                <Typography variant="h4" sx={{textAlign: 'center'}}>
                    Project Issue Tracker
                </Typography>
                <Box sx={{display: 'flex'}}>
                    <Stack spacing={2}>
                        <Typography variant="h5">
                            Add new issue
                        </Typography>
                        <TextField 
                        id="outlined-basic" 
                        label="Title" 
                        variant="outlined" 
                        onChange={handleTextInputChange}
                        value={textInput}
                        />
                        <Button variant="contained">Submit</Button>
                    </Stack>
                </Box>
                <Box sx={{ml: '1rem', mt: '3rem'}}>
                    <Typography variant="h5" >
                        Opened issue
                    </Typography>
                        <ProjectCard issueTitle="Bug: Issue 1" />
                        <ProjectCard issueTitle="Bug: Issue 2" />
                </Box>
            </Box>
        </div>
    )
}
export default HomePage;

This results in a new HomePage component that a user can interact with to add new issues by entering an issue name in a form text input. When the issue is submitted, a new ProjectCard component is added to the HomePage, which acts as an index for viewing all open issues.

The only thing left for the interface is to render the HomePage, which we can do by adding it to the App.tsx file.

Using Redux Toolkit

Now that our UI is finalised, we can move on to implementing Redux Toolkit to manage the state of this app. We will use Redux Toolkit to manage the state of the ProjectCard list by storing all the issues in a store that can be accessed from anywhere in the application.

Before we move to the actual implementation, let’s understand a few Redux Toolkit concepts to help understand what we’re implementing:

1. createSlice
   This function makes it easy to define the reducer, actions, and the initialState under one object. Unlike the plain redux, you don’t need to use a switch for actions and need to define the actions separately. This function accepts an object as a name (i.e., the name of the slice) and the initial state of the store and the reducer, where you define all the reducers along with their action types.
2. configureStore
   This function is an abstraction for the Redux createStore() function. It removes the dependency of defining reducers separately and creating a store again. This way, the store is configured automatically and can be passed to the Provider.
3. createAsyncThunk
   This function simplifies making asynchronous calls. It automatically dispatches many different actions for managing the state of the calls and provides a standardised way to handle errors.

Let’s implement all of this! We will create the issueReducer with an addIssue() action that adds any new submitted issue to the projectIssues store. This can be done by creating a new file in src/redux/ called IssueReducer.ts with this code:

// Part 1
import { createSlice, PayloadAction } from "@reduxjs/toolkit"

// Part 2
export interface IssueInitialState {
    projectIssues: string[]
}
const initialState: IssueInitialState = {
    projectIssues: []
}

// Part 3
export const issueSlice = createSlice({
    name: 'issue',
    initialState,
    reducers: {
        addIssue: (state, action: PayloadAction<string>) => {
            state.projectIssues = [...state.projectIssues, action.payload]
        }
    }
})

// Part 4
export const { addIssue } = issueSlice.actions
export default issueSlice.reducer

Let’s understand each part of the code. First, we are importing the necessary functions from the Redux @reduxjs/toolkit package.

Then, we create the type definition of our initial state and initialise the initialState for the issueReducer. The initialState has a projectIssues[] list that will be used to store all the submitted issues. We can have as many properties defined in the initialState as we need for the application.

Thirdly, we are defining the issueSlice using Redux Toolkit’s createSlice function, which has the logic of the issueReducer as well as the different actions associated with it. createSlice accepts an object with a few properties, including:

• name: the name of the slice,
• initialState: the initial state of the reducer function,
• reducers: an object that accepts different actions we want to define for our reducer.

The slice name for the issueReducer is issueSlice. The initalState of it is defined, and a single adIssue action is associated with it. The addIssue action is dispatched whenever a new issue is submitted. We can have other actions defined, too, if the app requires it, but this is all we need for this example.

Finally, in the last part of the code, we export the actions associated with our reducer and the issueSlice reducer. We have fully implemented our issueReducer, which stores all the submitted issues by dispatching the addIssue action.

Now let’s configure the issueReducer in our store so we can use it in the app. Create a new file in src/redux/ called index.ts, and add the following code:

import { configureStore } from "@reduxjs/toolkit";
import IssueReducer from "./IssueReducer";
export const store = configureStore({
    reducer: {
        issue: IssueReducer
    }
})
export type RootState = ReturnType<typeof store.getState>
export type AppDispatch = typeof store.dispatch

This code configures and creates the store using the configureStore() function that accepts a reducer where we can pass all of the different reducers.

We are done adding the reducer and configuring the store with Redux Toolkit. Let’s do the final step of passing the store to our app. Start by updating the App.tsx file to pass the store using the Provider:

import React from 'react';
import { Provider } from "react-redux"
import { store } from './redux';
import HomePage from './HomePage';
function App() {
    return (
        <div className="App">
            <Provider store={store}>
                <HomePage />
            </Provider>
        </div>
     );
}
export default App;

Here, you can see that we are importing the store and directly passing through the Provider. We don’t need to write anything extra to create a store or configure DevTools like we would using plain Redux. This is definitely one of the ways Redux Toolkit streamlines things.

OK, we have successfully set up a store and a reducer for our app with Redux Toolkit. Let’s use our app now and see if it works. To quickly sum things up, the dispatch() function is used to dispatch any actions to the store, and useSelector() is used for accessing any state properties.

We will dispatch the addIssue action when the form button is clicked:

const handleClick = () => {
    dispatch(addIssue(textInput))
}

To access the projectIssue list stored in our reducer store, we can make use of useSelector() like this:

const issueList = useSelector((state: RootState) => state.issue.projectIssues)

Finally, we can render all the issues by map()-ping the issueList to the ProjectCard component:

{
    issueList.map((issue) => {
        return(
            <ProjectCard issueTitle={issue} />
        )
    })
}

The final code for HomePage.tsx looks like this:

import React, { useState } from "react";
import { useDispatch, useSelector } from "react-redux";
import { RootState } from "./redux/index"
import { Box, Typography, TextField, Stack, Button } from "@mui/material";
import ProjectCard from "./components/ProjectCard";
import { addIssue } from "./redux/IssueReducer";
const HomePage = () => {
    const dispatch = useDispatch();
    const issueList = useSelector((state: RootState) => state.issue.projectIssues)
    const [textInput, setTextInput] = useState('');
    const handleTextInputChange = (e:any) => {
        setTextInput(e.target.value);
    };
    const handleClick = () => {
        dispatch(addIssue(textInput))
    }
    return(
        <div className="home_page">
            <Box sx={{ml: '5rem', mr: '5rem'}}>
                <Typography variant="h4" sx={{textAlign: 'center'}}>
                    Project Issue Tracker
                </Typography>
                <Box sx={{display: 'flex'}}>
                    <Stack spacing={2}>
                        <Typography variant="h5">
                            Add new issue
                        </Typography>
                        <TextField 
                        id="outlined-basic" 
                        label="Title" 
                        variant="outlined" 
                        onChange={handleTextInputChange}
                        value={textInput}
                        />
                        <Button variant="contained" onClick={handleClick}>Submit</Button>
                    </Stack>
                </Box>
                <Box sx={{ml: '1rem', mt: '3rem'}}>
                    <Typography variant="h5" >
                        Opened issue
                    </Typography>
                    {
                        issueList.map((issue) => {
                            return(
                                <ProjectCard issueTitle={issue} />
                            )
                        })
                    }
                </Box>
            </Box>
        </div>
    )
}
export default HomePage;

Now, when we add and submit an issue using the form, that issue will be rendered on the homepage.

This section covered how to define any reducer and how they’re used in the app. The following section will cover how Redux Toolkit makes asynchronous calls a relatively simple task.

Making Asynchronous Calls With Redux Toolkit

We implemented our store to save and render any newly added issue to our app. What if we want to call GitHub API for any repository and list all the issues of it in our app? In this section, we will see how to use the createAsyncThunk() API with the slice to get data and render all the repository issues using an API call.

I always prefer to use the createAsyncThunk() API of the redux toolkit because it standardises the way different states are handled, such as loading, error, and fulfilled. Another reason is that we don’t need to add extra configurations for the middleware.

Let’s add the code for creating a GithubIssue reducer first before we break it down to understand what’s happening. Add a new GithubIssueReducer.ts file in the /redux folder and add this code:

import { createAsyncThunk, createSlice } from '@reduxjs/toolkit';
export const fetchIssues = createAsyncThunk<string[], void, { rejectValue: string }>(
  "githubIssue/fetchIssues",
  async (_, thunkAPI) => {
    try {
      const response = await fetch("https://api.github.com/repos/github/hub/issues");
      const data = await response.json();
      const issues = data.map((issue: { title: string }) => issue.title);
      return issues;
    } catch (error) {
      return thunkAPI.rejectWithValue("Failed to fetch issues.");
    }
  }
);
interface IssuesState {
  issues: string[];
  loading: boolean;
  error: string | null;
}
const initialState: IssuesState = {
  issues: [],
  loading: false,
  error: null,
};
export const issuesSliceGithub = createSlice({
  name: 'github_issues',
  initialState,
  reducers: {},
  extraReducers: (builder) => {
    builder
      .addCase(fetchIssues.pending, (state) => {
        state.loading = true;
        state.error = null;
      })
      .addCase(fetchIssues.fulfilled, (state, action) => {
        state.loading = false;
        state.issues = action.payload;
      })
      .addCase(fetchIssues.rejected, (state, action) => {
        state.loading = false;
        state.error = action.error.message || 'Something went wrong';
      });
  },
});
export default issuesSliceGithub.reducer;

Let’s understand the fetchIssues part first:

1. We are using the createAsyncThunk() API provided by the Redux Toolkit. It helps create asynchronous actions and handles the app’s loading and error states.
2. The action type name is the first argument passed to createAsyncThunk(). The specific action type name we have defined is githubIssue/fetchIssues.
3. The second argument is a function that returns a Promise, which resolves to the value that dispatches the action. This is when the asynchronous function fetches data from a GitHub API endpoint and maps the response data to a list of issue titles.
4. The third argument is an object that contains configuration options for the async thunk. In this case, we have specified that the async thunk will not be dispatched with any arguments (hence the void type) and that if the Promise returned by the async function is rejected, the async thunk will return an action with a rejected status along with a rejectValue property that contains the string “Failed to fetch issues.”

When this action is dispatched, the API calls will be made, and the githubIssuesList data will be stored. We can follow this exact same sequence of steps to make any API calls we need.

The second section of the code is similar to what we used when we created the issueSlice, but with three differences:

1. extraReducers
   This object contains the reducers logic for the reducers not defined in the createSlice reducers object. It takes a builder object where different cases can be added using addCase for specific action types.
2. addCase
   This method on the builder object creates a new case for the reducer function.
3. API call states
   The callback function passed to the addCase method is dispatched by createAsyncThunk(), which updates the different store objects based on the API call states (pending, fulfilled, and error).

We can now use the GithubIssue reducer actions and the store in our app. Let’s add the GithubIssueReducer to our store first. Update the /redux/index.ts file with this code:

import { configureStore } from "@reduxjs/toolkit";
import { useDispatch } from "react-redux";
import IssueReducer from "./IssueReducer";
import GithubIssueReducer from "./GithubIssueReducer";
export const store = configureStore({
    reducer: {
        issue: IssueReducer,
        githubIssue: GithubIssueReducer
    }
})
export type RootState = ReturnType<typeof store.getState>
export type AppDispatch = typeof store.dispatch
export const useAppDispatch = () => useDispatch<AppDispatch>()

We just added the GithubIssueReducer to our store with the name mapped to githubIssue. We can now use this reducer in our HomePage component to dispatch the fetchIssues() and populate our page with all the issues received from the GitHub API repo.

import React, { useState, useEffect } from "react";
import { useSelector } from "react-redux";
import { useAppDispatch, RootState, AppDispatch } from "./redux/index";
import { Box, Typography, TextField, Stack, Button } from "@mui/material";
import ProjectCard from "./components/ProjectCard";
import { addIssue } from "./redux/IssueReducer";
import { fetchIssues } from "./redux/GithubIssueReducer";
const HomePage = () => {
    const dispatch: AppDispatch = useAppDispatch();
    const [textInput, setTextInput] = useState('');
    const githubIssueList = useSelector((state: RootState) => state.githubIssue.issues)
    const loading = useSelector((state: RootState) => state.githubIssue.loading);
    const error = useSelector((state: RootState) => state.githubIssue.error);
    useEffect(() => {
        dispatch(fetchIssues())
      }, [dispatch]);
    
    if (loading) {
      return <div>Loading...</div>;
    }
  
    if (error) {
      return <div>Error: {error}</div>;
    }
    const handleTextInputChange = (e:any) => {
        setTextInput(e.target.value);
    };
    const handleClick = () => {
        console.log(textInput)
        dispatch(addIssue(textInput))
    }
    return(
        <div className="home_page">
            <Box sx={{ml: '5rem', mr: '5rem'}}>
                <Typography variant="h4" sx={{textAlign: 'center'}}>
                    Project Issue Tracker
                </Typography>
                <Box sx={{display: 'flex'}}>
                    <Stack spacing={2}>
                        <Typography variant="h5">
                            Add new issue
                        </Typography>
                        <TextField 
                        id="outlined-basic" 
                        label="Title" 
                        variant="outlined" 
                        onChange={handleTextInputChange}
                        value={textInput}
                        />
                        <Button variant="contained" onClick={handleClick}>Submit</Button>
                    </Stack>
                </Box>
                <Box sx={{ml: '1rem', mt: '3rem'}}>
                    <Typography variant="h5" >
                        Opened issue
                    </Typography>
                    {
                        githubIssueList?.map((issue : string) => {
                            return(
                                <ProjectCard issueTitle={issue} />
                            )
                        })
                    }
                </Box>
            </Box>
        </div>
    )
}
export default HomePage;

This updates the code in HomePage.tsx with two minor changes:

1. We dispatch fetchIssue and use the createAsync() action to make the API calls under the useEffect hook.
2. We use the loading and error states when the component renders.

Now, when loading the app, you will first see the “Loading” text rendered, and once the API call is fulfilled, the issuesList will be populated with all the titles of GitHub issues fetched from the repo.

Once again, the complete code for this project can be found on GitHub. You can also check out a live deployment of the app, which displays all the issues fetched from GitHub.

Conclusion

There we have it! We used Redux Toolkit in a React TypeScript application to build a fully functional project issue tracker that syncs with GitHub and allows us to create new issues directly from the app.

We learned many of the foundational concepts of Redux Toolkit, such as defining reducers, immutability helpers, built-in middleware, and DevTools integration. I hope you feel powered to use Redux Toolkit effectively in your projects. With Redux Toolkit, you can improve the performance and scalability of your React applications by effectively managing the global state.