DEV Community: Milu

Create a Next.js AI Chatbot App with Vercel AI SDK

Milu — Fri, 12 Jul 2024 02:13:00 +0000

The recent advancements in Artificial Intelligence have propelled me (and probably many in the Software Engineering community) to delve deeper into this field. Initially I wasn't sure where to start, so I enrolled in the Supervised Machine Learning Coursera class to learn the basics. While the course is fantastic, my hands-on approach led me to implement a quick application to dip my toe and grasp the practical fundamentals. This is how I discovered the Vercel AI SDK, paired with the OpenAI provider. Using one of their existing templates, I developed my version of an AI chatbot. This exercise introduced me to the variety of available providers and the possibilities of integrating these providers to offer capabilities to users. In this article, I’ll define the Vercel AI SDK, detail how to use it, and share my thoughts on this experience.

What is Vercel AI SDK?

The Vercel AI SDK is a TypeScript toolkit designed to implement Large Language Models (LLMs) capabilities in frameworks such as React, Next.js, Vue, Svelte, Node.js, and others.

Why Use Vercel AI SDK?

There are several LLM providers available for building AI-powered apps, including:

OpenAI
Azure
Anthropic
Amazon Bedrock
Google Generative AI
Databricks
Cohere
...

However, integrating with each provider can vary and is not always straightforward, as some offer SDKs or APIs. With the Vercel AI SDK, you can integrate multiple LLM providers using the same API, UI hooks, and stream generative user interfaces.

How to Use Vercel AI SDK in a Next.js App?

Vercel offers an AI SDK RSC package that supports React Server Components, enabling you to write UI components that render on the server and stream to the client. This package uses server actions to achieve this. Let's explain some of the functions used:

useUIState: Acts like React’s useState hook but allows you to access and update the visual representation of the AI state.

const [messages, setMessages] = useUIState<typeof AI>()

useAIState: Provides access to the AI state, which contains context and relevant data shared with the AI model, and allows you to update it.

const [aiState, setAiState] = useAIState()

getMutableAIState: Provides a mutable copy of the AI state for server-side updates.

const aiState = getMutableAIState<typeof AI>()

useActions: Provides access to the server actions from the client.

const { submitUserMessage } = useActions()

streamUI: Calls a model and returns with a React Server component.

  const result = await streamUI({
    model: openai('gpt-3.5-turbo'),
    initial: <SpinnerMessage />,
    messages: [...],
    text: ({ content, done, delta }) => {
      ...
      return textNode
    }
  })

Detailed Tutorial

You can fork the simplified project I’ve worked on or use the official Vercel template. Both repositories have installation information in the README.

Let's dive into the key parts that make this integration work.

components/prompt-form.tsx
In this component, we use the useUIState hook to update the visual representation of the AI state. We also use the useActions function to access the submitUserMessage function that we will create next.

export function PromptForm({
  input,
  setInput
}: {
  input: string
  setInput: (value: string) => void
}) {
  const { submitUserMessage } = useActions()
  const [_, setMessages] = useUIState<typeof AI>()

  return (
    <form
      onSubmit={async (e: any) => {
        e.preventDefault()

        const value = input.trim()
        setInput('')
        if (!value) return

        // Optimistically add user message UI
        setMessages(currentMessages => [
          ...currentMessages,
          {
            id: nanoid(),
            display: <UserMessage>{value}</UserMessage>
          }
        ])

        // Submit and get response message
        const responseMessage = await submitUserMessage(value)
        setMessages(currentMessages => [...currentMessages, responseMessage])
      }}
    >
     <div>...</div>
    </form>

lib/chat/actions.tsx
Now, let's explore the submitUserMessage function. First, we use getMutableAIState to define a variable called aiState and update it with the user-submitted message.

async function submitUserMessage(content: string) {
  'use server'

  const aiState = getMutableAIState<typeof AI>()

  aiState.update({
    ...aiState.get(),
    messages: [
      ...aiState.get().messages,
      {
        id: nanoid(),
        role: 'user',
        content
      }
    ]
  })
  ...
}

Next, we use the streamUI function to define the LLM model we want to use (in this case, gpt-3.5-turbo), set an initial loading state while waiting for the response, and provide an array containing all the messages and their context.

Since we are using a streaming function, we can display the LLM results as they are received, even if they are incomplete. This enhances the user experience by showing results on the screen quickly, rather than waiting for a complete response.

async function submitUserMessage(content: string) {
  ...
  let textStream: undefined | ReturnType<typeof createStreamableValue<string>>
  let textNode: undefined | React.ReactNode

  const result = await streamUI({
    model: openai('gpt-3.5-turbo'),
    initial: <SpinnerMessage />,
    messages: [
      ...aiState.get().messages.map((message: any) => ({
        role: message.role,
        content: message.content,
        name: message.name
      }))
    ],
    text: ({ content, done, delta }) => {
      if (!textStream) {
        textStream = createStreamableValue('')
        textNode = <BotMessage content={textStream.value} />
      }

      if (done) {
        textStream.done()
        aiState.done({
          ...aiState.get(),
          messages: [
            ...aiState.get().messages,
            {
              id: nanoid(),
              role: 'assistant',
              content
            }
          ]
        })
      } else {
        textStream.update(delta)
      }

      return textNode
    }
  })
}

The streamUI function also has a tools attribute that could extend your chatbot's capabilities by defining custom tools that can be invoked during the conversation, enhancing the user experience with dynamic and context-aware responses.

async function submitUserMessage(content: string) {
  ...
  const result = await streamUI({
    ...
    tools: {
      weather: async (location: string) => {
        const response = await fetch(`/api/weather/location=${location}`)
        const data = await response.json()
        return `The current weather in ${location} is ${data.weather} with a temperature of ${data.temperature}°C.`
      }
    }
    ...
  })
}

The tools attribute is added to streamUI to define custom tools.
In this example, a weather tool is defined that takes a location as an argument. The weather tool makes an API call to /api/weather to fetch weather information for the given location. The API response is parsed, and a formatted weather message is returned.

And there you have it! You can get an AI chatbot working pretty quickly with these functions.

Thoughts on Vercel AI SDK

The Vercel AI SDK was intuitive and easy to use, especially if you already have experience with Next.js or React. While you could implement the OpenAI SDK directly, the Vercel AI SDK’s ability to integrate multiple LLM models without additional boilerplate makes it a good choice.

Terraform 101: The What, the Why, and the How

Milu — Thu, 05 Jan 2023 18:26:23 +0000

It's been nearly two years since I first encountered Terraform. In my first week working with Terraform, I got myself into a bad local state that led to countless error messages, many trials and errors, and the exposure to numerous Stack Overflow threads. Ultimately I manually deleted all my AWS resources. To say the least, my introduction to Terraform was a total nightmare. After that, I didn’t want to touch Terraform again. Little did I know I would learn to appreciate and even enjoy working with this powerful tool.

On my journey, I struggled to find tutorials that use Terraform to set up AWS resources, so I decided to share the knowledge I acquired with the hopes you (dear reader) will be able to skip some of the troubles I encountered. This post is going to define Terraform, list the reasons why you might want to learn it and use it, and go through the set up process step by step.

The What

Terraform is an infrastructure as code tool (IAC) created by HashiCorp that lets you automate cloud and on-prem resources. It uses configuration files written in HashiCorp Configuration Language (HCL) to declare resources (infrastructure objects) and define dependencies between them. To put it simply, this tool allows you to write a few configuration files and build a whole system’s architecture on the cloud by running a couple of commands. I found this to be a more efficient alternative to clicking through a console to create resources manually.

Terraform State

Terraform keeps track of the infrastructure it created in a state file. Every time you run Terraform, it compares the latest status of your resources with the state configurations you declared and it determines what changes need to be applied.

When working with a team, you would need to manage shared storage for state files in a remote backend. This will prevent multiple team members from applying changes at the same time. Using a remote backend also provides access control management as data in the state files are stored in plain text, including passwords. A number of remote backends are supported. However, the example below will be using AWS S3 as the remote backend.

The Why

In my opinion, the following reasons explain why using Terraform in your project is a good idea:

Speed. As I mentioned above, the automation benefit of using this tool is truly the best part! By leveraging Terraform, you can configure and provision an entire infrastructure architecture for multiple environments (development, testing/staging, production) by running a few commands.

Collaboration. Terraform captures the desired project goal in a state and it keeps track of all state changes in the environment. This is perfect when working in a team, every member of the team is able to contribute in the same way they would with regular application code.

Agentless. Terraform is cloud-agnostic so you can use it with different providers such as AWS or Azure.

Reusability. Terraform is modular. If you are provisioning similar resources, you can abstract this code, create a module and reuse it. This saves you a lot of work and reduces repetition in your code.

Error reduction. Standardizing the creation of cloud resources using code minimizes the probability of errors when provisioning in multiple environments.

The How

It’s time to dive into the fun part! Let’s talk about how to set up Terraform in your project.

1) The first thing you need to do is download Terraform.

2) Create a directory dedicated to terraform in your project. I called mine tf.

