Forem: Avi Avinav

Remix & Shopify: Circumvent Shopify’s APIs and go open source

Avi Avinav — Tue, 01 Nov 2022 12:06:53 +0000

Shopify seems to acknowledge that open source is what developers want. First, they gave us Hydrogen and now they went even further by joining forces with Remix. While good news, some might still want to go all-in on open source and customizability by building with a setup that is fully open source across the entire stack.

In this article, you’ll learn how you can circumvent Shopify to get a fully functional ecommerce setup with Remix using only open-source tools. Win-win-win.

How it’ll work

First, we will replace Shopify’s functionality by combining the power of two of the most popular open source projects:

Medusa, the leading open-source ecommerce platform for developers allowing for great customization and is built with Javascript
Strapi, the leading open source CMS built for developers likewise highly customizable and also built in Javascript

In this tutorial, you'll learn how to build an ecommerce storefront using Remix and powered by Medusa & Strapi to avoid a full Shopify backend.

You can find the source code for this article in this repository. Below a sneak peak to the final result:

Prerequisites

Node v14 or above
Yarn is recommended, but you can also follow along with npm.
Redis
Medusa CLI: To install the CLI, run yarn global add @medusajs/medusa-cli.

Set Up Strapi

Install the Template

npx create-strapi-app strapi-medusa --template shahednasser/strapi-medusa-template

This creates a folder named strapi-medusa in your project. Once the installation is complete, the Strapi development server will start on port localhost:1337. A new page will also open in your default browser to create a new admin user and log in. After you have logged in, you can access your Strapi Dashboard.

Change Authorization Settings for the User

Your Medusa sever will require the credentials of a Strapi User in order to seed Strapi with mock data. To create a new user, go to Content Manager, then choose User under Collection Types.

Click on the Create new entry button at the top right. This opens a new form to enter the user’s details.

Enter the user’s username, email, and password. Once you’re done, click on the Save button at the top right.

Next, go to Settings → Roles → Authenticated and select all the permissions, and hit save.

Set up Medusa

To initiate your Medusa server, run the following command:

medusa new medusa-server --seed

The --seed flag creates an SQLite database and seeds it with some demo data.

Change to the medusa-server directory and go to medusa.config.js. Change the exported object at the end to enable Redis:

module.exports = {
  projectConfig: {
    redis_url: REDIS_URL,
    //...
  }
  //...
};

The default Redis connection string is redis://localhost:6379 but if you have made changes to it, go to the .env file and add the following:

REDIS_URL=<YOUR_REDIS_URL>

Where <YOUR_REDIS_URL> is your connection string.

Additionally, since the Remix storefront runs on localhost:3000, you have to add an environment variable STORE_CORS that sets the URL of the storefront.

Add the following in .env:

STORE_CORS=http://localhost:3000

Install Strapi Plugin

To install the Strapi plugin, run the following command in your Medusa server’s directory:

yarn add medusa-plugin-strapi

Then, add the following environment variables:

STRAPI_USER=<STRAPI_IDENTIFIER>
STRAPI_PASSWORD=<STRAPI_PASSWORD>
STRAPI_PROTOCOL=http
STRAPI_URL=<STRAPI_URL> # Optional
STRAPI_PORT=<STRAPI_PORT> # Optional

Where:

<STRAPI_IDENTIFIER> is either the email address or username of the user you created in the previous step.
<STRAPI_PASSWORD> is the password of the user you created in the previous step.
<STRAPI_PROTOCOL> is the protocol of your Strapi server. Since, you’re using a local Strapi server, set this to http. The default value is https.
<STRAPI_URL> is the URL of your Strapi server. By default, the URL is localhost.
<STRAPI_PORT> is the port the Strapi server runs on. By default, the port is 1337.

Finally, open medusa-config.js and add the following new item to the plugins array:

const plugins = [
  //...
  {
    resolve: `medusa-plugin-strapi`,
    options: {
      strapi_medusa_user: process.env.STRAPI_USER,
      strapi_medusa_password: process.env.STRAPI_PASSWORD,
      strapi_url: process.env.STRAPI_URL, //optional
      strapi_port: process.env.STRAPI_PORT, //optional
      strapi_protocol: process.env.STRAPI_PROTOCOL //optional
    }
  }
];

Test Integration

Make sure the Strapi server is still running. If not, you can run the following command to run the Strapi server in the directory of the Strapi project:

yarn develop

Make sure your Redis server is up and running as well.

Then, in the directory of your Medusa server, run the following command to start the Medusa server:

yarn start

This will start your Medusa server on localhost:9000. You’ll see that product.created events have been triggered along with similar events.

This will update Strapi with the demo products you seeded.

Add CMS Pages in Strapi

You will now use Strapi to manage content on your storefront’s homepage. You will be able to control three things from Strapi after this implementation: the hero text that will appear at the top of the storefront; the subheading below the hero text; and the list of products shown on the homepage.

On your Strapi dashboard, go to Content-Type Builder under Plugins in your Strapi Dashboard. This is where you can define the model/schema for your content.

Click on “Create new single type” under “Single Types”.

Enter the display name as “Home Page” (if you have used another, you will have to use the appropriate API ID for it later) and hit continue.

Next, select the component field and give it the display name “Hero Text”, and a category homepage (click create “homepage” under the category). Then, click on configure the component.

Then give it the name hero_text in the next step and click Finish.

Go to the Hero Text component under Homepage in components and create three text fields named start_text, mid_text and end_text.

Here, the three text fields have been added because later on in the article you will give a special underline to the mid_text to highlight it.

Go back to the Home Page type under single types and add a relation field to products. The relation should be “homepage has many products”. Give it a field name products_list.

Finally, add a text field heading_2. Save your changes in the homepage content type.

This is what your homepage content type should look like:

Next, go to Settings → Users & Permissions Plugin → Roles → Public, and enable find permission for the homepage and product type. Hit save.

Now, go to the content manager and under the Home Page add your hero text and the products you wish to display under the relations section to the right. Hit save and then publish.

Set up the Remix Storefront

In this section, you’ll set up the ecommerce storefront with Remix.

Remix has three official pre-built templates for you to use depending on your needs, but you can also start with a basic one or create your own.

Set up Remix

To setup a Remix app (do this in a separate directory from medusa-server and strapi-medusa), run the following command:

npx create-remix@latest my-storefront

It will ask you a few questions. Choose Just the basics, then choose your preferred hosting platform (you can choose Remix App Server if you are unsure), choose typescript, and no for npm install if you wish to use yarn.

Then, change to the my-storefront directory and install dependencies with yarn:

cd my-storefront
yarn install

Configure Tailwind CSS

Install Tailwind CSS to design the UI element:

yarn add -D tailwindcss postcss autoprefixer concurrently

Run npx tailwindcss init to create your tailwind.config.js file. Then, set its content to the following:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Also, change the scripts in your package.json:

{
  "scripts": {
    "build": "npm run build:css && remix build",
    "build:css": "tailwindcss -m -i ./styles/app.css -o app/styles/app.css",
    "dev": "concurrently \"npm run dev:css\" \"remix dev\"",
    "dev:css": "tailwindcss -w -i ./styles/app.css -o app/styles/app.css"
  }
}

Then, create the file styles/app.css with the following content:

@tailwind base;
@tailwind components;
@tailwind utilities;

Lastly, add this to your app/root.tsx after the list of imports:

import styles from "./styles/app.css"

export function links() {
  return [{ rel: "stylesheet", href: styles }]
}

You can now use Tailwind CSS in your app.

Connect Storefront to Medusa Server

Once this is done let’s connect your storefront to your Medusa server.

First, you need to install a few packages with the following command:

yarn add medusa-react react-query @medusajs/medusa

