Forem: ClickPesa

Understanding ClickPesa Payment Gateway Integrations: Methods and Use Cases

Benedict Steven — Wed, 25 Sep 2024 18:13:58 +0000

In today’s fast-paced digital economy, businesses need reliable, seamless payment solutions to serve customers and suppliers effectively. ClickPesa as a licensed payments system provider, offers a suite of integration methods that enable businesses to support payments collection and disbursement functionalities seamlessly into their systems. ClickPesa Payment Gateway supports three integration methods: Embedded Integration, Hosted Integration, and API Integration. Each method is tailored to specific business needs and technical capabilities.

1. Embedded Integration

What is Embedded Integration?

Embedded Integration allows businesses to integrate ClickPesa’s payment functionalities directly into their websites or applications using customizable widgets. It allows businesses and their customers to complete transactions without leaving the business’s site or application, providing a seamless user experience while leaving the payment processing intrinsic to the ClickPesa Payment Gateway.

Use Cases for Embedded Integration:

SMBs Looking for Quick Setup: Small businesses that need a fast, easy-to-implement payment solution can use Embedded Integration to add payment functionality to their platforms without complex development.
Startups and Fast-Growing Platforms: Startups can quickly launch payment services using ClickPesa’s widgets, enabling them to focus on scaling their core offerings.
Platforms with Limited Development Resources: Businesses without large development teams can use Embedded Integration to offer payments without the overhead of custom-built solutions.

When to Use Embedded Integration:

Rapid Deployment: If you need to launch payments quickly and with minimal development effort, Embedded Integration is the best fit.
Simplified Setup: If your business doesn’t have a dedicated development team or wants to avoid managing payments directly, Embedded Integration offers a quick, simple solution.
Basic Customization: You can adjust the appearance of the payment widget to match your branding without complex coding.

When Not to Use Embedded Integration:

High Customization Needs: If your business requires a highly tailored payment flow with unique UI/UX features, Embedded Integration may not offer enough flexibility.
Complex Transaction Logic: For businesses needing advanced payment logic, a more customizable solution like API Integration would be more appropriate.

Development Considerations:

Minimal Technical Expertise: Embedded Integration doesn’t require extensive technical resources. Simply importing the widget into your app or website allows you to start making transactions without needing to manage security or infrastructure.
Security: In Embedded Integration, security is handled within the widget itself, meaning no API keys are required, which reduces the risk of exposing sensitive information. This makes Embedded Integration inherently more secure compared to Hosted or API options where API keys are involved.

Getting started:

Take a look at the embedding integration documentation.

2. Hosted Integration

What is Hosted Integration?

Hosted Integration allows business systems to use ClickPesa’s API to generate unique, secured and short-living hosted links. The links can be used by the business to make payouts or be shared with customers to collect payments. A business system initiates a transaction, the hosted page confirms it, and ClickPesa Payment Gateway processes it and responds the results back to the business’s system. Offering a seamless order processing securely.

Use Cases for Hosted Integration:

Small to Medium-Sized Businesses (SMBs): Businesses that want to initiate payments within their system but do not wish to manage complex payment infrastructure can use Hosted Integration to generate links for customers to complete transactions.
Invoicing Platforms: Businesses that send invoices to clients can use Hosted Integration to generate secure payment links, allowing clients to pay without the need to embed payment features into their system.
Startups and Non-Tech-Heavy Businesses: Startups or businesses with limited technical resources can initiate transactions within their app or system and have customers complete payments externally on ClickPesa’s hosted page.

When to Use Hosted Integration:

Transaction Initiation with Minimal Setup: If your business wants to initiate payments within your system but doesn’t need full control over the transaction process, Hosted Integration provides a quick and secure way to complete transactions.
Link-Based Payments: If your business sends payment links to customers (e.g., via email or messaging), Hosted Integration is ideal because it allows users to complete payments outside your main application.
Ease of Payment Processing: When you want to manage transaction initiation internally but prefer to hand off the actual payment processing to ClickPesa, Hosted Integration provides an easy solution.

When Not to Use Hosted Integration:

Need for Full Customization: If your business requires a fully customized payment flow where you control every step of the transaction process, Hosted Integration may not offer enough flexibility.
Real-Time On-Site Payments: For businesses that require customers to complete payments directly on their site or within their app, without being redirected, Embedded or API Integration may be a better choice.

Development Considerations:

API-Based Setup: Hosted Integration involves using ClickPesa’s API to generate payment links, which are then used to complete transactions on a hosted page. This reduces the technical burden of managing payments internally, while still offering flexibility in how transactions are initiated.
Security: Hosted Integration requires API keys, which if mishandled can pose security risks. Although ClickPesa’s infrastructure ensures payment security, extra care must be taken to properly secure API keys. For sensitive actions like payouts, an additional security layer is applied using two-factor authentication (2FA) via OTP to the user’s phone.

Getting started:

Get started with hosted integration.

3. API Integration

What is API Integration?

API Integration offers the most flexibility by allowing businesses to fully customize the integration of ClickPesa Payment Gateway functionalities into their existing systems. The gateway provides RESTful APIs to authenticate, initiate and manage business transactions. API’s provide businesses the ability to create highly customizable user experience that fits their unique requirements and infrastructure while staying compliant and secure.

Use Cases for API Integration:

Large Enterprises: Large organizations can integrate ClickPesa’s payment APIs with their existing systems to streamline payment processing and manage high transaction volumes.
Fintech Platforms: Companies building financial products such as wallets, peer-to-peer lending platforms, or multi-party payments will benefit from the flexibility and customization that APIs offer.
Marketplaces: Marketplaces that need to handle complex payment flows between buyers and sellers, including escrow services, can leverage APIs for full control over their transactions.

When to Use API Integration:

Full Control Over Payment Flow: If your business needs total control over the payment experience, including custom features like multi-party transactions or integrating with third-party systems, API Integration is the best fit.
Deep Integration with Internal Systems: API Integration is ideal for businesses that need payments tightly connected to internal systems, like accounting software or CRM tools.
Highly Customizable: If you require advanced customization and development flexibility, API Integration offers the highest degree of control.

When Not to Use API Integration:

Lack of Development Resources: If your business doesn’t have a dedicated technical team or the capacity to manage a custom integration, API Integration might be too complex.
Urgent Launch Needs: If you need to get payments up and running quickly, API Integration’s longer development time and resource requirements might not be suitable.

Development Considerations:

High-Level Technical Expertise: API Integration requires in-house development expertise, as it involves building a custom payment solution and maintaining the infrastructure. It’s a great option for businesses with the technical capacity to develop and manage a fully customized payment flow.
Security: Like Hosted Integration, API Integration relies on API keys. These must be carefully managed to avoid unauthorized access. For sensitive operations like payouts, additional layers of security, such as 2FA, are implemented.

Getting started:

API Integration is now in Beta testing. Reach out to tech@clickpesa.com for early access.

Choosing the Right Integration Method for Your Business

Selecting the right integration method depends on the size of your business, your technical capabilities, and your customization needs:

Embedded Integration: Ideal for businesses that need a fast-to-market solution with minimal setup and technical expertise. This option allows for a seamless, customizable payment experience. No Interaction with API’s, No Need to Create UI.
Hosted Integration: Best for companies prioritizing ease of use and minimal technical management. Hosted Integration is simple to implement and eliminates the need for handling payment data directly. Minimal Interaction with API’s, No Need to Create UI
API Integration: Suitable for large enterprises or businesses with dedicated development teams looking for full control and integration into their infrastructure. Full Interaction via API’s, Need to Create UI

At ClickPesa, we strive to provide flexible payment solutions that meet the needs of every business. Explore our Developers documentation today to understand the technicality and choose the integration method that fits your business requirements.

Sell your products online with one API call; A technical guide to ClickPesa checkout link integration

Neema Adam — Wed, 14 Jun 2023 17:17:35 +0000

One of the newest features that we offer at ClickPesa is a checkout page.

ClickPesa's checkout page allows users to create a checkout page from their website or application for their customers to pay for products or services.

Creating a checkout page only takes one API call to ClickPesa and you will receive a checkout URL that can be shared with the customer to collect payments.

Here is what you need...

Base URL: https://sandbox.clickpesa.com/webshop/generate-checkout-url

Payload:

{
  orderItems: [
    {
      name: 'Name of your product',
      product_type: 'DIGITAL_PRODUCT or PRODUCT',
      download_file_key: 'URL to file download', //OPTIONAL
      unit: 'unit of this item eg 1pc',
      price: 'price of the product',
      quantity: 'quantity of the product, eg 10',
    },
  ],
  orderReference: 'your order reference',
  merchantId: 'your merchant id',
  callbackURL: 'https://your_callback_url.com', //OPTIONAL
}

Here is a table to further explain each field that is added to the payload for checkout URL creation

Example:

curl --request POST \
  --url https://sandbox.clickpesa.com/webshop/generate-checkout-url \
  --header 'Content-Type: application/json' \
  --data '{
    "orderItems": [
        {
            "name": "Very cool ebook",
            "product_type": "DIGITAL_PRODUCT",
            "download_file_key": "uploads/c0f5a69d-28e8-434c-93ae-0e9dab972bb0.zip", //optional
            "unit": "1 pc(s)",
            "price": 25000,
            "quantity": 1
        },
        {
            "name": "Very cool book hardcopy",
            "product_type": "PRODUCT",
            "unit": "1 pc(s)",
            "price": 40000,
            "quantity": 1
        }
    ],
    "orderReference": "SHOP0.273114256151528d",
    "merchantId": "5f9beaa89c8d037a9b4f795d",
    "callbackURL":"http://hertha.biz" //OPTIONAL
}'

The above request will return the following response, which is a unique URL for the order's checkout page:

https://demo.checkout.clickpesa.com/checkout?serviceID=88&cartItemsCount=2&items=%5B%7B%22name%22:%22DIGITAL%20product%20THis%20Is%20a%20long%20lng%20test%20Maybe%20it%20is%22,%22product_type%22:%22DIGITAL_PRODUCT%22,%22download_file_key%22:%22uploads/c0f5a69d-28e8-434c-93ae-0e9dab972bb0.zip%22,%22unit%22:%221%20pc(s)%22,%22price%22:25000,%22quantity%22:1%7D,%7B%22name%22:%22TEST%20Cylinder%22,%22product_type%22:%22PRODUCT%22,%22unit%22:%22100%20pc(s)%22,%22price%22:50000,%22quantity%22:1%7D%5D&merchantID=5f9beaa89c8d037a9b4f795d&subtotal=75000&totalPrice=75000&discount=0&referenceID=SHOP0.273114256151528d

You can then share the URL with a customer via SMS/Email/WhatsApp or any other communication channel you have in place.

PRO TIP:

You can use services like https://www.shorturl.at to shorten the URL before sharing it with your customer. It's free.

When a customer opens the URL, they will get to the checkout page with all the details of the order.

Once a customer completes the payment, a notification will be shared via the callback URL added early on the request. The payload to the callback URL will have the following data:

{
  status: 'SUCCESS' | 'PROCESSING' | 'FAILED' | 'CANCELED',
  paymentReference: string, // Payment reference ID in our system
  orderReference: string, // Order reference ID you provided during checkout page creation
  collectedAmount: string, // Amount collected if the transaction is successful
  collectedCurrency: string, // Currency, currently TZS | USD
  message: string, // eg. 'Payment received'
}

If you don't have a callback URL in place, ClickPesa also provides an administration dashboard that you can use to track all your orders and their payment statuses. It's free!

Contact ClickPesa at info@clickpesa.com to get started. Takes a day max.

Transitioning from a designer to a frontend developer

Neema Adam — Mon, 08 May 2023 09:29:17 +0000

Transitioning from a designer to a self-taught front-end developer can be a challenging but rewarding experience. Acknowledging the learning curve and being prepared to learn is the first step toward achieving this goal. For successful learning, you can find learning resources that work for you, such as online courses, tutorials, or documentation. Remember to set goals and track your progress to help you stay motivated throughout the process.

In the following sections, I am excited to go through some tips that helped me successfully transition into this new career path.

Embrace the Learning Curve

Designing and developing share some common aspects but also require different skill sets. As a designer, you might be familiar with UI/UX design principles, but front-end development involves coding, debugging, and building UIs from scratch.

Start by breaking down the required skills into smaller chunks beginning with the basics and working your way up. Since you are probably a beginner, here is a simple roadmap and an overwhelming roadmap that you can use if you can't make your own. There is also this cool youtube video by Coder Coder that could help make things less overwhelming.

There are many online resources available to help you learn front-end development. I learned everything I know online. I started with FreeCodeCamp, Sololearn, and W3Schools then added YouTube channels such as Traversy Media, FreeCodeCamp, and Dev Ed. Find learning resources that work for you, such as online courses, tutorials, or documentation. The roadmap link I have shared also contains learning resources for each topic. Click on any topic and a drawer will open with links to different learning resources.

Build a Strong Foundation

Building a strong foundation in front-end development requires learning the basics of HTML, CSS, and JavaScript. These are the building blocks of any website. Once you understand these languages, you can start building more complex web pages and applications.

Learning how to use developer tools is also essential. These tools help you identify and fix issues with your code. Developer tools can also help you optimize your website's performance and improve its accessibility.

Familiarizing yourself with responsive design and accessibility is also important. Responsive design ensures that your website looks good on any device, while accessibility ensures that your website is usable by people with disabilities.

Apply Your Design Skills

One of the advantages of transitioning from a designer to a front-end developer is the ability to apply your design skills to create visually appealing websites or web applications.

Collaborate and Build Your Network

Collaborating with other developers and designers is an excellent way to build your network and learn from others. Joining developer communities and attending local meetups or events can help you to meet other like-minded individuals and build relationships.

Seeking feedback on your work is also important to improve and grow as a developer. Feedback can help you identify areas where you need improvement and areas where you excel.

Practice

Building projects and solving challenges is a great way to help you understand concepts that you will be learning and discover new things that you may want to pursue such as learning a frontend framework or exploring Canvas and WebGL. You can get project challenges from places like Frontend Mentor, CodePen Challenges, or Frontloops.

Conclusion

In conclusion, transitioning from a designer to a self-taught front-end developer can be a daunting task. As a beginner, It's easy to get bogged down trying to make sense of everything, but it's important to remember that building projects is a great way to discover new knowledge gaps and keep learning. Don't be afraid to make mistakes and seek feedback; this is how you'll continue to grow and develop your skills as a front-end developer. With determination and perseverance, you can achieve your goal and embark on an exciting and rewarding career in front-end development.

Thank you for reading. If you're interested in learning more about software development, fintech, and other related topics, be sure to check out the ClickPesa publication. Our team is constantly writing and publishing articles that cover a range of topics related to software development, product design, and entrepreneurship.

At ClickPesa, we are passionate about building products that help people and businesses succeed in today's digital economy. If you're interested in learning more about our products and services, be sure to visit our website and follow us on social media.

You don’t really need external testers

Omar — Mon, 08 May 2023 06:47:59 +0000

Or rather, before hiring one..
Consider unlocking the potential of developers to become effective testers.

Developers already possess half the skills of effective testers; Technical understanding.

In this article, we will explore other practices and strategies that can enhance developers testing skills to help them transition seamlessly to become effective testers.

1. Give testing the attention it deserves
To excel in testing, it is essential to approach this job with the same level of dedication as any other job in your daily work. Allocate sufficient time specifically for testing to ensure thoroughness and accuracy.

2. Understand product requirements
A strong understanding of product requirements allows developers to create test cases that accurately reflect the expected behavior of the software. As requirements are subject to change, clear communication and documentation paired with prototypes and demos, while breaking down complex requirements into smaller tasks will improve developers’ understanding of requirements.

3. Work with testing plans
A testing plan is crucial for setting clear objectives, defining test coverage, allocating resources, managing risks and facilitating communication in the testing process. It ensures that the testing effort is well-structured, coordinated, and aligned with the project’s goals. Proper documentation is the key here.

4. Increase end-user interactions
By actively involving end-users during the testing process, developers gain valuable insights into real-world scenarios and user workflows.Ultimately, this collaborative approach enhances the effectiveness and relevance of testing, resulting in a higher quality and more user-centric software product.

5. Implement automated testing
Automated tests can be executed much faster than manual tests, allowing developers to quickly validate their code changes. Automated tests can be seamlessly integrated into continuous integration and deployment (CI/CD) pipelines, enabling frequent and reliable testing as part of the development process.