3) Create a main.tf file in your newly created directory. Here is where you are going to define your providers. In this example, we are defining AWS as a provider.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"  
    }
  }

  required_version = "~> 1.3.6"
}

4) Create a backend.tf file. Here we are going to create and configure our remote state storage using a S3 bucket and a DynamoDB table. I’ve added comments above every resource block so you get a good idea of what these resources are doing. I encourage you to check the Terraform documentation for each resource as well. Also, here is an excellent post that explains each line in detail.

Essentially, the following code creates a S3 bucket called “remote_state” that cannot be deleted, keeps versioning of every change, uses encryption by default, and blocks public access.

# ----------------------------------------------------
# configure aws provider
# ----------------------------------------------------
provider "aws" {
  region = "us-east-2"
}

# ----------------------------------------------------
# create S3 bucket (backend)
# ----------------------------------------------------
resource "aws_s3_bucket" "remote_state" {
  bucket = "<YOUR-PROJECT-NAME>-remote-state"

  # Prevent accidental deletion of this S3 bucket
  lifecycle {
    prevent_destroy = true
  }
}

# Every update to a file in the bucket creates a new version of that file
resource "aws_s3_bucket_versioning" "enabled" {
  bucket = aws_s3_bucket.remote_state.id
  versioning_configuration {
    status = "Enabled"
  }
}

# Turn server-side encryption on by default
resource "aws_s3_bucket_server_side_encryption_configuration" "default" {
  bucket = aws_s3_bucket.remote_state.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

# Block all public access to the S3 bucket
resource "aws_s3_bucket_public_access_block" "public_access" {
  bucket                  = aws_s3_bucket.remote_state.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

In addition, we create a DynamoDB table for locking. It uses a primary key called LockedID and it has to match exactly (spelling and capitalization) for locking to work.

# ----------------------------------------------------
# create dynamo db table for state locking 
# ----------------------------------------------------
resource "aws_dynamodb_table" "terraform_statelock" {
  name           = "<YOUR-PROJECT-NAME>-tf-statelock"
  read_capacity  = 20
  write_capacity = 20
  hash_key       = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }
}

5) Set your AWS secret access key and access key id to access the AWS api on your terminal.

export AWS_ACCESS_KEY_ID=********
export AWS_SECRET_ACCESS_KEY=********

6) On your terminal, cd into the tf directory and run terraform init. This command will download the provider code. Then, run terraform plan to see a list of the changes that will be recorded on your state.

7) Run terraform apply. This command will build the S3 bucket and the DynamoDB table we declared above.

8) Now that we have provisioned the resources needed, let's add a backend configuration to the terraform configuration code under the main.tf file. The following code is defining S3 as our backend.

terraform {
  ...

  backend "s3" {
    bucket = "<YOUR-PROJECT-NAME>-remote-state"
    key    = "global/s3/terraform.tfstate"
    region = "us-east-2"

    dynamodb_table = "<YOUR-PROJECT-NAME>-tf-statelock"
    encrypt        = true
  }
}

9) Run terraform init. This command will configure the Terraform backend to the S3 bucket as indicated above. Go to the AWS console and take a look at your DynamoDB table, you should see your first state file!

10) Run terraform apply. After setting up our lock DynamoDB table, this command prompts Terraform to acquire a lock before running apply and releases the lock after it’s done.

That’s it! Now your project is set up to use Terraform. From here, we can declare resources and provision them by running terraform plan and terraform apply. I’m planning to write a continuation post that uses this setup as a base to provision a simple REST api. Thank you for reading!

Give this post a reaction if you found it helpful and follow me on Twitter and Dev.to to keep up with new posts!

Resources:
https://developer.hashicorp.com/terraform/language
https://www.linode.com/docs/guides/introduction-to-hcl/
https://developer.hashicorp.com/terraform/language/state
https://zerotomastery.io/blog/benefits-of-using-terraform/
https://www.varonis.com/blog/what-is-terraform

Demystifying React Hooks: useReducer

Milu — Mon, 13 Jul 2020 14:54:35 +0000