The medusa-react library uses react-query as a solution for server-side state management and lists the library as a peer dependency.

In order to use the hooks exposed by medusa-react, you will need to include the MedusaProvider somewhere up in your component tree. The MedusaProvider takes a baseUrl prop which should point to your Medusa server. Under the hood, medusa-react uses the medusa-js client library (built on top of axios) to interact with your server.

In addition, because medusa-react is built on top of react-query, you can pass an object representing react-query's QueryClientProvider props, which MedusaProvider will pass along.

You also need to wrap your app in a CartProvider since that will let you use the cart functionalities provided by Medusa, which you will do later.

Create a file app/lib/config.ts. This file will contain your medusaClient which will let you use Medusa’s Javascript client in your app.

import Medusa from '@medusajs/medusa-js';
import { QueryClient } from 'react-query';

const MEDUSA_BACKEND_URL = 'http://localhost:9000';

const STRAPI_API_URL = 'http://127.0.0.1:1337/api';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      refetchOnWindowFocus: false,
      staleTime: 1000 * 60 * 60 * 24,
      retry: 1,
    },
  },
});

const medusaClient = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 });

export { MEDUSA_BACKEND_URL, STRAPI_API_URL, queryClient, medusaClient };

Now go to your app/root.tsx and import the required packages:

import { MedusaProvider, CartProvider } from 'medusa-react';
import { MEDUSA_BACKEND_URL, queryClient } from './lib/config';

You can also edit the meta here to change your metadata

export const meta: MetaFunction = () => ({
  charset: 'utf-8',
  title: 'New Remix App',
  viewport: 'width=device-width,initial-scale=1',
});

Below this, you will see the App component. In the returned JSX add the MedusaProvider and CartProvider with some base styles to the body:

return (
    <html lang="en">
      <head>
        <Meta />
        <Links />
      </head>
      <body className="bg-black text-slate-400 overflow-x-hidden justify-center flex">
        <MedusaProvider
          queryClientProviderProps={{ client: queryClient }}
          baseUrl={MEDUSA_BACKEND_URL}
        >
                    <CartProvider>
              <Outlet />
              <ScrollRestoration />
              <Scripts />
              <LiveReload />
                    </CartProvider>
        </MedusaProvider>
      </body>
    </html>
  );

Display Home Page from Strapi

The data for your home page is available on the Strapi endpoint: localhost:1337/api/home-page (add ?populate=* to also show the nested products). It returns an object with the data & meta arrays. You don't have to care about the meta, what you should really care about is data, it contains all the content you entered in your Strapi Dashboard.

First, create the file app/types/StrapiResponse.ts with the following content:

// StrapiResponse.ts

export type StrapiResponseType = {
  data: {
    id: number;
    attributes: {
      createdAt: Date;
      updatedAt: Date;
      publishedAt: Date;
      hero_text: {
        id: number;
        start_text: string;
        mid_text: string;
        end_text: string;
      };
      products_list: {
        data: Array<StrapiProductData>;
      };
      heading_2: string;
    };
  };
  meta: {};
};

export type StrapiProductData = {
  id: number;
  attributes: {
    medusa_id: string;
    title: string;
    subtitle: string | null;
    description: string;
    handle: string;
    is_giftcard: boolean;
    status: 'draft' | 'proposed' | 'published' | 'rejected';
    thumbnail: string;
    discountable: boolean;
    weight: number;
    product_length: null;
    width: null;
    height: null;
    hs_code: null;
    origin_country: null;
    mid_code: null;
    material: string | null;
    createdAt: Date;
    updatedAt: Date;
  };
};

This is the format in which your data is returned from the Strapi API.

Next, create a utility function to fetch your content from the Strapi API. Create a file app/models/home.server.ts with the following content:

// home.server.ts

import { STRAPI_API_URL } from "~/lib/config";
import type {
  StrapiProductData,
  StrapiResponseType,
} from "~/types/StrapiResponse";

export const getHomePageData = async () => {
  const homePage: StrapiResponseType = await (
    await fetch(`${STRAPI_API_URL}/home-page?populate=*`)
  ).json();

  const { data } = homePage;

  const { attributes } = data;

  const heroText = attributes.hero_text;
  const products = attributes.products_list.data;
  const smallHeading = attributes.heading_2;

  const homePageData = { heroText, products, smallHeading };
  return homePageData;
};

export type homePageDataType = {
  heroText: {
    id: number;
    start_text: string;
    mid_text: string;
    end_text: string;
  };
  products: StrapiProductData[];
  smallHeading: string;
};

In the getHomePageData function, you should only return the data you need on your home page.

In the above code sample, you will notice that in the import statement ~ is used, this is because it is the alias set for the app directory set in the tsconfig by default in Remix, if you wish you can change it at your convenience.

All files inside the app/routes directory will be a route. For example, app/routes/store.tsx will contain the /store route.

Next, go to app/routes/index.tsx and create a loader function:

import { getHomePageData, homePageDataType } from '~/models/home.server';

export const loader = async () => {
  const homePageData = await getHomePageData();

  return homePageData;
};

To use the response you received from the loader function you will use the useLoaderData hook from Remix inside the Index component:

import { useLoaderData } from '@remix-run/react';

export default function Index() {
  const { heroText, products, smallHeading } =
    useLoaderData<homePageDataType>();

    ...
}

Here, homePageData was destructured and brought in using useLoaderData, now you can use it on your page.

Then, change the returned JSX to the following:

export default function Index() {
    //...

  return (
    <div className="px-10 sm:px-20 md:px-44 pt-44 max-w-[100rem] flex-grow w-screen">
      {/* Hero Section */}
      <div>
        <h1 className="text-[2.5rem] sm:text-5xl lg:text-6xl xl:text-8xl relative font-medium lg:leading-[1.15] xl:leading-[1.2]">
          {heroText.start_text}{' '}
          {heroText.mid_text.split(' ').map((text) => (
            <span key={text} className="text-gray-50">
              <span className="relative">
                {text}
                <div className="h-1 bg-emerald-200 w-full absolute bottom-0 left-0 inline-block" />
              </span>{' '}
            </span>
          ))}
          {heroText.end_text}
        </h1>
      </div>
    </div>
  );
}

heroText.start_text brings data from the start_text text field under the hero_text component you made in Strapi. Similarly, heroText.mid_text and heroText.end_text are from mid_text and end_text fields from Strapi respectively.

Then mid_text has been split so that each word gets a uniform underline in case there are multiple words, you will see it happen a bit later in the homepage UI.

To display your products, create the file app/components/productCard.tsx with the following content:

import { Link } from '@remix-run/react';

interface ProductCardType {
  image: string;
  title: string;
  handle: string;
}

export default function ProductCard({ image, title, handle }: ProductCardType) {
  return (
    <Link to={`/products/${handle}`}>
      <div className="flex flex-col space-y-1 p-2 hover:bg-slate-400 hover:bg-opacity-25 cursor-pointer active:scale-95 transition ease-in-out duration-75">
        <img src={image} alt="" />
        <h3 className="pt-2 text-white text-xl">{title}</h3>
      </div>
    </Link>
  );
}

The Link comes from Remix and will help you redirect to the products page. The handle prop which is available in Medusa products will be used as a slug.

Now getting back to your app/routes/index.tsx, you will map your Strapi response (products) to the page.

Do this just below your hero section:

import ProductCard from '~/components/productCard';