6. Participate in code reviews
During code reviews, developers have the opportunity to review and understand code written by their peers. This helps in knowledge sharing, exposing developers to different coding techniques, best practices, and design patterns. By learning from others’ code, developers can expand their understanding of software development and gain insights into effective testing strategies.

7. Increase Interaction with dedicated testers
Dedicated testers specialize in testing methodologies, techniques, and tools. By collaborating closely with them, developers can leverage their expertise to ensure comprehensive test coverage. Testers can identify areas that may have been overlooked and provide valuable insights on testing strategies and scenarios that developers may not have considered.

In conclusion, unlocking the potential of developers to become effective testers can lead to significant benefits for software development teams. By involving developers in testing, teams can reduce the time and cost associated with traditional testing methods, as well as improve the overall quality of their software.

However, it is important to recognize that this approach requires a cultural shift within the organization, as well as investment in training and resources to enable developers to acquire the necessary testing skills. With the right support and mindset, developers can become an invaluable asset to testing efforts, ultimately helping teams to deliver better software faster.

At ClickPesa, we are passionate about building products that help people and businesses succeed in today’s digital economy. If you’re interested in learning more about our products and services, be sure to visit our website and follow us on social media.

Create and deploy react components with bit.dev

Benedict Steven — Mon, 08 May 2023 06:22:59 +0000

React is one of the most popular JavaScript libraries for building user interfaces. One of the key benefits of React is its component-based architecture, which allows developers to create reusable UI components that can be shared across different projects.

Bit.dev is a platform that makes it easy to create and share React components.

There are several reasons why someone might need to use Bit.dev for their React components:

Reusability: Bit.dev allows developers to create and share reusable components across different projects and teams. This can greatly reduce development time and ensure consistency across projects.
Collaboration: Bit.dev provides tools for testing, versioning, and collaboration, making it easy for teams to work together on component development. This can help to improve code quality and reduce errors.
Scalability: Bit.dev is a distributed and scalable platform that can handle large-scale component-based development workflows. It provides a flexible and customizable workflow that can be adapted to the specific needs of different projects and teams.
Open-source community: Bit.dev has a thriving open-source community that contributes to the platform and creates new components. This can be a great resource for developers looking for inspiration or looking to contribute to open-source projects.
Integration: Bit.dev can integrate with other tools and platforms, such as Git and CI/CD pipelines, to create a seamless development workflow. This can help to streamline development processes and improve overall efficiency.

In this article, I'll walk you through the steps to create and deploy React components with Bit.dev.

To start creating components using bit, first we need to create accounts on bit.cloud.

Step 1: From the bit.cloud dashboard, create a scope, a place where you will be deploying your components.

Step 2: Install bit on your machine by following this set of commands

First install bvm



npm i -g @teambit/bvm

To verify that bvm is installed, run



bvm --version

if no bvm command is not found, follow this instructions

Step 3: Initialize your components project
Create new workspace by running



bit new react tasks-workspace --default-scope my-org.tasks-scope

Where:-
tasks-workspace: Workspace name
my-org: Organization / username
tasks-scope: default scope for the new components.

This by default will create a new workspace with components as a default scope.

Step 4: Create your first component.
To create your first component, cd tasks-workspace run



bit create react button

This will create a button component within components folder.
The created component will have a the following files

index.ts: Entry component file.
button.sx: Boiler plate for creating component.
button.spec.tsx: A file to write tests.
button.docs.mdx: A documentation file.
button.composition.tsx: A file for testing different variations of the component per creator's choice.

Run bit start to start the development server. Once the server is ready, on the browser, we should see this UI.
click on button component to open live preview of the created component.

Start editing the button component and preview changes on the browser.

In the component folder you can create multiple files such as stylesheet files, components files to support the main component. For now lets just make a button component work.



import React, { ReactNode } from 'react';

export type ButtonProps = {
  /**
   * a node to be rendered in the special component.
   */
  children?: ReactNode;
  /**
   * Onclick event
   */
  onClick?: () => void
};

export function Button({ children, onClick }: ButtonProps) {
  return (
    <button onClick={onClick}>
      {children}
    </button>
  );
}

Let's create two more components, title and input to complete a form with title, inputs and a button.

run



bit create react input

and



bit create react title

On title.tsx file in title folder add this code



import React, { ReactNode } from 'react';

export type TitleProps = {
  /**
   * a node to be rendered in the special component.
   */
  children?: ReactNode;
};

export function Title({ children }: TitleProps) {
  return <h1>{children}</h1>;
}

and on input.tsx in input folder add this code



import React, { CSSProperties, ChangeEvent } from 'react';

export type InputProps = {
  /**
   * label text
   */
  label: string;
  /**
   * input id
   */
  id?: string;
  /**
   * input type
   */
  type?: string;
  /**
   * on input change
   */
  onChange: (value: ChangeEvent<HTMLInputElement>) => void;
  /**
   * input value
   */
  value: string;
  /**
   * input style style
   */
  style?: CSSProperties;
};

export function Input({ label, id, type, onChange, value, style }: InputProps) {
  return (
    <label>
      <div>{label}</div>
      <input
        id={id}
        style={style}
        onChange={onChange}
        value={value}
        type={type}
      />
    </label>
  );
}

and on the input.composition.tsx add



import React, { useState } from 'react';
import { Input } from './input';

export const BasicInput = () => {
  const [value, setValue] = useState('');
  return (
    <Input
      label="Email"
      type="email"
      onChange={(e) => setValue(e.target.value)}
      value={value}
    />
  );
};

Update the docs and test on the live preview.

Step 5: Add test on the components.
bit uses jest under the hood to run react tests. Learn more about react testing here

Step 5: Use created components within your components project before deployment.

With bit, we can import other components within our components without deploying the library. how?
From the above created components, let's create a form component, call it login component which will include email and password inputs, submit button and title.

Run



bit create react login

and on login.tsx



import React, { useState } from 'react';
import { Input } from '@tasks-scope/components.input';
import { Title } from '@tasks-scope/components.title';
import { Button } from '@tasks-scope/components.button';

export type LoginProps = {
  onSubmit: (data: { email: string; password: string }) => void;
};

export function Login({ onSubmit }: LoginProps) {
  const [data, setData] = useState({
    email: '',
    password: '',
  });
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        onSubmit(data);
      }}
    >
      <Title>Welcome Back</Title>
      <Input
        value={data.email}
        onChange={(e) =>
          setData({
            ...data,
            email: e.target.value,
          })
        }
        label="Email"
      />
      <Input
        value={data.password}
        onChange={(e) =>
          setData({
            ...data,
            password: e.target.value,
          })
        }
        label="Password"
      />
      <Button>Submit</Button>
    </form>
  );
}

Now we have a working form component built with three other components.

Step 6: Install packages
There will be times that you will want to create a component but that component will need an external package to work, for instance one might need a styled-components package to create a component.
Run



bit install styled-components

This way one can use this package in any component they are creating

Step 7: Deploy your components

To deploy your library you need to login to bit cli,

run



bit login

This will open the browser and give you access to deploy your library.

Before deploying we need to tag all our components. Tagging components assigns new versions to our components.
run



bit tag

In .bitmap, we should see the new versions assigned to our new components.

To deploy the components, run



bit export

This will deploy your new component library.

To view your fresh components visit https://bit.cloud/your-username/tasks-workspace.

For an existing workspace when you want to edit your components or creating new components, first you will need to import all deployed components by running



bit import

And after making all changes, use the same process as we did while deploying components.

Step 8: Install and use your deployed components on your react project.

In your react project, install your components and start using them.

the first time you are installing your components in your project, you will need to configure your bit organization or username first by running



npm config set '@your-username:registry' https://node.bit.cloud

After the configuration you won't need to do that again in your projects.

Then run



npm i @your-username/components.login

Then you can start using your components as you used them in the composition files in your bit components.

Congratulations!!

Creating and deploying React components with Bit.dev is a powerful way to streamline your development workflow and make your components reusable across different projects. By following the steps outlined in this article, you can easily create, test, and share React components with other developers using the Bit.dev platform.

If you like this article, there are more like this in our blogs, follow us on dev.to/clickpesa, medium.com/clickpesa-engineering-blog and clickpesa.hashnode.dev

Happy Hacking!!

Testing React apps with Testing library