React Hooks are a simpler way to encapsulate stateful behavior and side effects in functional components instead of classes. Some hooks are easier to understand than others, therefore this series of posts will focus on demystifying the hooks that are not as straightforward.

So far, we have explored useCallback, useMemo, useRef, and useContext so make sure to checkout my previous posts if you haven’t already. This week, let’s start with the basics by explaining the JavaScript reduce method. Once we explore the basics, it will be much easier to understand the useReducer hook, as well as how and when to use it in your code.

What is a reducer?

A reducer is the action that will be executed in order to get only one value. The goal of a reducer is to reduce (...duh!). The value returned could be a number, a string, an array or even an object, as long as it is a singular value. Moreover, it is important to highlight that reducers return a new value instead of mutating your initial value.

reduces are very useful when you want to obtain a single value after applying some logic to a group of values. For instance, if you want to add up an array of numbers to obtain a total value as we do in the following example.

We apply the JavaScript reduce method to an array of numbers called nums = [1,2,3,4,5]. The reduce method takes two parameters:

reducer - a function that provides instructions to obtain one value. In this case, to sum up all the given values in the nums array.

const reducer = (accumulator, currentValue) => accumulator + currentValue;

initialValue - the starting point value when implementing the reducer function's instructions. In our example, we define our initial value as 0 so the total value returned reflects only the sum of the values in the array nums.

const initialValue = 0;

Now that we defined the elements involved, let’s see it all together. The reduce method takes our initialValue and builds on it by following the instructions given under the reducer function, adding each value in the nums array until it is able to return one total value.

// reducer method - the action that will be executed in order to get one value
const reducer = (accumulator, currentValue) => accumulator + currentValue;

// array of values that we want to add up
const nums = [1,2,3,4,5];

// initial value set to 0
const initialValue = 0;

// JavaScript reduce method receives two parameters: the reducer function and initial value defined above
const totalValue = nums.reduce(reducer, initialValue);

What is useReducer()?

The useReducer hook is used with state management. It receives the following parameters:

reducer - a function that provides instructions on how to manage state. It takes two parameters state and action and it returns a new state.

// reducer type
(state, action) => newState

initialState - the starting point value. It will change according to the reducer instructions.

Does it look familiar? Well yeah... It takes similar parameters as the reduce function explained above. However, the useReducer hook does not return just one value as reduce does. Instead it returns two elements as an array, the current state and a dispatch function.

const [state, dispatch] = useReducer(reducer, initialState);

If you are familiar with React hooks, you probably have used useState before. Let’s compare these two hooks

// useState implementation
const [state, setState] = useState(initialState);

// useReducer implementation
const [state, dispatch] = useReducer(reducer, initialState);

useReducer and useState both return a stateful value (state), and a function to update the state (setState and dispatch). In addition, both hooks receive an initial state value (initialValue). The main difference in these two initializations is that useReducer also takes a reducer function, which will be called when we use the returned dispatch function. Let’s explore how useReducer works in the next section.

How to use useReducer?

Sometimes the best way to explain how something works is with an example so let’s take a look at one. Here is a definition for an initialState, also called a store of data, that contains a list of dogs up for adoption with their name, breed, and adoption status.

const initialState = [
 {
      name: "Waffles",
      breed: "Chihuahua",
      adopted: false,
  },
  {
      name: "Charlie",
      breed: "Pitbull",
      adopted: true,
  },
  {
      name: "Prince",
      breed: "German Shepherd",
      adopted: false,
  },
];

Now let’s create a reducer function to update our initialState list of dogs as they get adopted or returned. This function takes the following parameters:

state - the current state of our dogs in adoption.

action - an object that contains the following:

type of action we want to perform. In this case, we are only building two options, adopt or ‘return’.
payload optional data. In our example, we will pass the dog’s name so we can identify which dog got adopted or returned.

const reducer = (state, action) => {
  switch (action.type) {
    case 'ADOPT':
      return state.map(dog => {
        if (dog.name === action.payload) dog.adopted = true;
        return dog;
      });
    case 'RETURN':
      return state.map(dog => {
        if (dog.name === action.payload) dog.adopted = false;
        return dog;
      });
    default:
      return state;
  }
}

Now It’s finally time to implement our useReducer() hook! Take a look at the example below, where we define our useReducer() hook with the initialState (adoption dogs list) and the reducer function we created to handle their adoption status.

We iterate through our dogs list state and display a button that will say adopt or return depending on their current adoption status. The onClick handler assigned to our button will call a function in charge of using the dispatch function returned by our useReducer() hook passing the type of action it needs to perform and the dog’s name as payload.

const adoptDog = name => dispatch({ type: 'ADOPT', payload: name });

The dispatch function will pass this data to our reducer function, where we will use the type to identify what section of code needs to run and the payload to find the dog record we need to update.

When should you use useReducer?

When explaining the useReducer hook, we compared it to useState so you might be wondering… when should I use useReducer and when should I use useState?

The useReducer hook is a preferred alternative to useState when dealing with the following:

Complex state logic that involves multiple sub-values
State values that depend on the state of other state elements

Summary

The JavaScript reduce method is very useful when you want to obtain a single value after applying some logic to a group of values.
reducers return a new value instead of mutating your initial value.
The useReducer hook is used with state management.
The useReducer hook should be used when dealing with complex state logic, multiple sub-values, or when your state depends on state sub-values.

I hope this post helped you get a better understanding of the JavaScript reduce method and the useReducer() hook and that you will start taking advantage of these concepts in your future projects.

I enjoy creating content that explains concepts in really simple terms. Why? Because knowledge is power and I want to help beginner developers expand their knowledge and thrive.

Give this post a reaction if you found it helpful and follow me on Twitter and Dev.to to keep up with new posts!

Demystifying React Hooks: useContext

Milu — Sat, 27 Jun 2020 15:36:24 +0000

React Hooks changed the way functional components are used providing them with a simpler way to encapsulate stateful behavior and side effects in a user interface. Since some hooks are easier to understand and use than others, this series of posts will focus on demystifying the hooks that are not as straightforward.

So far, we explored useCallback, useMemo, and useRef in depth. This post will start by exploring the difference in between prop drilling and context, followed by defining a context object, explaining how to use the useContext() hook, and how to optimize its performance.

Prop drilling vs Context

React provides us with a data-flow where a parent component uses props to share data with its children. This way of tracking data works great for small apps, however, as your application grows you might find yourself passing a prop through multiple layers of components. This is called prop drilling.

When passing props through multiple layers, identifying where data is being initialized and when data is actually being used can become very challenging and cumbersome. In addition, refactoring your code could lead to passing unnecessary props or using multiple names for one prop (AKA bugs!).