export default function Index() {
    ...

    return (
        <div className="px-10 sm:px-20 md:px-44 pt-44 max-w-[100rem] flex-grow w-screen">
            ...

            <div className="flex flex-col items-center pt-40 pb-44">
            <h2 className="text-2xl sm:text-3xl lg:text-4xl pb-10 text-white">
              {smallHeading}
          </h2>
          <div className="grid grid-cols-2 xl:grid-cols-4 gap-x-6">
              {products.map(({ attributes }) => (
                <ProductCard
                  key={attributes.medusa_id}
                image={attributes.thumbnail}
                handle={attributes.handle}
                title={attributes.title}
              />
            ))}
          </div>
          </div>
        </div>
)

Test Homepage

To test out your homepage, start your Remix development server with yarn dev (make sure that your Medusa and Strapi servers are already running).

Your app is ready at localhost:3000 and it will look like the following:

Implement Add to Cart Functionality with Medusa

To add your products to the cart, you first need to associate a cart with the customer. To do this, you can create a wrapper around your app that checks if a cart has already been initialized or need to be created, and does the needful.

Create the file app/components/outletContainer.tsx with the following content:

import { useCart } from 'medusa-react';
import { ReactNode, useEffect } from 'react';

import { medusaClient } from '~/lib/config';

interface OutletContainerType {
  children: ReactNode;
}

export default function OutletContainer({ children }: OutletContainerType) {
  const { setCart } = useCart();

  useEffect(() => {
    const localCartId = localStorage.getItem('cart_id');
    localCartId
      ? medusaClient.carts.retrieve(localCartId).then(({ cart }) => {
          setCart(cart);
        })
      : medusaClient.carts.create().then(({ cart }) => {
          localStorage.setItem('cart_id', cart.id);
          setCart(cart);
        });
  }, []);

  return <div>{children}</div>;
}

You are using medusa-react's useCart hook, setCart will set your cart globally. You can then use it anywhere in your app. The outletContainer will also save cart localStorage so that the added items persist even when the user returns.

You will also need to show toast notifications when a product is added to the cart. Install react-hot-toast to do this:

yarn add react-hot-toast

Now, go back to your app/root.tsx and wrap your <Outlet /> with OutletContainer. Also, add <Toaster /> from react-hot-toast that will let you show notifications:

import OutletContainer from './components/outletContainer';
import { Toaster } from 'react-hot-toast';

export default function App() {
  return (
    ...
        <CartProvider>
          <OutletContainer>
            <Outlet />
        </OutletContainer>
        ...
                <Toaster />
      </CartProvider>
      ...
  );
}

Create Product Page

In this section, you’ll create a product page. When you are deploying to production, you can’t make a separate page for each of your products, so you will create a dynamic page that will run according to your product’s handle. In Remix you will name your dynamic pages as $slug.tsx.

You will need to get the handle from the URL of your page, you can do that with a loader function but it’s much simpler to use useParams hook.

Create the file app/routes/products/$slug.tsx with the following content:

import { useParams } from '@remix-run/react';
import { useCart, useCreateLineItem, useProducts } from 'medusa-react';

export default function ProductSlug() {
  const { slug } = useParams();
}

slug is getting your page’s slug from your URL, for example, in localhost:3000/products/sweatshirt the slug is sweatshirt (remember you passed in the handle in your ProductCard component).

Next, fetch your product from Medusa using the useProducts hook and add it to the UI:

export default function ProductSlug() {
  ...

  const { products } = useProducts(
    {
      handle: slug,
    },
    {}
  );

if (!products) {
    return <div></div>; // you can use skeleton loader here instead.
  }

const product = products[0];

return (
  <div className="flex flex-col items-center lg:justify-between lg:flex-row px-10 sm:px-20 md:px-44 pt-44 max-w-[100rem] flex-grow w-screen">
    <img src={product.thumbnail!} className="h-96 w-auto" />
    <div>
      <h1 className="text-4xl pb-10 text-white">{product.title}</h1>
      <p className="w-72">{product.description}</p>
    </div>
  </div>
 );
}

Here, the useProducts hook was used and passed the slug. While the product is being loaded you show an empty div (you can use a skeleton loader instead).

Finally, you use the first item returned by the useProducts hook which is the product that has the handle in the page’s URL.

Please notice that the title and description are used here from the Medusa server since the Strapi plugin supports two-way sync. So, whenever you make changes to the products in Strapi, they’re reflected on the Medusa server as well. You can alternatively show the CMS data for the product from Strapi instead.

You also need to show the prices for your customers according to their region. To do this, create the file app/lib/formatPrice.ts:

import { formatVariantPrice } from 'medusa-react';
import type { Cart } from "medusa-react/dist/types";
import type { ProductVariant } from '@medusajs/medusa';

export const formatPrice = (variant: ProductVariant, cart: Cart) => {
  if (cart)
    return formatVariantPrice({
      variant: variant,
      region: cart.region,
    });
};

You use the formatVariantPrice function here from medusa-react. This formats the price according to your user’s region and the product variant selected.

Then, use it in app/routes/products/$slug.tsx:

import { formatPrice } from '~/lib/formatPrice';

export default ProductSlug() {
    ...

    const { cart } = useCart();

    return (
        <div className="flex flex-col items-center lg:justify-between lg:flex-row px-10 pb-44 sm:px-20 md:px-44 pt-44 max-w-[100rem] flex-grow w-screen">
      <img src={product.thumbnail!} className="h-96 w-auto" />
      <div>
        <h1 className="text-4xl pt-5 lg:pt-0 pb-5 lg:pb-10 text-white">
          {product.title}
        </h1>
        <p className="w-72">{product.description}</p>
        <p className="text-xl text-white pt-5">
          {formatPrice(product.variants[0], cart)}
        </p>
      </div>
    </div>
    )
}

Next, create a function to add to the cart and push notifications.

import toast from 'react-hot-toast';

export default function ProductSlug() {
    ... 

  const { mutate } = useCreateLineItem(cart?.id!);

  const addItem = () => {
    mutate(
      {
        variant_id: products?.slice(0, 1)[0].variants[0].id!,
        quantity: 1,
      },
      {
        onSuccess: () => {
          toast('Added to Cart!');
        },
      }
    );
  };

    ...
}

The useCreateLineItem hook lets you add items. It requires a cart ID. The addItem function will add the product to the cart and then show a toast notification.

Add the button that will run this function on click in the returned JSX:

export default function ProductSlug() {
  ...

  return (
    <div className="flex flex-col items-center lg:justify-between lg:flex-row px-10 sm:px-20 md:px-44 pt-44 max-w-[100rem] flex-grow w-screen">
      <img src={product.thumbnail!} className="h-96 w-auto" />
      <div>
        <h1 className="text-4xl pb-10 text-white">{product.title}</h1>
        <p className="w-72">{product.description}</p>
                <p className="text-xl text-white pt-5">
          {formatPrice(product.variants[0])}
        </p>
        <button
          className="p-5 rounded-md w-full bg-slate-400 bg-opacity-25 mt-10 cursor-pointer active:scale-95 transition ease-in-out duration-75"
          onClick={() => addItem()}
        >
          Add item
        </button>
      </div>
    </div>
  );
}

The last step is to add a navigation bar to make it easy to navigate to the cart.

Create the file app/components/topNavigator.tsx with the following content:

import { Link } from '@remix-run/react';

export default function TopNavigator() {
  return (
    <nav className="flex w-screen fixed top-0 right-0 left-0 items-center py-4 flex-row justify-between px-10 sm:px-20 md:px-44 z-10 bg-black">
      <Link to="/" className="text-xl">
        MRS
      </Link>
      <Link to="/cart">Cart</Link>
    </nav>
  );
}

Add the TopNavigator component to your root.tsx so it appears on all pages. Add it just above the Outlet:

import TopNavigator from './components/topNavigator';

export default function App() {
  return (
    ...
        <CartProvider>
          <OutletContainer>
                    <TopNavigator />
            <Outlet />
        </OutletContainer>
        ...
      </CartProvider>
      ...
  );
}

Test Product Page

To test out your product page, restart your Remix server (make sure Strapi and Medusa servers are already running).

Click on any of the products on your homepage and you will be able to see the details.

Create Cart Page

Now, you will create your very final cart page.

Create the file app/routes/cart.tsx with the following content:

import { useState, useEffect } from "react";
import { medusaClient } from "~/lib/config";

import type { Cart as CartType } from "medusa-react/dist/types";

export default function Cart() {
  const [cart, setCart] = useState<CartType>();

  useEffect(() => {
    medusaClient.carts
      .retrieve(localStorage.getItem("cart_id")!)
      .then(({ cart }) => {
        setCart(cart);
      });
  }, [cart]);

  return (
    <div className="px-10 sm:px-20 md:px-44 pt-44 max-w-[100rem] flex-grow w-screen">
      {cart?.items.map((variant) => (
        <div
          key={variant.id}
          className="flex flex-col xl:flex-row h-64 my-10 space-x-8 space-y-4 items-center"
        >
          <img className="h-full" src={variant.thumbnail!} />
          <div>
            <h3 className="pt-2 text-white text-xl">{variant.title}</h3>
            <p className="text-slate-400">{variant.quantity}</p>
          </div>
        </div>
      ))}
    </div>
  );
}

cart.items is an array of all the items in the customer’s cart. You display each item with its thumbnail, title, and quantity.

Test Cart Page

Restart your Remix server (make sure Strapi and Medusa servers are already running). When you add an item to the cart it will show on the cart page.

Conclusion

By following along with this tutorial, you can see how easy it is to use fully open source tools to build an ecommerce store.

There’s still much more that can be done to improve your storefront such as:

Improve the UI
Improve Cart page to add functionalities such as removing or updating items.
Implement Checkout Flow
Integrate Stripe Plugin for payment.
Install Medusa Admin to manage orders, products, and much more.
Check out Medusa’s Storefront API Reference to learn what more you can do in your storefront.

Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.

How tough is Freelancing?

Avi Avinav — Sun, 25 Sep 2022 14:21:00 +0000

I have decided to start freelancing for a little income in college, but before starting out I would like to know how tough it is to get a gig, how to negotiate pay, whether I should try to get paid hourly or per project, and what are some difficulties you have faced. Also, if you have any tips please let me know.

Tell me about some underrated OSS projects

Avi Avinav — Tue, 20 Sep 2022 14:43:16 +0000

So, recently I have been exploring more OSS projects to check out. I want to know about some more OSS projects that are in the early stages or are quite underrated. You can also share your own projects, bias is allowed.

The Making of A React Component Library

Avi Avinav — Sun, 11 Sep 2022 12:09:24 +0000

A component library is one of the coolest things a web developer can make, but if you don't know how to make one, let me guide you a bit.

Before we begin I would like to tell you, that I am not a pro at making component libraries, it's just from my experience developing a component library before.

Prerequisites

Before you get started, these are the following you should know:

Basics of React
Typescript (Optional but preferred, you can use Javascript too)

Why make a component library?

A react component library can be useful in many ways, you can use it in your projects as you scale and want uniformity or you can make your library open-source for everyone to use and contribute.

Tools Required

React - since, this is a tutorial about a react component library
Typescript - this is optional but recommended
Storybook - it's fine if you haven't heard of it, don't freak out. We will be using this to preview our components

Getting Started

There are a lot of ways we can set up our library, if you want to make several packages in the same organization I would recommend using a monorepo but for the sake of this tutorial we will be setting up a very simple library from scratch.

So, first of all, go ahead and make a package.json file:

npm init

Once, you have initialized the project, we will start installing our dependencies. Unlike, in a normal project where you would just install the dependencies directly with npm i [dep-name], here we will be using dev-dependencies and peer-dependencies.

Dev-dependencies are the dependencies that do not get packaged in the bundle and do not contribute to the size of our library, it is a dependency that you only require during development.

Peer dependencies basically tell you that you need to have a certain package installed to use the library, for example, if I have a library named avi-lib and it has peer dependencies as react & react-dom, then if I want to use avi-lib in my project I need to have react & react-dom already installed as dependencies in the project.

Now go ahead and install react , react-dom, tyepscript, & @types/react, @types/react-dom as devDependencies.

yarn i -D react react-dom typescript @types/react @types/react-dom

Add react & react-dom as peer-dependencies with appropriate versions:

{
    ...
    peerDependencies: {
        "react": ">=16.0.0",
        "react-dom": ">=16.0.0"
    }
    ...
}

Next, initialize a tsconfig file:

npx tsc --init

In the tsconfig.json file, go ahead and enable jsx with "jsx": "react" option.

Making the Component

Once this is done make a directory src or whatever you wish to name it. This directory will contain all code.

Inside src, make another directory components and create a file Button.tsx. Now, open the file and write out a simple button:

import React from 'react';

export interface ButtonProps {
  children: React.ReactNode;
  onClick: () => void;
}

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

Now inside the src directory, create a index.ts file, and write out the following:

export { Button, ButtonProps } from "./components/Button"

Storybook

Storybook is an amazing tool that is almost essential for component libraries, it helps you out with previewing your components adding documentation for them, and even lets you host the components for others to test. For the sake of this article, we will be primarily using it for testing our components.

To setup storybook in your library, run the following:

npx storybook --init

Storybook automatically detects that this is a react library and installs it accordingly. After it has done installing you will see a .storybook directory and a src/stories directory. You don't really have to do anything with the .storybook directory, you will use your components in the src/stories directory.

Inside the src/stories directory you will see a bunch of stuff, but don't worry about it, it is all just mock data. You can go ahead and empty it leaving only the Button.stories.tsx. Now you will see a lot of things in this file go ahead and empty it and type in the following:

import React, { useState } from 'react';
import { storiesOf } from '@storybook/react';

import { Button } from '../';

const stories = storiesOf('Button', module);

stories.add('Button', () => {
  const [value, setValue] = useState('Hello');
  const setChange = () => {
    setValue(value === 'Hello' ? 'Bye' : 'Hello');
  };

  return <Button onClick={setChange}>{value}</Button>;
});

Now go ahead and check it out, run the following in your terminal:

npm run storybook

This will open a browser window on localhost:6006, and you can see our little button working, its value changes on being clicked.

That's about it, now go ahead and add your own magic to the button, make more components, and similarly, you can even create hooks.

Documentation

It is a good idea to document things about your components in your library in a README file or on a docs website, it helps out anyone using your library. For the sake of this tutorial, we will not be writing documentation because it only contains a single button component.

Bundling

Once you are done with making your components, let's bundle our library.

It's a good idea to bundle because it helps you produce a single file. Some people prefer dragging and dropping a single file in their projects. A single file can also be used for CDNs.

To bundle your component you will have to use a bundler. There are a lot of options out there but here we will be using tsup because tsup doesn't require a configuration for our use case.

To install tsup, do the following:

yarn add -D tsup

This installs tsup as a dev-dependency, now inside your package.json file add a script:

{
    ...
    scripts: {
        ...
        "build": "tsup src/index.ts --dts"
    }
    ...
}

Now, go ahead and run yarn build, this will create a index.js file inside the dist directory. If you observe, we added a --dts in our build script, this will generate the type definitions for our project in index.d.ts.

Publishing

Now that all is done, it's time to show what you have built to the world (or not if it's for personal use). Before publishing, go to your package.json and you will find a few things, choose a name for your library and add an appropriate version (you can use semantic versioning if you don't know how to), a description of what it does, and a few keywords to make your library discoverable.

Now add a .npmignore file, this is very similar to .gitignore, this file will contain what you don't want to publish along with your library, for example, node_modules. Though this file is optional even if you don't include it, the .gitignore file will be used instead.

If you are not logged in to your npm account do npm login and you will have to enter your username and password. In the case, you don't have an npm account you can go to https://www.npmjs.com/ and register for one.

Once you have done that just simply run this command in the terminal:

npm publish

Once it finishes without any errors, Congrats! Your library has been published. Now you (and others too) can use your library in your projects.

Tips

Try to use typescript
Add documentation in your README & if you want, a docs website
I have not done it in the article but use git and make changes on a different branch than main
Read more on Storybook, its templates, and documentation

More Resources

Turborepo - in case you wish to create a monorepo, you can also use lerna instead of turborepo.
Storybook Documentation

Hope you enjoyed the read and learned something from it. In the case, you want to add something or find a mistake and wish to point it out, please feel free to do so in the comments.

A Guide to Overengineering a Windows Terminal

Avi Avinav — Sat, 04 Jun 2022 08:13:28 +0000

For decades, Windows users have been made fun of by the Linux community for the lack of a cool terminal (among other things). Well, it's about time we fight!

In this article, we will go through setting up a development workflow in the Windows terminal.

Prerequisites

Know how to type
Windows 10/11 (Some things may not work for you in this article if you are on some other version)
(Optional) Know Basic Unix Commands such as cd, mkdir, etc

What will we be doing

We will set up the following:

Powershell
Nerd Fonts
Theme
Scoop
z Directory Jumper
Terminal Icons
Node & Git
Neovim
Oh-My-Posh
Autocomplete
Aliases
Utilities

Well, then, let's get started!

Things to remember during the article

~ stands for your root or home directory, the default directory where the terminal will generally open.
If anything doesn't work even after installing/configuring just close and reopen the terminal.
The command pallete opens with ctrl+shift+p.
Terminal settings open with ctrl+,

Getting Started

Powershell

First of all, let's install Powershell, this is not Windows Powershell that comes with Windows. You will have to go to the Microsoft Store and search for it, it's free so don't worry.

After you have done that open Terminal (not PowerShell or Command Prompt), you can search it up, it's pre-installed on your PC.

Press Ctrl+, to open settings, here we will set Powershell as our default, it would be Command Prompt in default if you haven’t changed it before.

In the startup menu, change the default profile to PowerShell and save, that's it!

Nerd Fonts

So, what are Nerd Fonts? Nerd fonts let you use font ligatures and more glyphs in general, it's something everyone should use while coding. You might actually be using it without knowing in your IDE/text editor. I used Fira Code for a long time before knowing it was a Nerd Font.

To install a nerd font, first, go to the nerd-fonts GitHub Repo and download the zip file of your preferred Nerd Font from the latest release. Extract the zip file and install the fonts. If you have never installed a font before, that’s fine, you can just double-click the .ttf files and click on install.

I use the JetBrains Mono NF and another of my favorites is Hack NF (NF stands for Nerd Fonts).

Themes

To change the theme of your terminal, open settings and click on "Open JSON file", this will open the settings.json file for your terminal.

Now to change the theme you have three options:

Choose a theme from the themes already present in the terminal by default
Create your own theme from scratch or modify one already present.
Use a pre-written theme

I use a pre-written theme, you can find a lot of them here and paste it into your settings.json under “schemes”. Save the file.

Now, go back to your Terminal settings (not settings.json) and choose the theme you just added.

Terminal Tools

Scoop

Let's first install scoop, a package manager for Windows. We will be then using scoop to install other tools.

To install scoop run the following in PowerShell:

winget install scoop

This will install scoop. If you are wondering what winget is, it is a package manager that comes by default in Windows 10/11.

In case, you don't have winget do the following:

iwr -useb get.scoop.sh | iex

Now type scoop and if it returns an output like the below then all is good.

Usage: scoop <command> [<args>]

Some useful commands are:

alias       Manage scoop aliases
bucket      Manage Scoop buckets
cache       Show or clear the download cache
cat         Show content of specified manifest. If available, `bat` will be used to
            pretty-print the JSON.
checkup     Check for potential problems
cleanup     Cleanup apps by removing old versions
config      Get or set configuration values
create      Create a custom app manifest
depends     List dependencies for an app
download    Download apps in the cache folder and verify hashes
export      Exports (an importable) list of installed apps
help        Show help for a command
hold        Hold an app to disable updates
home        Opens the app homepage
info        Display information about an app
install     Install apps
list        List installed apps
prefix      Returns the path to the specified app
reset       Reset an app to resolve conflicts
search      Search available apps
shim        Manipulate Scoop shims
status      Show status and check for new app versions
unhold      Unhold an app to enable updates
uninstall   Uninstall an app
update      Update apps, or Scoop itself
virustotal  Look for app's hash on virustotal.com
which       Locate a shim/executable (similar to 'which' on Linux)

Type 'scoop help <command>' to get help for a specific command.

If it doesn't return an output, just close and reopen the terminal, and it will work.

This is the moment you stop using those installers, now you are a terminal guy. You can even install Mozilla Firefox, just do scoop install firefox.

There is also choco/chocolatey which you can use as a package manager but we will stick with scoop for this article.

z

z is a directory jumper. What is a directory jumper? Let's say you are in the directory ~/Desktop/Development/NextJS/tutorial, and you want to go to ~/SomewhereElse/Products/Product1/prod-website, the one way of doing this in your terminal would be this:

cd ../../../../

cd SomewhereElse/Products/Product1/prod-website

This looks small but you don't always remember where all your projects are so add 4-5 more commands in there. This wastes our time, especially over a prolonged period. This is where a directory jumper comes in, with just a single command you can go from one project to another.

Let's take the above example this time you just have to do this (assume you are in ~/Desktop/Development/NextJS/tutorial):

z prod-website

That's it! You just should have visited the directory once in your lifetime (which you most probably will during the project setup). You don't even need to use the full name of your project directory, you can just do z prod and you would jump to the most recent directory which has prod in its name somewhere (in this case, the prod-website).

One thing to note is, to try not to include spaces in your directory names that may make it hard for the directory jumper to find them. It's a good practice in general too to not include spaces in directory names.

Now to install z, just type in the following and hit enter and there you go:

Install-Module -Name z -Force

Huh? This is not scoop, is it? Yes, it is not, we are currently installing a PowerShell Module (you can install some modules using scoop or winget too) and thus, we are using the Install-Module command that is builtin into PowerShell.

Try it out, if it doesn't work open a new Terminal tab (shortcut: ctrl+shift+t), and it should work now.

Terminal Icons

As the name suggests it adds icons for when you do ls. To install it do the following:

Install-Module -Name Terminal-Icons

This will install the module. To be able to use it globally, we need to add it to our powershell profile, which we will cover in this article later.

Node & Git

If you use Node.js install it but if you don’t there is no need to.

To install Node, first install nvm which stands for Node Version Manager, it also lets you have multiple versions of node installed at the same time.

scoop install nvm

This will install nvm.

Now download the stable release of Node.js with:

nvm install lts

for the latest release do:

nvm install latest

you can even specify a certain version like this:

nvm install 18.1.0

To list out the versions of node available use nvm list, the one with a * denotes the one being used currently. To change the version do nvm use version_number.

Quick Tip: You can also install sudo by doing scoop install sudo, by using that you don’t have to close and reopen the terminal for admin commands. You can use it like, sudo nvm use 18.1.0.

Now for git just do either of the following:

using scoop:

scoop install git

using winget

winget install git

That's it!

Neovim

Neovim is a fork of Vim that is better for plugins and extensions.

To install Neovim, type in the following and hit the enter key:

scoop install neovim

Also, install any other packages it asks you to. I don't recommend jumping into Neovim right ahead if you haven't seen it ever before in your life or don't know the common commands/keybindings. You can check out this article of mine for learning a bit about it and how to set it up.

I will be using Neovim here for editing files, but it's alright you can just follow along with the steps in your preferred text editor or IDE too.

Oh-My-Posh

Now that all your terminal tools are all set up, let's start with customizing your prompt.

First of all, to install it you can do either of the following:

winget install oh-my-posh

scoop install https://github.com/JanDeDobbeleer/oh-my-posh/releases/latest/download/oh-my-posh.json

Now, we will start messing with config files!

First, let's create a config file for our PowerShell, we will be using this file to customize our prompt as well as to set aliases and utilities. The config file will be in PowerShell script.

You can create it anywhere but you will have to link it accordingly in your PowerShell profile. PowerShell profile is from where PowerShell will load its config, you can write your config there directly but we will write it in a separate file.

Let's make ours in ~/.config/powershell.

cd .config

mkdir powershell && cd powershell

Again, you can name your file anything just make sure it will be the same in your PowerShell profile.

Let's get started with the editing then, create a file user_profile.ps1 in your preferred editor, I will be using Neovim here.

nvim user_profile.ps1

Now type in the following into your powershell config:

oh-my-posh init pwsh --config ~/.config/powershell/avi.omp.json | Invoke-Expression

Save it now. In here you can see "avi.omp.json" and you can name it anything like "your_name.omp.json" just make sure to replace it in the config. Now, you may ask me though, what even is that file? That file is the one that will contain our oh-my-posh configuration for the prompt.

You can create your own custom prompt from scratch by looking at the docs, but there are a lot of awesome ones already there. I use one of them and just modified it a bit. You can check it out on their website and copy the config. Here's the one I am using:

{
  "$schema": "https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes
/schema.json",
  "blocks": [
    {
      "alignment": "left",
      "segments": [
        {
          "foreground": "#41A6B5",
          "style": "plain",
          "template": "@avi",
          "type": "session"
        },
        {
          "foreground": "#7AA2F7",
          "properties": {
            "folder_separator_icon": "/",
            "style": "full"
          },
          "style": "plain",
          "template": " \uf07b {{ .Path }} ",
          "type": "path"
        },
        {
          "foreground": "#BB9AF7",
          "powerline_symbol": "\ue0b0",
          "properties": {
            "fetch_stash_count": true,
            "fetch_upstream_icon": true
          },
          "style": "plain",
          "template": "{{ .UpstreamIcon }}{{ .HEAD }}{{ if gt .StashCount 0 }} \uf692
{{ .StashCount }}{{ end }} ",
          "type": "git"
        }
      ],
      "type": "prompt"
    },
    {
      "alignment": "left",
      "newline": true,
      "segments": [
        {
          "foreground": "#cd5e42",
          "style": "plain",
          "template": "\ue3bf ",
          "type": "root"
        },
        {
          "foreground": "#CD4277",
          "style": "plain",
          "template": "> ",
          "type": "text"
        }
      ],
      "type": "prompt"
    }
  ],
  "version": 2
}

Next, open your powershell profile (you can do it by nvim $profile, do it from the home directory if you are not on Neovim, the file is located at ~/My Documents/powershell/Microsoft.PowerShell_profile.ps1), and type in the following:

. $env:USERPROFILE\.config\powershell\user_profile.ps1

Save that. Close and reopen the terminal. Your prompt should load now.

Awesome! Now, let's add autocomplete.

Autocomplete

PSReadline is a module of PowerShell that comes pre-installed which will help us out with the autocomplete.

To configure it open your user_profile.ps1 and add the following:

Set-PSReadLineOption -PredictionSource History

Set-PSReadLineOption -PredictionViewStyle ListView

You can choose "HistoryAndPlugin" or "Plugin" too as PredictionSource. For PredictionViewStyle, the other option is InlineView, you can also switch between them by pressing the F2 key.

I talked about adding Terminal Icons to the config before, you can do it by just adding the following line into your config:

Import-Module Terminal-Icons

Aliases

Aliases can be useful in saving time.

It's quite simple to set aliases, for example:

Set-Alias g git

The above will set the alias for git as g, but that will only make it the alias for this particular terminal session/tab not globally. To make it a global alias add the exact same command as above in your powershell config file. Now, g is the alias for git. Similarly, you can set other aliases. Here are a few of mine:

Set-Alias v nvim
Set-Alias g git
Set-Alias y yarn
Set-Alias p pnpm
Set-Alias tig 'C:\Program Files\Git\usr\bin\tig.exe'
Set-Alias explorer explorer.exe

These are PowerShell aliases, you can also setup aliases for git to speed up your development process, I won't go into the detail of it here.

There is another way to set aliases for commands like npm start, yarn dev. Here is an example of making alias yd for yarn dev:

function yarnDev {
  yarn dev
}

New-Alias yd yarnDev

I don’t have experience with PowerShell script, so in the above, I can only explain that we create a function yarnDev and add whatever we want to run when we call the function. After that, we set the alias to call the function as yd.

Similarly, you can setup other aliases for such commands.

Utilities

You can even make your own little commands by setting them in your PowerShell config. For example, touch command (used to create a file) which is not present in PowerShell, here is how you can add it:

function touch ($command) {
    New-Item -Path $command -ItemType File | out-null && Write-Host Created $command
}

What we are doing above is creating a function touch and letting it have a parameter. Then, in New-Item -Path $command -ItemType File, we are using built-in PowerShell commands to create a file, you will have to research PowerShell commands to create more utilities on your own, the documentation is amazing, so it won’t be a problem. In the second half of the function, we are just telling it to output Created [file_name].

Here is how you can add rm command from Linux:

function rm ($command) {
    Remove-Item $command -Recurse && Write-Host Removed $command
}

To use this just do rm [file_name/directory_name] and it will delete the file.

It is not exactly the same as the rm command in Linux though.

Other tools

Here are some of the other CLI tools you can use:

Commitizen - Commitizen is used for defining a standard way of committing rules and communicating them in Git. It is designed for teams, but I also use it for my personal projects.
gh CLI - gh is GitHub on the command line. It brings pull requests, issues, and other GitHub concepts to the terminal next to where you are already working with git and your code.
gh-dash extension - An extension of gh cli to display a dashboard with pull requests and issues.
dunk - You can use this to get prettier git diffs.
Rich CLI - Rich-cli is a command-line toolbox for fancy output in the terminal.

WSL Setup

Now, you might have already heard of WSL or might even be using it, nothing wrong with it if you are not. WSL stands for Windows Subsystem For Linux, it lets you have the Linux terminal on your windows machine.

I will not be discussing WSL setup here but you can check out "The Complete Windows Developer Setup Guide" by @stephanlamoureux, it goes through setting up WSL quite nicely.

Conclusion

So, that's finished! You can find my config files here on GitHub if you want, before copying anything go through the readme once, also do not copy anything you don’t know the meaning of.

If anyone wants to add something, correct me somewhere, or ask anything please feel free to do so in the comments.

Resources

for themes - https://windowsterminalthemes.dev/ or https://github.com/atomcorp/themes
docs for PSReadline - https://docs.microsoft.com/en-us/powershell/module/psreadline/?view=powershell-7.2
video by devsalife on setting up powershell - https://www.youtube.com/watch?v=5-aK2_WwrmM
Documentation for all other tools has been linked with their introductions in the article

Vim: A Beginner's Guide From A Beginner

Avi Avinav — Sat, 28 May 2022 05:28:58 +0000

Vim, one of the oldest contestants in the text editor war, ever since its release in 1991. It has been a friend to many and a foe to many, wanna find out what it will be for you? Then, let's try it out!

I have been using Vim for about a month and a half now, and I have been loving it (the first week was a bit painful though).

In this article, I'll be discussing why to use Vim, how to set it up, and some basics of Vim.

Why To Use Vim?

Now, don't fight with me, I am not comparing Vim with any other text editor. I am just telling you what Vim has to offer.

Fully customizable - It means you have full control, some people even make it look like vscode (I personally like to keep it minimal though)
Productivity - Well, in the beginning, your productivity would decline but as you start getting used to Vim and its keybindings, it will increase for sure
Keyboard-driven (you can use a mouse though if you set the preference) - This may or may not be a good thing for you
Looks cool

Neovim

Don't freak out if you haven't heard of Neovim, it's nothing scary. Neovim is just an implementation of Vim but more focused on extensions and plugins, a bit less customizable than Vim. Often people don't say they use Neovim, they just call it Vim. It really doesn't make much of a difference, just that Neovim has more support for plugins. Also, the default keybindings and commands for both are the same, so, if you learn Neovim keybindings you can as well use Vim.

Installation

Mac & Linux

For Mac & Linux machines, do either of the following depending on your package manager:

sudo apt install neovim

brew install neovim

Vim (not Neovim) is installed by default on most Linux machines. You can run it by typing vi or vim.

Just in case, you opened it right now without knowing the keybindings and are now freaking out, just type :q! and press enter to exit.

Windows

For windows users, you have two options:

You can use wsl (Windows subsystem for Linux) and follow the same steps as for Linux systems. I won't go into details about installing wsl here.
Use Powershell (not Windows Powershell), you can download it from the Microsoft store, and install Neovim using scoop (A package manager for windows):

To install scoop, type the following into your terminal:

winget install scoop

winget is another package manager that comes pre-installed in windows nowadays.

scoop install neovim

If it tells you to install additional buckets, do it too.

Close and reopen your terminal and you can open Neovim by typing nvim.

Just in case, you opened it right now without knowing the keybindings and are now freaking out, just type :q! and press enter to exit.

First Look

This is how it looks right now:

Right now that doesn't look very good, does it?

Let's configure it!

Configuration

Now, there are many good pre-configured neovim setups out there like NvChad and AstroNvim, but I advise you to first at least try out your own configuration. I personally don't use the pre-configured ones, I prefer to use my own configuration.

You will have to create a configuration file for neovim first.

For Linux & Mac Users, the config file should be created at ~/.config/nvim.

For Windows Users, the config file should be created at ~/AppData/Local/nvim.

(In the above ~ represents the home directory)

Open your terminal in your respective directories. Create the file, its name shall be init.vim. In this file, we will be using vimscript to write our configuration.

Quick note: You can also use init.lua instead of init.vim, more about that towards the end, in this article I will be following with init.vim.

Now, we are going to configure Neovim using Neovim (sounded pretty weird to me the first time).

Basic Rules

Go to the directory mentioned above inside your terminal, and type nvim init.vim and press enter.

Quick note: If you just type nvim without mentioning any file, it will open up something like a welcome page. If you type nvim file.md and file.md does not already exist, Neovim will open it and if you save it the file will be created. Same rules apply to Vim too.

Now, no need to click anything, forget you have a mouse, once that intimidating text editor is open in front of you, just press i (no shift key, no ctrl key, just plain simple little i), this lets you enter insert mode. Now, you can edit your file normally. To exit insert mode or rather any mode in Vim in general, press the escape or esc key, this doesn't exit the editor just returns you to normal mode (the default mode).

You can also use arrow keys to navigate the file for now.

Quick Note: when in normal mode, to move left press 'h', to move right press 'l', to move up press 'k', and to move down press 'j'.

Before jumping on to plugins let's set up some basic rules/settings:

set number                 " Sets line numbers
set autoindent             " Sets auto indentation
set tabstop=2              " Sets tabstop
set shiftwidth=2           " For proper indentation
set smarttab               " Affects how tab key presses are interpreted
set softtabstop=2          " Control how many columns Vim uses when you hit tab key
set mouse=a                " This lets you use your mouse
set wrap                   " Sets up line wrapping

Quick tip: If you don't understand what a certain setting does, just open Vim and in normal mode type, :help <property_name>, for example for shiftwidth, do :help shiftwidth.

Next, press esc key to exit insert mode. Now type :wq (no need for clicking anywhere or pressing all those ctrl & shift keys) and press enter, this will write to file (basically, it will save the file) and then exits the editor.

If you use just type :w, it just writes to the file, it doesn't exit the editor.

If you use just type :q, it exits the editor, but it won't let you do that if you have unsaved changes, in that case, do :q!, this will revert all unsaved changes and exit the editor forcefully.

If you want a property I haven't mentioned here, just search it up, I am sure you will find it.

Let's set up the plugins now!

Setting Up Plugins

Now, there are a bunch of plugin managers (Vim/Neovim requires plugin managers to install plugins) out there but for this tutorial, we will stick with vim-plug.

For Unix/Linux, you can install vim-plug with:

sh -c 'curl -fLo "${XDG_DATA_HOME:-$HOME/.local/share}"/nvim/site/autoload/plug.vim --create-dirs \
       https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'

For Windows(Powershell), you can install vim-plug with:

iwr -useb https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim |`
    ni "$(@($env:XDG_DATA_HOME, $env:LOCALAPPDATA)[$null -eq $env:XDG_DATA_HOME])/nvim-data/site/autoload/plug.vim" -Force

Check out their install instructions for more.

Now open init.vim in neovim again, and navigate to the end of the file, you can also use arrow keys, don't press i this time, press o, this will make a new line and enter you to insert mode. Now type in the following (after the basic rules):

call plug#begin()

" Your plugins go here

call plug#end()

Quick note: You can use " to write single-line comments in vimscript. For example " This is a comment.

All our plugins will go in between the call plug#begin and call plug#end.

Here are some of the plugins I use:

coc.nvim - I will elaborate a bit more on this later
presence.nvim - a plugin to let you show that you are using Vim on Discord
lightline.vim - a light and configurable statusline/tabline plugin for Vim
nerdtree - a tree explorer plugin for vim, more about this later
nerdtree-git-plugin - a plugin to show git status in nerdtree
vim-devicons - a plugin to show icons for your files
auto-pairs - completes your parentheses, brackets and quotes
copilot.vim - If you have GitHub Copilot, then you can use it with this plugin

You can list your plugins like this:

call plug#begin

Plug 'neoclide/coc.nvim', {'branch': 'release'}
Plug 'andweeb/presence.nvim'
Plug 'itchyny/lightline.vim'
Plug 'ryanoasis/vim-devicons'
Plug 'preservim/nerdtree' |
           \ Plug 'Xuyuanp/nerdtree-git-plugin'
Plug 'jiangmiao/auto-pairs'
Plug 'copilot.vim'

call plug#end

Quick note: Always remember, before you install a plugin, do check out its docs before installing, because sometimes they may have special instructions on the setup for a plugin

Once it's done, save the file and exit Neovim (remember, use :wq and press enter). Reopen Neovim. To install these plugins, type :PlugInstall in normal mode and press enter. This will open another pane and start installing all the plugins, once it's done. Close the pane (:q), then close init.vim too. This exits Neovim, now, re-enter and all the plugins will start to work.

Quick Tip: to move between panes, press ctrl+w, and then h to move to the left pane and l to move to the right pane

Coc.nvim & LSP

What is LSP?

Well, LSP (Language Service Provider) is the thing that gives you language support (language support in an editor means it points out your mistakes and offers suggestions while coding for a specific language). It is also built-in neovim since version 0.5. We won't be configuring the native LSP here, instead we will use coc.nvim.

What is Coc.nvim?

Coc.nvim is an ecosystem that builds beyond the native LSP, meaning you don't have to configure anything. It brings autocomplete, suggestions, and some other stuff. It's recommended for beginners as there is not much setup. We already installed coc.nvim earlier as a plugin.

Well, with that out of the way, we can install the support of coc for our used languages. For example, if you want to install the support for python, just do :CocInstall coc-python. Most languages will have their support as coc-[language-name] but just to be sure you should just google it, you will easily find it.

Keybindings

Now, take a moment and feel proud, you have conquered a bit of the fear of vim.

In vim/neovim, you can set up your own keybindings apart from the ones already there.

For example, let's say I want to set up a keybinding for closing a file in Neovim. So, in general, I would have to type :q.

To do that at the end of your init.vim file (after the call plug#end) add the following:

nnoremap <C-q> :q<CR>

What does this mean?

nnoremap is a declaration that you are setting a keybinding, so you will have to put that before declaring any keybindings.

Here, in <C-q>, the "C-" stands for the ctrl key, followed by whatever key you want to use in combination with it. For example, <C-q> means ctrl+q and <C-k> means ctrl+k.

In between, <C-q> & <CR> is the command for which this keymapping is.

<CR> represents the enter key. So, nnoremap <C-q> :q<CR> means you have to press ctrl+q and it will be the same as typing :q and then pressing enter.

Since, we installed plugins, like nerdtree, they brought their own commands for us, for example now you have access to :NERDTreeToggle and :CocInstall.

So here are some keybindings you can setup for nerdtree:

nnoremap <leader>n :NERDTreeFocus<CR>
nnoremap <C-n> :NERDTree<CR>
nnoremap <C-t> :NERDTreeToggle<CR>
nnoremap <C-f> :NERDTreeFind<CR>

This keybinding is from their readme on their GitHub repo, but you are free to change it, you can make to if you prefer, whatever suits you. Just keep in my mind, not to have conflicting keybindings.

You must be wondering though, what is that <leader> over there. That stands for \, so nnoremap <leader>n :NERDTreeFocus<CR> is means you have to type \n and it will run :NERDTreeFocus command.

NERDTree

After setting up the keybindings for nerdtree, you can press, ctrl+t to open it up, you can navigate it just like you would a file with arrow key or [h, j, k, l] keys. To delete or rename a file, press m, and it will open up a menu listing out how to do it. To create a file, navigate to the node you want it to be in, and then press m to open up the menu.

That about wraps it up.

Themes

You can install Themes the same way you did with plugins. You can search about the themes, there are many out there. I personally don't use any theme because my terminal's theme is good enough for me.

Don't worry, I have listed some resources for you to find a good theme at the end of this article.

Lua & Vimscript

Earlier, I stated that you could have put your config in init.lua too. Many people prefer to use Lua because it's more logical than Vimscript.

If you wish to convert your init.vim to init.lua, you can check out this article by Olivier Roques.

Final look

If you have followed everything in this article, your init.vim should look something like this now:

" Basic Rules

set number
set autoindent
set tabstop=2
set shiftwidth=2
set smarttab
set softtabstop=2
set mouse=a
set encoding=UTF-8
set wrap


" Plugins

call plug#begin

Plug 'neoclide/coc.nvim', {'branch': 'release'}
Plug 'andweeb/presence.nvim'
Plug 'itchyny/lightline.vim'
Plug 'ryanoasis/vim-devicons'
Plug 'preservim/nerdtree' |
           \ Plug 'Xuyuanp/nerdtree-git-plugin'
Plug 'jiangmiao/auto-pairs'
Plug 'copilot.vim'

call plug#end


" Keymaps

nnoremap <leader>n :NERDTreeFocus<CR>
nnoremap <C-n> :NERDTree<CR>
nnoremap <C-t> :NERDTreeToggle<CR>
nnoremap <C-f> :NERDTreeFind<CR>

This is how it looks now:

Take a deep breath, and feel a sense of accomplishment, you are done. Now, go ahead experiment with it and make Vim you own.

Common Commands in Vim

:w - Save file
:q - Close file
:q! - Force close file and revert unsaved changes
:wq - Save and close file
esc key - Go back from any mode to normal mode
i - Enter insert mode
o - Next line and insert mode
s - delete character and insert
dd - delete line

Here is a vim cheat sheet from devhints. You can check it out for more commands.

Some Tips

Do not give up on Vim, at least try it for a week or two before deciding to throw it away. I know it's pretty annoying at first but a lot of people end up loving it after using.
Do not close Vim, don't exit the terminal without quitting Vim, can corrupt files sometimes
Do not use ctrl+z, freezes my Vim for some reason
You can use shell commands by prefixing things with !
Windows may not have some features that Linux will offer but you can install wsl.
Increase your typing speed, it will help you out in general too.
Use aliases for speeding up your development process.
Practice. That's the best way to get used to Vim.

Some Useful Tools

Use a directory jumper, so you don't have to keep cding all the time. I use z
You can use a terminal multiplexer for Linux and Mac devices. tmux is a famous one and the only one I know. Never heard of terminal multiplexers on Powershell though

More Resources

awesome-neovim - A collection of wonderful neovim plugins & themes for you to try
r/vim - A wonderful community if you have any questions regarding Vim
r/neovim - Similar to r/vim
neovim docs - The official documentation for Neovim
vim docs - The documentation for Vim
nerd fonts - It lets you have more glyphs and font ligatures

If someone wants to point out something that I missed or any other resource or just has doubts about something I wasn't able to explain properly, please comment it down below.

Hope you liked it!

An explanation of Git for beginners

Avi Avinav — Fri, 20 May 2022 19:07:02 +0000

Git is an essential tool for version control, no matter what programming language or framework you use. That's a pretty okay explanation but when I first heard about Git, I didn't understand what that meant, might be the case for you too.

An analogy

Now, let's say there was a man, Lorem Ipsum, who was living a pretty good life, he had a loving dog, a good job, and a nice house; but then he messed up a lot of things, his dog ran away, he lost his job and now he is on drugs wishing every day that he could go back in time and fix his mistakes, but that is only a wishful fantasy, he doesn't have a time machine.

Don't worry though, you don't have to end up like Lorem, because you've got Git, your time machine. Of course, it cannot fix all your mistakes in life but it can let you return to a certain checkpoint in the timeline of your project.

Let's say, I wasn't using Git. I started building a web app, and everything's going well, but then I try to center a div and it's all messed up. I keep trying to fix it but I can't. Finally, I deleted the project and start it again from scratch, and the same story repeats. I abandon the project and question my life choices, then cry myself to sleep. Based on a true story.

But then I started using Git, so whenever I add a new feature I set a checkpoint by making a commit and adding a comment about the change for future reference. So, even if I mess up in the future and can't get back, I won't have to cry myself to sleep. I can just use Git and go back to that checkpoint.

You can also use it to create an alternate timeline called a branch. Your branch would be named master or main by default. Now, when you create an alternate branch, it copies everything from the default branch into this one, let's call this branch "dev" (you can call it whatever). In this branch, you can do whatever you like and it won't affect the "main" branch, and when you are satisfied with your work on the "dev" branch, you can open something called a pull request (as the name suggests a request to pull changes from one branch to another) and then merge (basically means accepting a pull request) it in with your "main" branch to update it.

Installation

Git is installed by default on most Linux & Mac machines. In case, it isn’t, you can use brew or apt-get to install it.

For windows users, you can download and use the installer from git-scm.com, if you have scoop you can use that, or you can use winget.

Other useful tips

Use these tips once you know what the basic commands in Git do.

To save time you can set up an alias for Git in your terminal, I have set mine to just "g" (Yeah, I really saved a lot of time, didn’t I?). It's easy to do, just check it according to your terminal.
You can also create a global .gitconfig file and add aliases for commands like st for status.

More Info

I won’t be discussing git commands here, I intended this article to only be about what git is and why you should use it.

Hope you were able to gain something from this article.