Neema Adam — Thu, 13 Apr 2023 00:11:29 +0000

Testing is an essential aspect of software development that ensures the quality and reliability of software products. React, being one of the most popular JavaScript frameworks, requires a robust testing strategy to ensure that the application functions as expected. Throughout this March and April, I had a chance to learn a lot about writing tests in React while building ClickPesa’s UI component library. In this article, I will share some of the things that I have learned.

Essential things you can test for in React components

Render: Ensure that the component renders without throwing any errors.
Props: Test that the component accepts and uses props correctly.
State: Test that the component updates its state correctly.
Events: Test that the component handles events correctly.
Lifecycle methods: Test that the component correctly handles its lifecycle methods such as componentDidMount, componentDidUpdate, and componentWillUnmount.
Snapshot testing: Use snapshot testing to ensure that the component's UI doesn't unexpectedly change over time.
Accessibility: Test that the component is accessible to users with disabilities.
Integration testing: Test that the component works correctly when integrated with other components.
Performance: Test that the component doesn't have any performance issues or memory leaks.
Error handling: Test that the component handles errors and edge cases gracefully.
API calls: Test that the component makes API calls correctly and handles the response appropriately.
Security: Test that the component doesn't introduce any security vulnerabilities.
Routing: Test that the component navigates correctly between routes in the application.
Authentication: Test that the component handles authentication and authorization correctly.
Edge cases: Test that the component handles edge cases, such as empty or null props, correctly.

What is React's Testing Library?

React's Testing Library is a testing framework designed to test React components in a way that closely mimics how users interact with the application. The Testing Library provides a set of utilities that allow developers to write tests that simulate user interactions with the components and check that the application behaves correctly.

The Testing Library is built on top of the Jest testing framework, which is a popular testing tool in the React community. Jest provides a test runner and an assertion library, while the Testing Library provides a set of utilities to help developers write tests.

The key philosophy behind the Testing Library is to test components as if you were a user interacting with the application. This approach makes it easier to write tests that closely resemble the user experience and ensure that the application is working as intended.

How to use React's Testing Library?

To use React's Testing Library, you need to install it as a dependency in your project. If you created your project using create-react-app or bit dev, this library comes pre-installed. To install manually, you can do this by running the following command in your terminal:

npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event @types/jest

Once you have installed the Testing Library and other dependencies, you can start writing tests. Let's take a look at an example of how to test a simple React component using the Testing Library.

Suppose we have a simple component called "Counter" that displays a counter value and allows the user to increment and decrement it. Here's what the component looks like:

import React, { useState } from 'react';

const Counter = () => {
  const [count, setCount] = useState(0);

  const handleIncrement = () => {
    setCount(count + 1);
  }

  const handleDecrement = () => {
    setCount(count - 1);
  }

  return (
    <div>
      <h1>{count}</h1>
      <button onClick={handleIncrement}>Increment</button>
      <button onClick={handleDecrement}>Decrement</button>
    </div>
  );
}

export default Counter;

To test this component using the Testing Library, we can write a test that checks that the counter value starts at 0, increments when the "Increment" button is clicked, and decrements when the "Decrement" button is clicked.

Here's what the test looks like:

import React from 'react';
import { render, fireEvent } from '@testing-library/react';
import Counter from './Counter';

test('counter increments and decrements correctly', () => {
  const { getByText } = render(<Counter />);

  // check that the counter starts at 0
  const counterValue = getByText('0');
  expect(counterValue).toBeInTheDocument();

  // click the increment button and check that the counter increments
  const incrementButton = getByText('Increment');
  fireEvent.click(incrementButton);
  expect(counterValue).toHaveTextContent('1');

  // click the decrement button and check that the counter decrements
  const decrementButton = getByText('Decrement');
  fireEvent.click(decrementButton);
  expect(counterValue).toHaveTextContent('0');
});

In this test, we first render the Counter component using the render function from the Testing Library. We then use the getByText function to find the "0" text node and check that it is in the document. We then simulate a click on the "Increment" button using the fireEvent.click function and check that the counter value is updated correctly using the toHaveTextContent assertion.

We then simulate a click on the "Decrement" button and check that the counter value is updated correctly using the same assertion.

This is a simple example, but it illustrates the power and simplicity of the Testing Library. With just a few lines of code, we can test that our component behaves correctly and that the user experience is what we expect.

Best practices for testing with React's Testing Library

To get the most out of React's Testing Library, there are some best practices that you should follow:

Test behavior, not implementation

When writing tests, focus on testing the behavior of your components, not their implementation details. This means that you should test what your component does, not how it does it. This approach makes your tests more resilient to changes in the implementation and ensures that they remain valid even if you refactor your code.

Test user interactions

Since the Testing Library is designed to test components as if you were a user interacting with the application, you should focus on testing user interactions. This means that you should simulate clicks, key presses, and other user actions to ensure that your components behave as expected.

Keep your tests small and focused

When writing tests, it's important to keep them small and focused. Each test should test a single piece of functionality or behavior. This approach makes it easier to debug failing tests and ensures that your tests remain maintainable over time.

Use descriptive test names

To make your tests more readable and understandable, use descriptive test names. Your test names should describe what the test does and what it's testing. This makes it easier to understand what your tests are doing and what they're testing.

Conclusion

React's Testing Library is a powerful tool that can help you create high-quality and maintainable code. By testing your components as if you were a user interacting with the application, you can ensure that your code behaves correctly and meets your users' expectations. In this article, we've explored how to use React's Testing Library and some best practices for writing tests. By following these best practices, you can write tests that are resilient, maintainable, and easy to understand.

Thank you for reading this article on testing React applications using React's Testing Library. We hope that you found it informative and helpful in your development process. If you're interested in learning more about software development, fintech, and other related topics, be sure to check out the ClickPesa publication. Our team is constantly writing and publishing articles that cover a range of topics related to software development, product design, and entrepreneurship.

Why should you learn ReactJs in 2023?

Benedict Steven — Wed, 12 Apr 2023 11:50:01 +0000

Why should you learn ReactJs in 2023?

React is a library for creating web and native user interfaces. With react you can build your application by creating small pieces / components and combine them into page / screen or app.

React is a powerful JavaScript library that allows developers to build complex user interfaces with ease.

If you're a front-end developer looking to keep up with the latest trends and stay relevant in the industry or a newbie aspiring to become a developer, learning React is a must. In this article, we'll take a closer look at why React is such an important skill for front-end developers in 2023, and why you should consider adding it to your skills.

Technical benefits.

High Performance: React's virtual DOM allows for efficient rendering of changes, resulting in fast and responsive user interfaces.

React's virtual DOM allows for efficient rendering of changes, making it ideal for building fast and responsive user interfaces. This can lead to better user experiences, which can be a key differentiator in today's competitive market.
Reusable Components: React's component-based architecture encourages code reusability and maintainability, making it easier to build and maintain large-scale applications. This can save developers time and effort, allowing them to focus on more important aspects of their projects.
Versatile: React's ability to be used in a variety of contexts, including web applications, mobile apps, and desktop applications, makes it a valuable skill to have in today's diverse and constantly evolving tech landscape. This can give developers more flexibility and opportunities to work on a wider range of projects.
Strong Ecosystem: React has a large and active community, with a plethora of libraries and tools available to help developers build and maintain their projects.
Compatibility: React is compatible with a wide range of platforms and frameworks, making it easier to integrate with existing codebases. This can save developers time and effort, as well as make it easier to work on projects that use different technologies.
Future-Proofing: React is constantly evolving and improving, ensuring that developers who invest in learning it will be equipped to tackle the challenges of web development for years to come. This can give developers confidence in their skills and help them stay relevant in a rapidly changing industry.

General benefits.

Increased job opportunities: React is a widely used technology, so learning it can open up many job opportunities for developers.
Higher earning potential: Due to the high demand for React developers, they often earn higher salaries compared to developers who work with other technologies.
Improved collaboration: React's component-based architecture makes it easier for developers to collaborate on projects. This can lead to more efficient teamwork, as well as better communication and coordination between team members. This can be especially important for large-scale projects or remote teams.
Faster development: React's virtual DOM and reusable components can help developers build applications faster, since they can reuse existing code and easily make changes without having to rebuild the entire application.
Better user experiences: React's performance and ability to render changes quickly can lead to better user experiences, which is increasingly important in today's market. Applications that provide a seamless user experience are more likely to be successful and gain traction with users.
Enhanced problem-solving skills: Learning React requires developers to think creatively and solve problems in new ways. This can improve their problem-solving skills and help them become better developers overall. These skills can be applied to other areas of development and can help developers stay competitive in the ever-evolving tech industry.
Access to a strong community: React has a large and active community, which can provide developers with support, resources, and opportunities for collaboration and networking. This community can be valuable for developers at all stages of their careers, from beginners who are just starting out to experienced professionals who want to stay up-to-date with the latest developments in React development.