An alternative to prop drilling is to use Context, a simple and light solution that gives us the capability of accessing data across components even when they don’t have a parent-child relationship.

What is a context object?

A context object is created using the createContext() API and its composed by two elements:

Provider: it provides the value
Consumer: it consumes the value

To create a context object, you can initialize it empty or with a value:

const testContext = createContext();

And you can access its elements by destructuring them in this way:

const { Provider, Consumer } = testContext;

How to use the Provider?

The Provider in your context object needs to wrap around the parent element of a component-tree. This gives every component under that component-tree access to your global data. Take a look at the <Provider> tags below, they are making the name state accessible to all the components being wrapped. Now, the components <NameModifier /> and <NamePrinter /> (and any of their children) have access to the state name even though we are not passing name as a prop.

const App = () => {
  const { Provider } = testContext;
  const [name, setTestName] = useState(“Milu”);

  return (
    <Provider value={{ name }}>
      <NameModifier />
      <NamePrinter />
    </Provider>
  );
};

How to access our global data using useContext()?

The useContext() hook accepts a context object (defined above) and returns the current values made available by the Provider as static variables.

Here we have our <NamePrinter /> component (wrapped by the Provider tag in the previous section of code) and we are accessing the value of name by using our userContext() hook.

export const NamePrinter = () => {
    const { name }  = useContext(testContext);

    return <div>My name is {name}!</div>
};

Did you notice how <NamePrinter /> is not taking any props? The name value is being accessed using the useContext() hook instead.

How do I update my context?

You can also make functions available through your Provider!

In the following example, I’ve created a function called updateName() that allows you to modify the name state. If you take a look at the <NameModifier /> component, I’m accessing the updateName() function using the useContext hook and calling it every time my input changes.

What about performance?

A component that uses useContext() will re-render when the value in the context object is updated. You could run into an instance where one of the values in your context changes very often, which could cause all your components using useContext() to re-render even though the fast-changing-value is only used in a small component-tree.

The recommended solution is to split Context. Therefore if you have Light/Dark Themes and a toggle to choose in between them that most likely won’t change too often in comparison to other values being shared by your context, you want to create a ThemeContext and AppContext as shown below.

const App = ({ user, theme, themeToggle }) => {

  return (
    <ThemeProvider value={{ theme, themeToggle }}>
      <AppContext value={{ user }}>
        <HomePage />
      </AppContext>
    </ThemeProvider>
  );
};

Summary

The use of a context object is a great alternative to prop drilling. It allows you to access global data without passing it as props and it subscribes to it to re-render when it changes.

The context object contains two elements: Provider and Consumer.

The Provider element needs to wrap the component-tree that will have access to the global data.

The useContext() hook allows you to access the global data from any child components in the component-tree under the Provider wrapper.

To avoid unnecessary re-renders, split your context. i.e. using ThemeContext and AppContext.

I hope this explanation of useContext() was helpful and that you will be applying these new concepts in future applications!

I post new content every week. We will be exploring a different React hook next Weekend. Follow me on Twitter and Dev.to to keep up with new posts!

Demystifying React Hooks: useRef

Milu — Sat, 20 Jun 2020 17:02:13 +0000

React Hooks changed the game when they came out! They are a simpler way to encapsulate stateful behavior and side effects in a user interface while using less code and increasing readability. Some hooks are easier to understand and use than others, this is why this series of posts will focus on demystifying the hooks that are not as straightforward.

Last week, we explored useCallback and useMemo in depth. Today, let’s start by explaining what it means to imperatively modify a child and the DOM, continue by focusing on defining the useRef hook and discussing how, when, and where to use it.

Imperatively modify a child and the DOM

If you have worked with React before, you must be familiar with how a parent component uses props to interact with its children. In order to re-render a child component with different data, the parent component passes new props.

At times, we face situations where we need to imperatively modify a child component outside of the typical "passing props" dataflow or we want to manually access DOM nodes or React elements created in the render method. Here is when useRef() becomes handy!

Why is useRef() Hook special?

The useRef() hook persists in between component renders (like state).

The magic of useRef is that it can be mutated without causing your component to re-update because the useRef value exists outside of the render cycle.

How to use useRef() Hook?

You initialize a useRef() hook by passing an initial value to it or initializing it empty and updating its value later:

const testRef = useRef(1)

useRef() stores an object that contains an attribute called current, which stores the passed value, in our example, it would hold the value 1.

testRef = { current: 1 }

When to use useRef() Hook?

To manage focus, text selection, or media playback. Most elements inside of your document have a ref attribute, which facilitates the use of useRef to reference elements inside of your HTML. As an example, take a look at this <input/> HTML tag, we created a useRef value and passed it to <input/> as a ref attribute. Now, we are able to imperatively modify the input element with a couple of functions that get the <input/> to focus or blur.

To access a previous value. Another helpful use for useRef is to store the previous value of your state. Take a look at the example below, we have a list of three Pokemon and you need to select your favorite. Currently Pikachu is selected… but let’s be real, Pikachu is overrated. Select any of the other options and you will see your previous selection at the bottom. This is possible as a result of the use of our useRef hook:

const previousSelected = useRef()

Then, everytime we select a different option, we keep track of the previous selection in our changeSelection() function:

previousSelected.current = favPokemon

Also, according to React Docs, refs are useful to trigger imperative animations and to integrate with third-party DOM libraries.

Where should you update a useRef() value?

Updating a ref value is considered a side effect. This is the reason why you want to update your ref value in event handlers and effects and not during rendering (unless you are working on lazy initialization). React docs warns us that not following this rule could lead to unexpected behaviors.

Should you use refs instead of state?

Big NO. Refs aren’t reactive, which means changing its value won’t cause the HTML to update.

Take a look at the following example to make sure you understand why refs should not replace state.

We initialized a state and a ref with $1000 dollars. This component allows you to spend this value dollar-by-dollar every time you click the button Spend.

When you spend the money value stored in state, it triggers a re-render and it updates the view to show you the new value.

Now, if you spend the money value stored in ref, it will also subtract a dollar on every click, however, this change won’t trigger a re-render so you won’t see a change in your HTML.

You can check out the console to see that ref value is truly changing inside the component.

Is useRef() the same as createRef?

No.

createRef() useful to access DOM nodes or React elements. BUT it creates a new instance of the ref on every render instead of keeping a value between renders when used in functional components (This does not apply if you are using a class component!).

useRef() useful to access DOM nodes or React elements AND it holds a value even when a component re-renders. Here is an example that will help you see the difference.

Take a look at the following code, we are initializing two ref values as null, using createRef and the useRef respectively.

Everytime we click on the Add a render! button, we update the renderCounter state triggering a re-render. On every render, we check if the refs values are null and if they are, we assign the current renderCounter state value to it.

Notice that the ref value created using useRef is only null on the first render, so it is set to 1 once and never again.

On the other hand, the ref value created using createRef is created on every single render, so it always starts as null and then it is reassigned the current state value under renderCounter.

Side note: This is a simple example to illustrate the difference in between createRef and useRef. However, modifying the value of a ref should occur in an effect or event handler, not as shown in this example.

Summary

The useRef() hook helps create mutable variables inside a functional component that won’t update on every render.

Refs are helpful to access DOM nodes or React elements (what is being rendered) and for keeping values in between renders, such as the previous value of a state.
useRef() should not be used to replace state because it is not reactive and it won’t trigger a re-render.
Refs should be updated inside effects and event handlers to avoid weird behaviors.

I hope this post helped you expand your understanding of useRef() and that you will start taking advantage of this feature in your future projects.

I post new content every week. We will be exploring a different React hook next Weekend!

Follow me on Twitter and Dev.to to keep up with new posts!

Demystifying React Hooks: useCallback and useMemo

Milu — Sun, 14 Jun 2020 22:49:17 +0000

React Hooks introduced the capability to use state and other lifecycle features while using functional components instead of classes. Hooks are a simpler way to encapsulate stateful behavior and side effects in a user interface while using less code and increasing readability.

Some hooks are easier to understand and use than others, therefore this series of posts will focus on demystifying the hooks that are not as straightforward. Let’s start by explaining what occurs when a component re-renders, followed by defining the purpose of useCallback and useMemo, and finally discussing when it is and when it is not appropriate to use these hooks.

What occurs when a component re-renders?

As you might already know, React re-renders components on every state change or when props change. Since functions are considered objects in JavaScript, all objects (including functions) created under a React functional component will be created again on every re-render. This occurs as a consequence of referential equality, which means that two objects that look exactly alike are not the same unless they both point at the same object.

In other words, when a React component is about to re-render, it compares each object created under its original component with the new version of itself. And even though the objects are exactly the same, they are not pointing at the same object, therefore React identifies them as different objects and it allows their re-creation all over again under each re-render.

What is the purpose of useCallback and useMemo?

The purpose of useCallback and useMemo, if used correctly, is to prevent unnecessary re-renders and make your code more efficient.

Let’s take a look at their structure. Both of these hooks receive two parameters:

1) a function
2) an array of dependencies

useCallback hook returns the same instance of the function being passed (parameter #1) instead of creating a new one every time a component re-renders.

It creates a new instance of the function being passed (parameter #1) only when the array of dependencies (parameter #2) changes.

Let’s look at an example, here we have a simple app that adds two values. The user can increment the first value and/or decrease the second value and the result will update accordingly. We also have a third extra value that the user can update, however, this number is not being used in the computation.

If the user interacts with the extra state value, the component would re-render creating a new copy of the additionResult function even though extraVal is not used in it. In this example, we implement the useCallback hook to only create a new copy of the additionResult function if firstVal or secondVal are updated.

useMemo hook is very similar, however, instead of returning an uncalled function as useCallback does, it calls the function being passed and only returns a result value when the array of parameters change. In other words, useMemo calls the passed function only when necessary and it returns a cached value on all the other renders.

In this example, we implemented an app that accepts a number and it returns it's factorial. For instance, if we typed the number 5, it would use a recursive function to compute 5!= 5*4*3*2*1=120. In this case, we used the useMemo hook to tell React to only recalculate when the number changes.

When to use them?

If you are thinking of adding useCallback and useMemo hooks everywhere in your component, please don’t.

Both of these hooks add some extra complexity to your code and they require a lot of things working under the hood.

Adding performance optimizations using useCallback and useMemo is expensive and these optimizations don’t always bring enough benefits to offset their cost.

You should consider using useCallback and/or useMemo hooks on the following situations:

1) Processing large amounts of data
2) Working with interactive graphs and charts
3) Implementing animations
4) Incorporating component lazy loading (useMemo specifically)

Summary

When a component is re-rendered, it creates new instances of all objects, including all the functions in it.

useCallback - Allows you to cache an instance of a function between renders.

useMemo - Allows you to cache a value between renders.

I hope you found this post helpful and that you will start using useCallback and useMemo with confidence in your next project.

I post new content every week. We will be exploring a different React hook next Sunday!

Git Explained: Tips and Tricks

Milu — Sat, 06 Jun 2020 13:41:30 +0000

As you learn Git and start getting more comfortable with the basics, you also want to learn ways to speed up your workflow. Git is such a powerful tool and there are numerous ways to achieve an intended action, however, some methods are quicker than others. Today we are going to discuss a few tips and tricks that will lead to a more productive way of interacting with version control on your daily development tasks.

Checkout your last branch

We already learned that in order to move in between branches we need to use the command git checkout [branch-name]. You can also quickly switch to the last branch you were in, without having to remember its name, by using the following command:

  git checkout -

Copy a file from another branch with one command

Sometimes you want to reference code that lives in another branch that hasn’t been merged into master yet. The obvious thing to do with the basic commands you have mastered so far is to stash your changes, checkout the other branch, copy or just look at the file contents you want to reference, and then switch back to your current branch. Let me show you a way to get this same intended action with just one command:

git checkout [branch-name] -- [path/to/file-name]

Restore a deleted file

Have you ever cleaned up a project and then realized you actually wanted to keep one of the files you removed? (Sigh...). Here is a way to restore it in one command:

git checkout [deleting-commit]^ -- [path/to/file-name]

Auto-correct Git Commands

Git can help you by auto-correcting a mistyped command too! By setting up the following configuration, if you type something like ‘chekcout’ instead of ‘checkout’, Git will automatically fix it for you.

git config --global help.autocorrect 1

Undo committed changes to a single file

Every so often, you will commit some changes and then realize that you committed changes to a file by accident (Another sigh...). Here is one command that will allow you to remove the changes made to that file in your last commit:

git reset HEAD^ [file-name] git commit --amend

Create your own shortcuts with Git aliases

Some Git commands can get pretty long and Git does not infer the command you are typing as you type it (silly Git!). The solution for this is to set up aliases for your most used commands using the following git config command:

git config --global alist.[shortcut-name] [command]

The following command will allow you to use the shortcut git co [branch-name] instead of git checkout [branch-name] every time you want to switch in between branches:

git config --global alias.co checkout

Here are some other useful aliases you can use to speed up your workflow:

git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status