Learning React in 2023 is a smart investment for developers looking to stay ahead of the curve in the tech industry. With its wide range of benefits, React is a versatile and powerful technology that can help developers achieve their goals. Moreover, the technical benefits of React make it an ideal choice for building high-quality applications across multiple platforms. By investing time and effort into learning React, developers can enhance their skills and advance their careers. So, if you're looking to take your career to the next level in 2023 and beyond, learning React is definitely worth considering.

If you like this article there are more like this in our blogs, follow us on dev.to/clickpesa, medium.com/clickpesa-engineering-blog and clickpesa.hashnode.dev

Happy Hacking!!

Setting up SSH Keys for Github, GitLab, and Bitbucket in one windows pc

Neema Adam — Tue, 07 Mar 2023 08:11:37 +0000

What are Github, Gitlab and Bitbucket?

Github, GitLab, and Bitbucket are all popular web-based Git repository hosting services that allow developers to collaborate on code and manage version control.

GitHub is the most well-known of the three and is used by millions of developers worldwide. It offers both free and paid plans and is a popular choice for open-source projects.

GitLab is another web-based Git repository hosting service that offers both free and paid plans. It is known for its built-in continuous integration and deployment features, making it a popular choice for DevOps teams.

Bitbucket is a Git repository hosting service that is owned by Atlassian, the company behind popular products like Jira and Confluence. It offers both free and paid plans and is known for its tight integration with other Atlassian products.

All three services offer similar functionality and are widely used by developers for managing code and collaborating on projects.

Connection method

There are several methods available to connect to Github, GitLab, or Bitbucket, including HTTPS and SSH. HTTPS is the default method and uses a username and password for authentication. SSH, on the other hand, uses a public and private key pair for authentication.

Using SSH has several advantages over HTTPS. First, it is more secure because it uses encryption to protect your credentials. Second, it is more convenient because you don’t need to enter your username and password every time you push or pull code. Finally, it allows for more fine-grained control over access to your repositories.

This guide shows you how to set up SSH keys for Github, GitLab, and Bitbucket on your Windows PC.

While SSH has several advantages over HTTPS, there are also some potential disadvantages to consider.

One is that setting up SSH requires more initial configuration than HTTPS. Additionally, if you lose your private key or it is compromised, it can be difficult to recover access to your repositories. Finally, some corporate firewalls may block SSH traffic, which could prevent you from using it to connect to remote repositories.

Setting up SSH Keys for Github, GitLab, and Bitbucket in One Windows PC

SSH keys are a secure way to authenticate with remote Git repositories like Github, GitLab, and Bitbucket. In this guide, we will show you how to set up SSH keys for all three services on your Windows PC.

Step 1: Check for existing SSH keys

Before generating new SSH keys, we need to check whether any SSH keys already exist on our machine. Open the Git Bash terminal by right-clicking on your desktop and selecting “Git Bash Here”. Then, enter the following command in the terminal:

ls -al ~/.ssh

If any files with names like id_rsa or id_rsa.pub exist in the output, you already have an SSH key pair. If not, we will generate a new key pair in the next step.

Step 2: Generate a new SSH key pair
In the Git Bash terminal, enter the following command to generate a new SSH key pair:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

This command will prompt you for a file name and passphrase.

Step 3: Add the SSH key to Github, GitLab, and Bitbucket

Next, we need to add the SSH key to our Github, GitLab, and Bitbucket accounts.

Github

Log in to your Github account and go to “Settings”.
Click on “SSH and GPG keys”.
Click on “New SSH key”.
Give your key a title and paste the contents of your id_rsa.pub file into the “Key” field.
Click “Add SSH key”.

GitLab

Log in to your GitLab account and go to “Settings”.
Click on “SSH Keys”.
Give your key a title and paste the contents of your id_rsa.pub file into the “Key” field.
Click “Add key”.

Bitbucket

Log in to your Bitbucket account and go to “Settings”.
Click on “SSH keys”.
Click on “Add key”.
Give your key a label and paste the contents of your id_rsa.pub file into the “Key” field.
Click “Add key”.

Step 4: Test the SSH connection

To test the SSH connection, enter the following command in the Git Bash terminal:

ssh -T git@github.com

Replace “github.com” with “gitlab.com” or “bitbucket.org” to test the connection to those services.

If the SSH connection is successful, you should see a message like “Hi username! You’ve successfully authenticated, but GitHub does not provide shell access.”

Congratulations! You have now set up SSH keys for Github, GitLab, and Bitbucket on your Windows PC.

Why should you use react query for your react app - part 2

Benedict Steven — Fri, 03 Mar 2023 08:33:42 +0000

...For the introduction to react-query and useQuery hooks, Read my previous post Part one

In my previous post we explored the introduction to react query and useQuery hook.

In this post we explore useMutation hook in data creation, edition and deletion.

We will use Free API for creating user, editing user info, viewing and deleting user. In order to use the free api above, you will need to login to get your access token for authorization.

Lets create a form that to create user info.
The required user info are name, gender, email and status.

const App = () => {
  const handleSubmit = (e) => {
    e.preventDefault();
    // submit user data
    const dataToSubmit = {
      name: e.target[0].value,
      email: e.target[1].value,
      gender: e.target[2].value,
      status: e.target[3].value,
    };
  };

  return (
    <div className="App">
      <form onSubmit={handleSubmit}>
        <label>
          Name:
          <input type="text" name="name" required placeholder="Name" />
        </label>
        <br />
        <label>
          Email:
          <input type="email" name="email" required placeholder="Email" />
        </label>
        <br />
        <label>
          Gender:
          <select
            name="gender"
            defaultValue=""
            required
            placeholder="Select gender"
          >
            <option disabled value="">
              -- select an option --
            </option>
            <option value="male">Male</option>
            <option value="female">Female</option>
          </select>
        </label>
        <br />
        <label>
          Status:
          <select
            name="status"
            defaultValue=""
            required
            placeholder="Select status"
          >
            <option disabled value="">
              -- select an option --
            </option>
            <option value="active">Active</option>
            <option value="inactive">Inactive</option>
          </select>
        </label>
        <br />
        <button>Create user</button>
      </form>
    </div>
  );
};

export default App;

Now that we can collect info, lets create our first user,
import useMutation from react-query

useMutation provides data and methods/callbacks to run and get data.

import { useMutation } from "react-query"

const App = () => {
 const {
   // responses and functions to call mutation
   data,
   error,
   isError,
   isIdle,
   isLoading,
   isPaused,
   isSuccess,
   mutate,
   mutateAsync,
   reset,
   status,
 } = useMutation(
   // the function to call an api (accepts variables)
   mutationFn, 
   // options and methods/callbacks
   {
     mutationKey,
     onError,
     onMutate,
     onSettled,
     onSuccess,
     retry,
     retryDelay,
     useErrorBoundary,
     meta,
   }
)

// this will run synchronous
 mutate(variables, {
   onError,
   onSettled,
   onSuccess,
 })

// this will return a promise
mutateAsync(variables, {
   onError,
   onSettled,
   onSuccess,
 })
}

Learn More

From the sample above, lets create our first user.

import axios from "axios";
import { useMutation } from "react-query";

const App = () => {
  const { data, error, isLoading, mutate } = useMutation(
    async (dataToSubmit) => {
      // call axios request
      const { data } = await axios.post(
        "https://gorest.co.in/public/v2/users?access-token=89945d7d4cea090a8135a824fa3100f5a057ee2c4bdf9c3b8ab01f7a20b16784",
        dataToSubmit,
        {
          headers: {
            "Content-Type": "application/json",
          },
        }
      );
      return data;
    }
  );

  const handleSubmit = (e) => {
    e.preventDefault();
    // submit user data
    const dataToSubmit = {
      name: e.target[0].value,
      email: e.target[1].value,
      gender: e.target[2].value,
      status: e.target[3].value,
    };
    mutate(dataToSubmit);
  };

  console.log(data, error);

  return (
    <div className="App">
      <form onSubmit={handleSubmit}>
        <label>
          Name:
          <input
            type="text"
            name="name"
            required
            disabled={isLoading}
            placeholder="Name"
          />
        </label>
        <br />
        <label>
          Email:
          <input
            type="email"
            name="email"
            required
            disabled={isLoading}
            placeholder="Email"
          />
        </label>
        <br />
        <label>
          Gender:
          <select
            name="gender"
            defaultValue=""
            required
            disabled={isLoading}
            placeholder="Select gender"
          >
            <option disabled value="">
              -- select an option --
            </option>
            <option value="male">Male</option>
            <option value="female">Female</option>
          </select>
        </label>
        <br />
        <label>
          Status:
          <select
            name="status"
            defaultValue=""
            required
            disabled={isLoading}
            placeholder="Select status"
          >
            <option disabled value="">
              -- select an option --
            </option>
            <option value="active">Active</option>
            <option value="inactive">Inactive</option>
          </select>
        </label>
        <br />
        <button disabled={isLoading}>
          {isLoading ? "Creating user" : "Create user"}
        </button>
      </form>
    </div>
  );
};

export default App;

Run the code above to create your first user. Congratulations on creating your first user 🎉.

Lets create a formal way to represent the flow, from creating a new user to viewing all users to viewing single user to editing single user and finally deleting single user. We will have mainly three screens,
First the screen for viewing all users - it will include a button to create new user and a list of all users.
Second is a screen we just created, for creating a single user ( we can make it available for editing user as well. )
Third is a screen for viewing single user with buttons to edit and delete user.

First install react-router-dom for easy routing. run

npm install react-router-dom

Then wrap your application in Browser router.
in main.jsx or index.jsx
with vite it will look like this

import React from "react";
import ReactDOM from "react-dom/client";
import { QueryClient, QueryClientProvider } from "react-query";
import { BrowserRouter as Router } from "react-router-dom";
import App from "./App";

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <Router>
        <App />
      </Router>
    </QueryClientProvider>
  </React.StrictMode>
);

Lets create our pages

users.jsx page

import axios from "axios";
import React from "react";
import { useQuery } from "react-query";
import { Link } from "react-router-dom";

const Users = () => {
  const { data, isLoading, error, refetch } = useQuery({
    queryKey: ["FETCH_USERS"],
    queryFn: async () => {
      const { data } = await axios.get("https://gorest.co.in/public/v2/users", {
        headers: {
          Authorization:
            "Bearer 89945d7d4cea090a8135a824fa3100f5a057ee2c4bdf9c3b8ab01f7a20b16784",
        },
      });
      return data;
    },
  });

  if (isLoading) {
    return <p>Please Wait...</p>;
  }
  if (error) {
    return (
      <div>
        <p>{error?.message}</p>
        <button onClick={() => refetch()}>Retry</button>
      </div>
    );
  }

  return (
    <div>
      <div
        style={{
          marginBottom: "1rem",
        }}
      >
        <Link to={"/mutate-user"}>Create New User</Link>
      </div>
      <ul>
        {data?.map((user) => (
          <li key={user?.id}>
            <Link to={`/user/${user?.id}`}>{user?.name}</Link>
          </li>
        ))}
      </ul>
    </div>
  );
};

export default Users;

user.jsx

import axios from "axios";
import React from "react";
import { useMutation, useQuery } from "react-query";
import { Link, useNavigate, useParams } from "react-router-dom";

const User = () => {
  // navigation hook
  const navigate = useNavigate();

  // get url params
  const params = useParams();
  const id = params?.id;

  const { data, isLoading, error, refetch } = useQuery({
    queryKey: ["FETCH_USER", id],
    queryFn: async () => {
      const { data } = await axios.get(
        `https://gorest.co.in/public/v2/users/${id}`,
        {
          headers: {
            Authorization:
              "Bearer 89945d7d4cea090a8135a824fa3100f5a057ee2c4bdf9c3b8ab01f7a20b16784",
          },
        }
      );
      return data;
    },
  });

  //   delete mutation
  const {
    error: mutateError,
    isLoading: mutateLoading,
    mutateAsync,
  } = useMutation(async () => {
    // call axios request
    const { data } = await axios.delete(
      `https://gorest.co.in/public/v2/users/${id}?access-token=89945d7d4cea090a8135a824fa3100f5a057ee2c4bdf9c3b8ab01f7a20b16784`,
      {
        headers: {
          "Content-Type": "application/json",
        },
      }
    );
    return data;
  });

  if (isLoading) {
    return <p>Please Wait...</p>;
  }
  if (error) {
    return (
      <div>
        <p>{error?.message}</p>
        <button onClick={() => refetch()}>Retry</button>
      </div>
    );
  }

  return (
    <div>
      <div
        style={{
          display: "flex",
          gap: "1rem",
          marginBottom: "1rem",
        }}
      >
        <Link to={`/mutate-user?id=${id}`}>Edit User</Link>
        <button
          onClick={async () => {
            await mutateAsync();
            // if success delete redirect to all users page
            navigate("/");
          }}
        >
          {mutateLoading ? "Deleting user" : "Delete User"}
        </button>
      </div>
      {mutateError && (
        <p
          style={{
            color: "red",
          }}
        >
          {mutateError?.message}
        </p>
      )}
      <div>
        <p>Name: {data?.name}</p>
        <p>Email: {data?.email}</p>
        <p>Gender: {data?.gender}</p>
        <p>Status: {data?.status}</p>
      </div>
    </div>
  );
};

export default User;

mutate-user.jsx

import axios from "axios";
import { useEffect } from "react";
import { useMutation, useQuery } from "react-query";
import { useNavigate, useSearchParams } from "react-router-dom";

const MutateUser = () => {
  // navigate hook
  const navigate = useNavigate();
  // find ID if present
  const [searchParams] = useSearchParams();
  const id = searchParams.get("id");

  //   get user if there is an ID
  const {
    data: userData,
    isLoading: userLoading,
    error: userError,
    refetch,
  } = useQuery({
    queryKey: ["FETCH_USER", id],
    queryFn: async () => {
      const { data } = await axios.get(
        `https://gorest.co.in/public/v2/users/${id}?access-token=89945d7d4cea090a8135a824fa3100f5a057ee2c4bdf9c3b8ab01f7a20b16784`,
        {
          headers: {
            Authorization:
              "Bearer 89945d7d4cea090a8135a824fa3100f5a057ee2c4bdf9c3b8ab01f7a20b16784",
          },
        }
      );
      return data;
    },
    enabled: !!id,
  });

  const { data, error, isLoading, mutateAsync } = useMutation(
    async (dataToSubmit) => {
      // call axios request
      // call post if its user creation and put if its user editing
      const { data } = await axios[id ? "put" : "post"](
        `https://gorest.co.in/public/v2/users${
          // pass id if editing user
          id ? "/" + id : ""
        }?access-token=89945d7d4cea090a8135a824fa3100f5a057ee2c4bdf9c3b8ab01f7a20b16784`,
        dataToSubmit,
        {
          headers: {
            "Content-Type": "application/json",
          },
        }
      );
      return data;
    }
  );

  // navigate to user page when request was successfully
  useEffect(() => {
    if (data) {
      // redirect to user page
      navigate(`/user/${data?.id}`);
    }
  }, [data]);

  if (userLoading) {
    return <p>Please Wait...</p>;
  }

  if (userError) {
    return (
      <div>
        <p>{userError?.message}</p>
        <button onClick={() => refetch()}>Retry</button>
      </div>
    );
  }

  const handleSubmit = async (e) => {
    e.preventDefault();
    // submit user data
    const dataToSubmit = {
      name: e.target[0].value,
      email: e.target[1].value,
      gender: e.target[2].value,
      status: e.target[3].value,
    };
    await mutateAsync(dataToSubmit);
  };

  return (
    <div className="App">
      <form onSubmit={handleSubmit}>
        <label>
          Name:
          <input
            type="text"
            name="name"
            // prefill data if exists
            defaultValue={userData?.name ?? ""}
            required
            disabled={isLoading}
            placeholder="Name"
          />
        </label>
        <br />
        <label>
          Email:
          <input
            type="email"
            name="email"
            // prefill data if exists
            defaultValue={userData?.email ?? ""}
            required
            disabled={isLoading}
            placeholder="Email"
          />
        </label>
        <br />
        <label>
          Gender:
          <select
            name="gender"
            // prefill data if exists
            defaultValue={userData?.gender ?? ""}
            required
            disabled={isLoading}
            placeholder="Select gender"
          >
            <option disabled value="">
              -- select an option --
            </option>
            <option value="male">Male</option>
            <option value="female">Female</option>
          </select>
        </label>
        <br />
        <label>
          Status:
          <select
            name="status"
            // prefill data if exists
            defaultValue={userData?.status ?? ""}
            required
            disabled={isLoading}
            placeholder="Select status"
          >
            <option disabled value="">
              -- select an option --
            </option>
            <option value="active">Active</option>
            <option value="inactive">Inactive</option>
          </select>
        </label>
        <br />
        {error && (
          <p
            style={{
              color: "red",
            }}
          >
            {error?.message}
          </p>
        )}
        <br />
        <button disabled={isLoading}>
          {!id && <>{isLoading ? "Creating user..." : "Create user"}</>}
          {id && <>{isLoading ? "Editing user..." : "Edit user"}</>}
        </button>
      </form>
    </div>
  );
};