You can also add an alias for those commands that you wish git offered out of the box!
For instance, If you wish Git had an unstage command, you can create your own using the following:

git config --global alias.unstage ‘reset HEAD --’

Now you only need to use git unstage [fileName] to unstage a specific file.

To list all the alias and configs you have setup so far:

git config --list

I hope you give these shortcuts and configurations a try! I promise they will save you some precious time that can be wisely used to continue solving complex problems.

If you enjoy learning and growing your Git skills and understanding, make sure to check out my other previous Git posts!

Git Explained: A Project Umbrella Structure Using Git Submodules

Milu — Sat, 30 May 2020 19:23:45 +0000

Oftentimes, a team of developers will be faced with the decision of implementing a Git structure to handle the different parts that a project entails. Some teams opt for a monorepo, while others decide to break it down into sub-projects, for instance, a repository for the UI and another one for the API. Both Git structures have advantages and drawbacks.

Monorepos offer benefits such as code sharing, less code duplication, a single build, and atomic commits. However, monorepos also deal with a large number of commits in unrelated parts of the tree, as well as potential performance issues when cloning, fetching, and pushing code. On the other hand, maintaining sub-projects also translates into multiple repositories to clone, multiple sets of instructions to follow in order to install and build, and multiple directories to keep up with.

Recently, I’ve been introduced to the use of Git Submodules to create a central umbrella repository that points to a particular commit in both the UI and API external repositories. This umbrella structure allows you to keep a sub-project composition with some of the advantages of using a monorepo such as managing documentation and configurations in one central place, and the ability to pull the whole project, including sub-projects, in one step. This post is going to discuss the benefits of using an umbrella repository structure using Git Submodules, the struggles that come with it, and the commands that you need to learn to start using this Git structure.

The benefits

Sub-project composition. Having multiple repositories for the different parts of your project allows you to give limited access on a “need to code” basis. For instance, you might be in a situation where a frontend developer is added to your team for a few weeks to speed up the UI implementation. This developer can easily choose to pull only your UI repository, without having to mess with the API.

Continuous Development. The proposed umbrella structure using Git Submodules keeps a sub-project composition that allows each repository to have it’s own deployment process.

Documentation in one place. The umbrella repository gives you space to store documentation that applies to the whole project in a single location. I personally like to keep a global markdown file with the instructions to build and run the whole project using Docker in the umbrella repository and a markdown file in each repository with instructions on how to install and use each sub-project locally.

Configurations in one place. Our team uses Docker containers to create, deploy and run applications. The umbrella repository is a fantastic spot to place a docker-compose.yml file that builds and runs a database image, your api, and ui environments with one command.

Atomic code pulling. By using the --recurse-submodules flag when cloning an umbrella repository, you get all the nested directories that contain submodules in one command. In other words, you get your UI and API repositories all at once.

The struggles

Need to specify the use of Git Submodules in instructions. If your team is not used to this Git structure, they most likely won’t know how to clone or handle them correctly. Git does not download submodule contents by default, so make sure to include this information in your README.

Manual retrieval of submodules updates. Git won’t automatically register the updates to submodules. You need to run git submodule update --remote to see changes made to a submodule.

Simple implementations only. So far, I’ve only used this umbrella structure to link the UI and API repositories per project. I can see how keeping up with more than two submodules could get challenging and might require you to look into a different implementation.

Mostly useful when using Docker. If you are not using Docker, the benefits of this structure might not be as impactful.

The commands

Let’s discuss the possibilities and commands you have in your toolbox to implement this umbrella structure:

Create a project with submodules
Rename a submodule
Clone a project with submodules
Work in a submodule
Check and pull submodule updates
Update umbrella project with latest submodule commits

Create a project with submodules

To explain this action clearly, I will create a repository called umbrella and two repositories called umbrella-ui and umbrella-api in GitHub. You can check them out here.

cd[umbrella-project-name]
git submodule add [git@github.com:your-account/umbrella-ui.git] [name]

Note: the name parameter is optional. If you don’t pass a name, you will get the submodule repository name. In this case, I will give it the “ui” name parameter because I don’t want a redundant directory name like “umbrella-ui” inside my “umbrella” project.

Run the ls -a command to see a new directory called ui and a new file called .gitmodules. The .gitmodules file is a configuration that stores the mapping between your main project and its submodules. It will look similar to the following:

[submodule “ui”]
path = ui
url = git@github.com:your-account/umbrella-ui.git

After committing and pushing this change, you should see a folder for your submodule that points to the latest commit in the submodule's master branch.

Rename a submodule

If you forget to pass a name parameter when adding your submodule, you can still change your submodule directory name using the following command:

git mv [old-name] [new-name]

Clone a project with submodules

Pass the following command to automatically clone your project and its submodules. If you don’t pass the --recurse-submodules flag, your directory will be empty.

git clone --recurse-submodules [git-repo-url]

Work in a submodule

This is the same process that you follow when dealing with a regular repository. You make changes, commit them, push them to remote.

Check for submodule updates

When changes in submodules are pushed to their remote repository, you are going to need to check for these changes and update your umbrella repository because the commit pointers will be out of date.

To make sure you understand this concept, I will show you the umbrella-api repository, which has been updated and the last commit in master is 6302c8…

Now let’s look at our umbrella repository, the api submodule is not pointing to the latest commit in umbrella-api. Instead, it is pointing at an old commit 15a146…

You can pull the changes made in all your submodules directly from the umbrella directory with the following command:

// fetch all new updates in submodules
git submodule update --remote

// see which submodule has been modified
git status

// see all new commits that have been pulled down
git diff

Update umbrella project with latest submodule commits

Now that we pulled changes made in our submodules, we need to update our umbrella project pointers. This is VERY IMPORTANT because if someone clones our umbrella project in this state, they won’t get the newest code under our submodules.

// add all submodules changes
git add .

// commit new pointers
git commit -m “Update submodule pointers”

// publish the changes
git push origin master

Note: You can also use the following shortcut to pull the latest changes made to your submodules and get your umbrella project to point to the last commits.

git submodule update --remote --merge

Now our umbrella project points to the latest commits in both submodules, umbrella-ui and umbrella api.

Have you used Git Submodules in a similar umbrella structure before? If not, I hope it sparks your interest and you give it a try.

Thank you for reading, liking, and sharing my Git Explained series posts, it truly means a lot to me. I enjoy putting them together and love your questions and suggestions.

Checkout my other Git Explained posts and keep an eye for the next one. I explore, define, and explain Git concepts every Saturday!

Git Explained: Proper Team Etiquette

Milu — Sat, 23 May 2020 19:38:01 +0000