export default MutateUser;

Then lets setup our routing system

in the App.jsx

import React from "react";
import { Route, Routes } from "react-router-dom";
import MutateUser from "./pages/mutate-user";
import User from "./pages/user";
import Users from "./pages/users";

const App = () => {
  return (
    <div>
      <Routes>
        <Route element={<Users />} path="/" />
        <Route element={<User />} path="/user/:id" />
        <Route element={<MutateUser />} path="/mutate-user" />
      </Routes>
    </div>
  );
};

export default App;

Congratulations 🎉, we have created CRUD application with react-query Without managing any state ourselves Phew.

If you missed the introduction part and useQuery part, read my previous post

If you like this article there are more like this in our blogs, follow us on dev.to/clickpesa, medium.com/clickpesa-engineering-blog and clickpesa.hashnode.dev

Happy Hacking!!

Creating a design system from scratch

Neema Adam — Sun, 19 Feb 2023 23:04:57 +0000

This is the third and final part in my series about my notes on the design system, you can find the introduction part here and the second part here. In the first part, I talked about design systems, and in the second part, I talked about customizing a prebuilt design system. In this article, I’ll go over some things that I and my team at ClickPesa did to successfully ship our custom design system.

1. The Scope

The first thing to do when creating a design system is to determine the primary usage of your system. You might want your design system to be a general system that designers and teams building different products can use or you might want it to be something specific to only your projects or narrow it down even more to a single project. The wider the target usage of your system, the broader the scope.

The scope of your system will determine how many colors and text styles you will have to set up and how many components and their variants you will have to create. Let’s say you want to create a design system like Untitled UI that designers and teams can buy and use in their own projects, in this case, you will have to consider the needs of a lot of designers and create a general solution that will be a time server and yet customizable enough to fit into their products. You might end up creating and maintaining hundreds of components with their variants.

Another case is if you want to create a design system for your products or for a single product. In this case, you will only have to set up colors and text styles that are needed and create only the components that your products use. At ClickPesa, we decided to ship a design system that can be used to design all of our products. We decided that our products will share components and only use different primary colors and font families so I only created components that we need for our products with a few variants. This makes it easy to use and maintain the design system.

2. Creating the system

Intro

The team and I dedicated two days and went over our products to determine what components do we need to design, then we prepared a list in google sheets with six columns; name, type, description, states, variants, and URL to component. This document serves as documentation, a rule book, and also a design system checklist. We chose to use google sheet so that every member of the team can have access to it and take a look whenever they want to.

Design Tokens

I started by preparing the design tokens. I only prepared colors, text styles, drop shadows, and border-radius. So far those are the only things we needed in our products.

Icons

After setting up all the tokens, I prepared the icons. I used Phosphor icons and migrated outlined and filled icons to my design system.

I also added common keywords that I’d use to search certain icons in their description so it’s easy to find them.

Components

For ClickPesa we decided on 33 components that are going to be used in all our products including GetPaid. We have essential components such as input, textarea, buttons, and other product-specific components such as the balance card component that we use to display account balances.

If you are interested to learn about my process of creating complex components in Figma, I wrote an article about it here.

3. Documentation

Apart from having a google sheet with a description of what each component is and where to use it, I also prepared documentation in Figma that goes into specifics on how to use the component.

Conclusion

If your product is huge, creating a design system from scratch can seem daunting, but it's an important investment for any company that wants to create consistent, efficient, and memorable products. Just start small and evolve it according to usage needs.

Why should you use react query for your react app

Benedict Steven — Sat, 18 Feb 2023 20:47:10 +0000

React query provides hooks for managing server data in react application.

Imagine you are creating an application that receives data from an API and displays that data. How will you handle that data? State management yes!

With normal flow you will have to write logic to fetch data, write reducers, caching logic, retry (it could be more… depending on the application).

You will be surprised with the number of codes you will need using react query.

Among-st many things, react-query offers server data management, caching, re-fetching, mutation. Learn more.

To get a glimpse of react query lets create a simple blog application using react query and react.

Install react-query and axios in your react app.

npm install react-query axios

Then wrap your entire provider in react query provider

in index.jsx

import React from "react";
import ReactDOM from "react-dom/client";
import { QueryClient, QueryClientProvider } from "react-query";
import App from "./App";

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </React.StrictMode>
);

Lets do the fetching first

in App.jsx
import useQuery from react-query

import { useQuery } from "react-query";

Create a first api request to fetch sample blog posts.

import { useQuery } from "react-query";

const App = () => {
  const { data, isLoading, error } = useQuery({
    queryKey: ["FETCH_POSTS"],
    queryFn: async () => {
      const { data } = await axios.get(
        "https://jsonplaceholder.typicode.com/posts"
      );
      return data;
    },
  });
  console.log(data);
  return <div className="App">Hello world</div>;
};

export const App

NB: useQuery is a hook and can only be called inside the react function component

from the simple example above, data will hold any data success response from the api call, error will hold error data, isLoading will hold the loading status (true/ false). The returned data will be cached after initial success request, whenever you call the same api via use query in another component, the data will persist that you won't need to store them in any state.

QueryKey keeps track of the memory required to handle data caching, When useQuery is used, it checks the cache first using query key and if none is found, then it makes actual API request, if cache is present, it returns the existing data. Its can be array of a simple string to array of complex data depending on application complexity.

Lets display the fetched data and allow user to view single post.

const App = () => {
  return (
    <div className="App">
      {/* display data */}
      <Posts />
    </div>
  );
};

// all posts
const Posts = () => {
  const { data, isLoading, error, status } = useQuery({
    queryKey: ["FETCH_POSTS"],
    queryFn: async () => {
      const { data } = await axios.get(
        "https://jsonplaceholder.typicode.com/posts"
      );
      return data;
    },
  });
  return (
    <div>
      {isLoading && <div>Please wait...</div>}
      {data &&
        data.map((post) => (
          <PostCard
            key={post.id}
            post={post}
          />
        ))}
    </div>
  );
};

// Post Card
const PostCard = ({ post }) => {
  return (
    <a href="#">
      <p>{post.title}</p>
    </a>
  );
};

This will display all the data from the, lets set a way to view single post in the same screen. React router can be used but for this case we can use state to render all posts and single post on post clicking.

const App = () => {
  const [selectedPost, setSelectedPost] = useState(-1);
  return (
    <div className="App">
      {/* display data */}
      {selectedPost === -1 && <Posts selectPost={(id) => setSelectedPost(id)} />}
      {/* add a back button on viewing single post */}
      {selectedPost && (
        <a href="#" onClick={() => setSelectedPost(-1)}>
          Back
        </a>
      )}
      {/* viewing single post details */}
      {selectedPost > -1 && <Post id={selectedPost} />}
    </div>
  );
};

// all posts
const Posts = ({selectPost) => {
  const { data, isLoading, error, status } = useQuery({
    queryKey: ["FETCH_POSTS"],
    queryFn: async () => {
      const { data } = await axios.get(
        "https://jsonplaceholder.typicode.com/posts"
      );
      return data;
    },
  });
  return (
    <div>
      {isLoading && <div>Please wait...</div>}
      {data &&
        data.map((post) => (
          <PostCard
            key={post.id}
            post={post}
            onClick={() => selectPost(post.id)}
          />
        ))}
    </div>
  );
};


// Post Card
const PostCard = ({ post, onClick }) => {
  return (
    <a href="#" onClick={onClick}>
      <p>{post.title}</p>
    </a>
  );
};

const Post = ({ id }) => {
  return <div>Hello post</div>;
};

Now we should be able to click and view a single post and go back to viewing all posts.

Lets fetch data on a <Post /> component.

const Post = ({ id }) => {
  const { data, isLoading, error, status } = useQuery({
    queryKey: ["FETCH_POST", id],
    queryFn: async () => {
      const { data } = await axios.get(
        `https://jsonplaceholder.typicode.com/posts/${id}`
      );
      return data;
    },
  });

  return (
    <div>
      {isLoading && <div>Fetching post...</div>}
      {data && (
        <div>
          <h3>{data.title}</h3>
          <p>{data.body}</p>
        </div>
      )}
    </div>
  );
};

Note that in query key, We added id, id is unique for each post and helps to keep memory in the cache for that particular post we just viewed, clicking the same post again won't make an API call, instead will return the cached data.

For a case where we don't need cache, and every time user visits the component or page, we want to make an actual request, we can prevent cache by adding an cacheTime as an option in useQuery params.

const Post = ({ id }) => {
  const { data, isLoading, error, status } = useQuery({
    queryKey: ["FETCH_POST", id],
    queryFn: async () => {
      const { data } = await axios.get(
        `https://jsonplaceholder.typicode.com/posts/${id}`
      );
      return data;
    },
    cacheTime: 0,
  });

  return (
    <div>
      {isLoading && <div>Fetching post...</div>}
      {data && (
        <div>
          <h3>{data.title}</h3>
          <p>{data.body}</p>
        </div>
      )}
    </div>
  );
};

This will run every time a post is visited, even the one which was already visited before.

Another cool thing we can do is adding refetch button. Assume you visit a page which returns an error that data fetching failed, you have no choice but to refresh the page. Well you can add a refetch button and use refetch provided by react query out of the box, lets see how we can utilize that

const Post = ({ id }) => {
  const { data, isLoading, error, status, isRefetching, refetch } = useQuery({
    queryKey: ["FETCH_POST", id],
    queryFn: async () => {
      const { data } = await axios.get(
        `https://jsonplaceholder.typicode.com/posts/${id}`
      );
      return data;
    },
    cacheTime: 0,
  });

  return (
    <div>
      {(isLoading || isRefetching) && <div>Fetching post...</div>}
      {data && (
        <div>
          <h3>{data.title}</h3>
          <p>{data.body}</p>
        </div>
      )}
      {error && <p>{error.message}</p>}
      {error && <button onClick={refetch}>Refetch</button>}
    </div>
  );
};

We can also enable or disable data fetching using enable option. When the query is disabled no fetching will be done until it is enabled, this feature can be used when implementing lazy query (queries that are triggered by user action.
Lets see an example of this. In the post component, lets say we want user to trigger initial fetching by clicking something.

const Post = ({ id }) => {
  const [enabled, setEnabled] = useState(false);
  const { data, isLoading, error, status, isRefetching, refetch } = useQuery({
    queryKey: ["FETCH_POST", id],
    queryFn: async () => {
      const { data } = await axios.get(
        `https://jsonplaceholder.typicode.com/posts/${id}`
      );
      return data;
    },
    cacheTime: 0,
    enabled,
  });

  return (
    <div>
      {!data && !error && (
        <button onClick={() => setEnabled(true)}>Fetch Post</button>
      )}
      {(isLoading || isRefetching) && <div>Fetching post...</div>}
      {data && (
        <div>
          <h3>{data.title}</h3>
          <p>{data.body}</p>
        </div>
      )}
      {error && <p>{error.message}</p>}
      {error && <button onClick={refetch}>Refetch</button>}
    </div>
  );
};

Now every time user clicks to view a single post, they will have to click Fetch button to load post details. This is useful especially on search screen where you only allow fetching when user search something.

There are more options on useQuery hook that might help in your project such as refetchOnWindowFocus, refetchOnMount (By default these two are true).

Other options include refetchInterval specifies at with interval you want to be pooling your data (in milliseconds).
React-query works best with pagination as well as fetching and re-fetching data on background.

React query provides useMutation hook that provides data creation, edition and deletion. In my next post we'll cover how to mutate data with useMutation hook.

If you are using GraphQL API, the best alternative to react-query is Apollo Client although react-query can also be used with GraphQL.

If you like this article there are more like this in our blogs, follow us on dev.to/clickpesa, medium.com/clickpesa-engineering-blog and clickpesa.hashnode.dev

Happy Hacking!!

Customizing a prebuilt design system in Figma

Neema Adam — Thu, 22 Dec 2022 16:36:33 +0000

This post is part of a series about everything I have learned about design systems and I’ll write it from a designer’s point of view. This is the second part, you can find the introduction part here

Customizing design tokens

After getting a new design system, you might need to customize all the design tokens to match your product’s. Check if your design system takes full advantage of the Figma Tokens plugin, which will allow you to change the style of the entire design system in a few minutes. For this post, I’ll be working with this open-source design system file I found in the Figma community. This one doesn’t support Figma tokens so this post won’t cover it.

This file ships with design tokens and a few essential components. You can take a look around by navigating the pages found in your left panel.

Fonts

Once duplicated the file, on the right side, you will see all the local styles available. We want to edit the text styles.

Hover over one of the styles, eg. H1 and you will see a controls icon button, click it and a window for editing will appear.

There you can change the name of the text style, you can add a description to help designers in your team understand what this text style is used for, and can change the font family and other text properties. For this example, I will change the font family from Poppins to Chivo, and I’ll repeat the same steps for all text styles so the font family used across the design system is Chivo.

When changing the font family you might find that some font-weight styles from the current font are not found in the font you are trying to use, so instead, you can use a font-weight close to that one. In this case, Chivo doesn’t have a medium font weight so I used bold, in fact for H1 through H5 my font-weight is set to bold.

After changing the font family and weight in all text styles, this how the typography preview look.

Colors

Our example design system ships with five types of colors, the default black and white, neutrals, primaries, critical, and success. I want to add more colors and edit the current color values and their names.

Adding new colors

On the left panel, there is a category for color styles, I am going to hover over the title ‘Color Styles’ and use the plus button to add more colors.

The new colors I am going to add are yellow color for warning and blue color for progress. I like using the colors created by TailwindCSS, so I’ll visit the link attached and copy the yellow and sky colors from values 500 - 300. I want to only have three colors for each group except neutrals, so my scale will be from 100 to 300.

Editing existing colors

For editing existing color styles, I want to delete all the criticals, success, and primary colors from values 70 - 5, and then rename them and change their values. After deleting the values I don’t need and renaming them, here is what I have:

For my primary colors, I am going to use Tailwind Fuchsia, values 500 - 300. For errors, I’ll use Tailwind Red from 500 - 300. And for Success, I’ll also use Tailwind Green, values 500 - 300’. This is what my color styles look like:

I also renamed the neutrals:

I also edited the colors documentation and now it looks like this:

Components

The example design system ships with a couple of essential components. You might need to add your own components or edit the existing ones.

Editing existing components

Let’s start by fixing the button component. When I edited the color styles, by deleting some values I broke the styling of the buttons, they are now not using the color styles defined.

I’ll fix this by selecting the frame containing all buttons and going to the selection colors section in the right panel where I’ll click and change the values to use my color styles.

After editing here is what I have

To edit the contents of a component, you can edit the master component at the top of the variants. Example here is the master component of the input component:

You can choose to edit this by adding an icon before the hint text or adding an icon after the label text and your changes will be reflected across all variants. And you can even make new variants that use or don’t use your new elements.

Adding new components

To add new components, create a new page, give it a name related to your component and start creating.
Publishing Changes

With the free plan, you can only publish your styles, like text, color, or effects. With a team or professional plan, you can publish your components. Whenever you publish new changes, files that use your design system will get a notification that there are some new changes needed to be reviewed and applied.

Here is the version I have been working on in this article, you can duplicate the file and explore it.