Proper team etiquette will assist your team to achieve seamless collaboration and productivity. These rules are often gained with experience as most developers who are starting to grasp challenging new concepts do not prioritize proper Git etiquette. Even though these rules might not seem essential at first, they are immensely helpful during debugging, merging code, and managing pull requests.

This post aims to help you maximize your team’s use of Git by discussing etiquette pointers that will support you when creating branches and commits, as well as handling unnecessary, private, or large files. In addition, we will look at the different commands we can use to amend common mistakes that could hurt your workflow and team collaboration.

Branches

A repository always has a main branch called origin/master, which reflects the production-ready state or already deployed code, and developers branch and merge from it. During the implementation of a project, many supporting branches will be created. These branches should have a specific purpose, a limited life time, and a descriptive name. Here are some guidelines to create effective branches:

Create a branch per issue. You will have to create a merge request at some point in order to get your supporting branch merged into master. Merge requests are a great opportunity for feedback that will help you grow. Overly long merge requests get procrastinated or simply not reviewed in detail. In other words, you would miss out on getting feedback from your team that would help you grow.

Use a token at the beginning of your branch name. Tokens are groups agreed by your team that quickly communicate in which part of your workflow each branch belongs. Some popular tokens are feature/ or feature- and bug/ or bug-.

Note: The use of / in your naming convention might break your CI/CD pipeline if using Jenkins or other third-party tools. Make sure you talk to your team before choosing a token name convention.

This convention also allows you to list them by group:

git branch --list “feature/*”

Include issue number. This comes handy when your issues are not automatically linked to your branches. For instance, my team is currently using JIRA to track issues and Gitlab as our Git repository hosting service. It is really nice to be able to glance at a branch and know which issue it belongs to.

Use a descriptive and short name. Do your best to select short and well-defined names that communicate the task’s purpose clearly.

A well-thought-out branch name example for a new feature that adds a search bar under ticket #28 would be the following:

feature/28-search-bar

If you are reading this post and suddenly realized your branches are not following any of these rules… don’t panic! Let’s take a look at how you can rename your branches locally and remotely:

To rename your local branch:

# if HEAD is in the branch you want to change
git branch -m [new-name]

# if HEAD is in another branch
git branch -m [old-name] [new-name]

To rename a remote branch:

# Rename your local branch (step above)

# Delete your old remote branch
git push --delete remote branch-name

# Or use this shortcut
git push origin :[old-name] 

# Push your new-name branch to remote
git push origin [new-name]

# Reset the upstream branch for the new-name local branch
git push origin -u [new-name]

Clean unused and already merged branches. When you create a merge request, make sure you select the merging option that deletes your branch after merging. Moreover, make sure you exercise good housekeeping by deleting unused branches locally and remotely.

To prune all stale referenced remote branches:

git fetch --prune --all

To delete a branch locally:

# safely - Git prevents you from deleting it if it hasn’t been merged
git branch -d [branch-name]

# force delete
git branch -D [branch-name]

To delete a branch remotely:

git push origin :[old-name]

Commits

Good commit messages matter because they allow you to explain the changes you have made and why when you look back in history or when a team member is reviewing your merge request. Here are some guidelines to compose precise commit messages:

A commit should consist of a single logical change. This one can be hard, especially since it’s very tempting to commit all changes in one commit after several were made. Here is a flag that could help you out:

git add --patch

It will go through all the changes you made, one change at a time, and ask you if you want to commit that specific change.

Keep it short. No more than 50 characters please. If you are modifying or refactoring already existing code, give a short explanation of why you made that change. Not sure what to include in your commit message? Use the following command to see a list of changes in between your working tree:

git diff

Start with a capital letter. And keep it consistent.

No punctuation at the end. It's not necessary.

Start the sentence with a verb. Your commit message should complete the following sentence:

“This commit will…[commit-message]”

Good examples:

“Redirect user to the requested page after login”
“Fix typo in introduction to the user tools”

Are you not happy with your last commit? Use the following command to change it:

git commit --amend -m “New message”

You can also use this command if you want to make a change to your previous commit but want to leave your message intact. For instance, sometimes I forget to remove a log message and I don’t want to create another commit just for that.

git add changed/file.ts
git commit --amend --no-edit

Ignore files

Files that are not required by your project should not be tracked by Git. Understanding what to ignore is beneficial because it will help you keep an unclutter and secure project for you and your team members. Here is a list of common type of files to ignore:

Operating system files
Language and framework files
File downloaded with package managers
Usernames and passwords
Debugging logs

Add a local .gitignore file to the root of your project with the following command:

touch .gitignore

Include any file or folder that you would like Git to ignore on each line. Here are some examples:

# Ignore operating system files
.DS_store

# Ignore SASS config files
.sass-cache

# Ignore npm dependencies folder
/node_modules

# Ignore API credentials
.env

# Ignore all logs
*.log

Note: A DEV community member recommended gitignore.io to generate a .gitignore file in one step. This tool allows you to enter Operating Systems, IDEs, Programming Language, or Frameworks and it generates a useful .gitignore file for your project! They also have documentation to help you access their API using your command line.

Did you already commit a file you meant to ignore? It happens to the best of us! Let’s take a look at how to fix it:

First you need to remove the file from your repository. The following command will get Git to stop tracking [file-name], however, the file won’t be deleted from your working system.

git rm --cached [file-name]

Then add it to your .gitignore file and commit this change.

# Ignore [file-name]
[file-name]

Handle large files

Uploading large files to Git is uncommon, however, you could be faced in a situation where you might want to share some large data files with your team members. This could be a problem as cloning, fetching or pulling from a repository that stores large files takes a long time as every version of each large file is downloaded. Don’t cause your team members a headache by doing this, instead share big files through Git LFS (Large File Storage), an open source Git extension. This tool is useful because it replaces large files in your repository with small pointer files. Here are some instructions to use this tool:

Download and install Git LFS

git lfs install
Track your large files

git lfs track “files/*.csv”

This command will create or update a file called .gitattributes, which binds tracked file patterns. You will need to commit this file to your repository.

Notes:

To stop tracking a file with Git LFS, remove it from the .gitattributes file.
Cloning and pulling from a Git LFS is the same as using a normal repository.

These are some of the Git guidelines I’ve learned through working with different people in different projects. Everybody has different preferences, however it is important to choose a consistent set of Git rules when collaborating with a team so everybody is on the same page. Let me know in the comments if you have another rule you recommend!

Checkout my previous posts:
Git Explained: The Basics
Git Explained: In-depth Comparison

I explore, define, and explain Git concepts every Saturday!

Git Explained: An In-Depth Comparison

Milu — Sat, 16 May 2020 19:40:01 +0000

Git is a very powerful tool and It has a long list of capabilities available at your disposition. Some commands provide slightly similar results and it is worth understanding and comparing them in order to choose the one that satisfies your needs and improves your workflow. This post is going to define and compare the following commands: revert, checkout, reset, merge, and rebase.

Revert vs. checkout vs. reset

These tools allow you to undo and manipulate changes in your repository. The problem is that they are very similar, therefore it is really easy to get them confused. We will define each of them in detail and list their similarities and differences.

Git revert

This is an unconventional and safe way to revoke an operation as it prevents you from losing history. Git revert inverts the changes that were added in a commit and adds a new commit with the inverted content. This command is especially helpful when you have already pushed your changes to a remote repository as it keeps your original commit intact.

To revert using commit hashes: git revert [SHA]

To revert using ranges: git revert HEAD~[num-of-commits-back]

Git checkout

This is a versatile tool, it allows you to switch in between branches, inspect older commits, and undo local uncommitted changes by moving HEAD and updating your working directory accordingly.

To switch in between branches: git checkout [branch-name]

To inspect an older commit using commit hashes: git checkout [SHA]

To inspect an older commit using ranges: git checkout HEAD~[num-of-commits-back]

Notes:

When moving HEAD to a different branch or commit, you are going to need to commit or stash any uncommitted changes that could be lost.
You will be in a detached HEAD state by switching to an old commit, which is great for inspection but not for modifications. In other words, you are not in your branch anymore so don’t add any commits on a detached HEAD because you are going to lose them when you switch to another branch. If you are planning to commit changes on a detached HEAD, make sure to create a new branch from it.

To undo all local uncommitted changes: git checkout .

To undo a specific local uncommitted change: git checkout -- [file-name]

Git reset

This is a powerful but complex way to undo an operation. There are three available arguments:

--mixed
This is the default mode so git reset --mixed is the same as git reset. By using any of these commands you will move HEAD to the latest commit and all the changes that were added after that commit will be available as untracked changes in your working directory.

--soft
This operation is similar to the one executed using the --mixed argument. HEAD is moved to the latest commit, however, the changes that were added after that commit are left staged.

--hard
Use the command git reset --hard only when you know what you are doing as it is very dangerous. By resetting the hard way, you will move HEAD to the latest commit and destroy the changes that were added after. This cannot be undone so use it wisely.

You should not use git reset when you have already pushed to a remote repository. Removing a commit that other team members have continued building upon is hard and it would disrupt your team member’s workflow.

Bonus action: Use git reset -- [file-name] to unstage a file that hasn't been committed yet.

Merge vs. rebase

When multiple people are working in a project you will need to combine your code at some point. Git rebase and merge have different approaches to consolidate the changes from one branch into another one.

Git merge

It uses a non-destructive operation to combine two branches’ histories without changing them. In addition, it creates a new “merge commit” every time it’s used. This is a great way to consolidate changes, however your commit history could get several merge commits depending on how active your master branch is, which can get cumbersome.

To combine the latest changes from master into your branch:
git checkout [branch-name] git merge master

Git rebase

This is a destructive operation as it moves an entire branch’s history on top of another one by rewriting the project history with new commits.

This command is useful if you prefer a clean and linear project history. However, it is not safe to rebase on changes that have been pushed to a remote repository master branch because you would be changing the master branch’s history while your team members continue working on a diverged version of it.

In addition, Git will not allow you to easily push a rebased branch back to a remote repository. You are going to need to force it by using git push --force, which overwrites the remote branch and could cause issues with other collaborators. In other words, stop yourself from confusing your team members and creating tedious conflicts by only using rebase to cleanup in-progress features and not the master branch.

I hope you found these comparisons helpful and easy to follow. I explore, define, and explain git concepts every Saturday!

If you are new to git, checkout my previous post Git Explained: The Basics.

Git Explained: The Basics

Milu — Sat, 09 May 2020 16:35:45 +0000

Git is scary when you are starting up. There is this imminent fear that you could possibly lose hours of hard work by using the wrong commands. Keep reading if this is how you feel every time you are about to use git. This post is going to define git, explain why you need to learn it, and break down the following basic commands in detail: clone, checkout, pull, add, commit, stash, and push.

What is git and why do you need it?

Git is one of the most popular version control systems and it helps software developing teams manage changes to their source code over time. In other words, version control keeps track of every change in your code and it allows you to go back in time when something goes wrong.

Also, it is really helpful to prevent concurrent work from conflicting when multiple people are working in the same project. An individual may be working on the sidebar navigation while another one is simultaneously updating the header.

Version control systems facilitate the work of multiple individuals by allowing them to use different branches as part of one “file tree” and merge their updated code to one source of truth when it's ready.

Git clone

Downloads a copy of the project (remote repository) to your local computer. To use this command, follow these steps:

1) Copy the clone or download link

2) Open your terminal

3) Access the location on your computer where you want to copy the project: cd [desired-location]

3) Clone the project: git clone [copied-link]

4) Use the commands cd [project-name], followed by ls and you should see the list of files you just cloned!

Git branch

Lists all your project branches and highlights your current branch. If you just cloned a project, you are going to be in the master branch (your source of truth). It is not advised to work directly on the master branch because there is a big chance you would have a broken project while you are adding some progress. Instead, you want to create a different branch, work on your changes or new feature and when you are done and everything is working as expected, merge that branch into master.

Git checkout

Selects the branch you want to work on.

If the branch already exists:
git checkout [branch-name]

If you want to create a new branch:
git checkout -b [branch-name]

Git pull

Pulls recent changes from the remote repository to your local files. If one of your team members merged a new feature into master, you need to pull the recent code added to master to keep your local files up to date.

Git status

Lists all the files that you have worked on and have not been saved in a commit yet.

Git add

Stages file that you would like to commit.

If you want to stage all the files that you have worked on: git add .

If you want to stage only one particular file: git add [file-name]

Git commit

Saves the group of changes you staged to your local repository. Add a comment with each commit that summarizes the change.
git commit -m “commit message”

Git stash

Saves any changes you have made locally and it reverts the working directory to match the HEAD of your last commit.

See a list of all the changes you have stashed: git stash list

Bring back the last changes you stashed: git stash pop

Clear all your stashed entries: git stash clear

Git push

Saves your local committed changes into the remote repository so everybody else has access to your work.
git push origin [branch-name]

What is next?

This is the first one from a series of posts about git. We will explore more advanced commands, git submodules, multiple remotes, and squashing commits before a pull request in the next weeks.

I hope this information was helpful and you feel a little more confident about working with git!