Forem: dastasoft

How to get cool animations in your React projects

dastasoft — Wed, 08 Jun 2022 21:05:13 +0000

In this guide we will apply Framer Motion animations to a basic example project to enrich the user experience with animations.

The project is made with Next and TypeScript, but you can apply all the concepts to a normal React project with JavaScript.

Sample Project

You can find in this repo the sample project, a basic memory game that has different screens for introduction, selecting the difficulty, selecting the deck (with different animes to play) and the game itself. As in other memory games, you have to discover all the pairs within the time limit.

The best approach to following this guide is to use the initial version which is fully functional without animations, test the different sections of code in the article and review the final version if you had any problems during the process.

You can check a live demo of the sample project:

*In this version, CSS animations are added to at least make the game playable.

What is Framer Motion?

It's an animation library for React made by Framer that aims to allow us to write animations declaratively and effortlessly with seamless integration with our React ecosystem.

You can achieve the same results using pure CSS but Framer Motion will allow you to quickly introduce nice and smooth animations while keeping your code simpler, working with props as you are used to in React and giving you the possibility to react to state changes and other React behaviours.

Also, if you're not quite used to CSS animations this can be a good introduction to them with a more developer-friendly syntax thanks to the intuitive syntax we'll be using.

You will be able to run simple and complex animations, transitions and even sequential animations with a couple of props in your currently working components.

Installation

Simply install the framer-motion package in the project:

yarn add framer-motion
npm install framer-motion

Once installed, simply import the motion component and use it in any HTML tag:

import { motion } from "framer-motion"

<motion.div animate={{ scale: 0.5 }} />

Motion will wrap all HTML elements and add animation properties that we will see throughout this guide.

Basic Animations

As we have seen previously, adding an animation is as simple as using the animate property on a component wrapped with motion.

So, as a first test, let's animate the Play button located on the Intro page.

// components/Intro

import { motion } from 'framer-motion'

const Intro = ({ next }: { next: () => void }) => {
  return (
    <div className="flex-vertical">
      <h1>Memory Game</h1>
      <motion.button
        onClick={next}
        animate={{ scale: 1.5 }}
        transition={{ delay: 1 }}
      >
        Play
      </motion.button>
    </div>
  )
}

export default Intro

We wrapped the button tag with the motion component, this allows us to use additional properties such as animate.
The animation provided is for scaling up by 1.5
To be able to see the size difference we add an additional property transition, which we will see in detail later, to delay the animation by 1 second.

With those few lines we have an animation ready. For now we're using the JS object syntax we're used to, but later we'll see more options for passing animations in the animate property.

In the example above, framer motion defaults us to an initial property with all the default values, but we can define it and override whatever we want for the different states of the animation.

// components/Intro

import { motion } from 'framer-motion'

const Intro = ({ next }: { next: () => void }) => {
  return (
    <div className="flex-vertical">
      <h1>Memory Game</h1>
      <motion.button
        onClick={next}
        initial={{ rotate: -360, scale: 3 }}
        animate={{ rotate: 0, scale: 1 }}
        transition={{ duration: 1 }}
      >
        Play
      </motion.button>
    </div>
  )
}

export default Intro

With that we switch from a big Play button to a normal size button while rotating.

Transitions

We will use transitions to control the animation between states, for example in the last example we have delayed the starting point by 1 second but we can do much more.

We are going to change the last Play button a bit to test some of the possibilities that transitions offer, for example we want the animation to scale in an infinite loop instead of just firing once.

// components/Intro

import { motion } from 'framer-motion'

const Intro = ({ next }: { next: () => void }) => {
  return (
    <div className="flex-vertical">
      <h1>Memory Game</h1>
      <motion.button
        onClick={next}
        animate={{ scale: 1.5 }}
        transition={{
          duration: 0.4,
          yoyo: Infinity,
        }}
      >
        Play
      </motion.button>
    </div>
  )
}

export default Intro

We have removed the delay prop but it will work with it as well.
Now the duration of 0.4 seconds is the total duration of the animation.
Finally yoyo is a special property to go back and forth between the initial state and the animation, in this case, an infinite number of times. With this property you can control how many times you want to trigger an animation.

Transitions allow us to define the type of animation we want to use, we can use:

Tween → Animations that are based on time duration, when you define a duration without any type, this is the default type used.

// components/Intro

<motion.button
        onClick={next}
        animate={{ rotate: 360 }}
        transition={{
          type: 'tween',
          duration: 0.4,
        }}
      >
        Play
</motion.button>

Spring → Simulates natural physics as animations, if you have tried react-spring this follows the same principle.

// components/Intro

<motion.button
        onClick={next}
        initial={{ x: '100vw' }}
        animate={{ x: 0 }}
        transition={{
          type: 'spring',
          stiffness: 300,
        }}
      >
        Play
</motion.button>

Inertia → Such animations will decelerate from an initial speed.

// components/Intro

<motion.button
        onClick={next}
        animate={{ rotate: 360 }}
        transition={{ type: 'inertia', velocity: 450 }}
      >
        Play
</motion.button>

Try these different options in the sample project and check the resulting animations.

Tip: Some of the above settings are incompatible with some properties, if you use TypeScript, errors will appear if any combination doesn't make sense.

Another useful use of transitions is orchestrations, which we will explain later, but there are a few things to know first.

Variants

As you can see, the code is getting bigger and bigger and soon, these new props will have even more relevance than those related to React logic. We can use variants to isolate code related to animations and much more.

With variants we need to specify different tags that we will assign to different stages of animations.

Let's refactor one of the Play button examples with variants:

// components/Intro

import { motion } from 'framer-motion'

const buttonVariants = {
  hidden: {
    x: '100vw',
  },
  visible: {
    x: 0,
    transition: {
      type: 'spring',
      stiffness: 300,
    },
  },
}

const Intro = ({ next }: { next: () => void }) => {
  return (
    <div className="flex-vertical">
      <h1>Memory Game</h1>
      <motion.button
        onClick={next}
        initial="hidden"
        animate="visible"
        variants={buttonVariants}
      >
        Play
      </motion.button>
    </div>
  )
}

export default Intro

Now we replaced all the code inside the component with:

The tag related to the initial state, in this case hidden (you can name it anything you want).
The tag related to the animate state (also contains the transition details).
The variants object that this component uses.

Tip: You can move all variants to a separate file as you would do with normal CSS or any other CSS-in-JS library to simplify your component.

Tip: If the parent component and the children share the same tags, you only need to write it once in the parent, the children will have the same tags by default.

Orchestration

In some cases we want to trigger the animations one after the other, in which case orchestration + variants will come in handy.

For example, we will animate the title of the deck selection and once the animation is finished, we will make animations for each of the children.

// components/SelectDeck

import { motion } from 'framer-motion'

import { DECKS } from '@/utils/Decks'

import Button from '../ListedButton'
import { childVariants, containerVariants } from './SelectDeck.variants'

type Props = {
  next: () => void
  setDeck: (deckName: string) => void
}

const SelectDeck: React.FC<Props> = ({ next, setDeck }) => {
  const handleSelect = (
    event: React.MouseEvent<HTMLButtonElement, MouseEvent>
  ) => {
    setDeck(event.currentTarget.value)
    next()
  }

  return (
    <motion.div
      variants={containerVariants}
      initial="hidden"
      animate="visible"
    >
      <h2>Select Deck</h2>
      <div className="flex-vertical stack">
        {Object.keys(DECKS).map((theme: string) => (
          <motion.div key={theme} variants={childVariants}>
            <Button onClick={handleSelect} value={theme}>
              {theme}
            </Button>
          </motion.div>
        ))}
      </div>
    </motion.div>
  )
}

export default SelectDeck

Before going through the variant code, note that in this component, the motion component container has the initial and animated props defined but the motion children does not. As mentioned above, the children get the animation props from the parent by default, so if we set the same tags there is no need to specify others.

// components/SelectDeck//SelectDeck.variants.ts

const containerVariants = {
  hidden: {
    opacity: 0,
    x: '100vw',
  },
  visible: {
    opacity: 1,
    x: 0,
    transition: {
      type: 'spring',
      mass: 0.4,
      damping: 8,
      when: 'beforeChildren',
      staggerChildren: 0.4,
    },
  },
}

const childVariants = {
  hidden: {
    opacity: 0,
  },
  visible: {
    opacity: 1,
  },
}

export { containerVariants, childVariants }

In transition we define two props that define the orchestration when and staggerChildren.
- In this case, we specify beforeChildren so that the parent's animation runs and completes before the children's animation.
- The staggerChildren parameter will apply each child animation one by one with a 0.4 sec delay between them.

Other ways of orchestration are:

Using delay as we did in the first example.
Delaying the children's animation with delayChildren instead of making it depend on the parent animation.
Repeating animations with repeat.

With orchestration you can make powerful combinations.

Gestures

In addition to React's built-in listeners, framer motion includes gestures that allow us to perform animations in other situations such as hover, tap, pan, viewport and drag.

For example, let's go back to our Play button in the intro screen, and perform other animations when we mouse over and tap the button:

// components/Intro

import { motion } from 'framer-motion'

const buttonVariants = {
  hidden: {
    x: '100vw',
  },
  visible: {
    x: 0,
    transition: {
      type: 'spring',
      stiffness: 300,
    },
  },
  hover: {
    scale: 1.5,
  },
  tap: {
    scale: 0.5,
  },
}

const Intro = ({ next }: { next: () => void }) => {
  return (
    <div className="flex-vertical">
      <h1>Memory Game</h1>
      <motion.button
        onClick={next}
        initial="hidden"
        animate="visible"
        whileHover="hover"
        whileTap="tap"
        variants={buttonVariants}
      >
        Play
      </motion.button>
    </div>
  )
}

export default Intro

We add the whileHover and whileTap listeners to the new hover and tap variants, as always you can name it whatever you want. With these changes, now when we mouse over the button it will scale up and when we click it, it will scale down.

You don't need to use variants to use the gestures, as in the previous examples, you can place the object directly on the listeners instead of the tag.

In this example we are only modifying the scale, but you can make complex animations and even transitions like the ones you have seen so far, think of the gestures as just another state in the animation chain.

Another very useful gesture is whileInView, with which you can easily control the triggering of animations when an element appears in the viewport, in one of my last articles about how to use Redux Toolkit I made an example project that uses this feature:

// components/Card/Card.tsx

<motion.div
      initial="hidden"
      variants={cardVariants}
      animate={controls}
      whileInView="show"
      viewport={{ once: true }}
    >
...
</motion.div>

*I simplified this component for this article but you can see the actual code in the link above.

Using whileInView and passing in the variant we want to run is all we need to trigger the animations at that precise moment. We also use viewport once to trigger the animation only once and not every time this element returns to the view.

Keyframes

Another way to have more control over the behaviour of the animation is to make it with keyframes, this is the way to go when you want to combine different properties and have an exact control over the values in time.

For example, let's add an animation for the cards when they are placed on the board:

// components/Card/

import { motion } from 'framer-motion'

import { Card as TCard } from '@/types'

import styles from './Card.module.css'

const cardVariants = {
  hidden: { scale: 0, rotate: 0 },
  flip: {
    scale: [1, 0.5, 0.5, 1],
    rotate: [0, 180, 360, 0],
    transition: {
      duration: 0.8,
    },
  },
}

type Props = {
  card: TCard
  handleSelection: (card: TCard) => void
  flipped: boolean
  disabled: boolean
}

export default function Card({
  card,
  handleSelection,
  flipped,
  disabled,
}: Props) {
  const handleClick = () => {
    if (!disabled) handleSelection(card)
  }

  return (
    <motion.div
      className={styles.card}
      variants={cardVariants}
      initial="hidden"
      animate="flip"
    >
      <div className={`${styles.inner} ${flipped ? styles.flipped : ''}`}>
        <img className={styles.front} src={card.imageURL} alt="card front" />
        <img
          src={`${card.imageURL.split('/').slice(0, -1).join('/')}/cover.jpg`}
          alt="card back"
          className={styles.back}
          onClick={handleClick}
        />
      </div>
    </motion.div>
  )
}

Changes made:

Converted to motion div the container and added cardVariants, hidden and flip states.
In cardVariants instead of using a value in scale and rotation , an array is used to specify the exact values in each keyframe.

If no duration is specified, the frame will space the changes placed on the keyframes evenly.

Controlling animations

We've seen a lot of options on how to transition between animations, but there are some situations where you need to directly control when to start and/or end an animation. In those cases we can invoke a ready-to-use hook called useAnimation.

As a simple example, let's say we want to do two animations, apart from the transition from hidden to visible, on the Play button intro screen:

// components/Intro

import { useEffect } from 'react'

import { motion, useAnimation } from 'framer-motion'

const buttonVariants = {
  hidden: {
    x: '500vw',
  },
  visible: {
    x: 0,
    transition: { type: 'spring', delay: 0.3, duration: 1 },
  },
  loop: {
    scale: 1.5,
    transition: {
      duration: 0.4,
      yoyo: Infinity,
    },
  },
}

const Intro = ({ next }: { next: () => void }) => {
  const controls = useAnimation()

  useEffect(() => {
    const sequence = async () => {
      await controls.start('visible')
      return controls.start('loop')
    }

    sequence()
  }, [controls])

  return (
    <div className="flex-vertical">
      <h1>Memory Game</h1>
      <motion.button
        onClick={next}
        variants={buttonVariants}
        initial="hidden"
        animate={controls}
      >
        Play
      </motion.button>
    </div>
  )
}

export default Intro

As you can see, after the transition from hidden to visible we want to do another animation, which in this case is an Infinity yo-yo animation, one of the solutions is to take the moment of the component's mount point with useEffect and perform the necessary actions.
The button now has controls as an animate value which is extracted from the useAnimation hook.
When the component is mounted, we can use controls to trigger any animation, which returns a promise that resolves when the animation ends.

Controls supports both the variants and the JS object we saw at the beginning of the article.

Exit animations

In addition to initial and animate there is a third state exit that we can use to make animations when the component is removed from the DOM.

In this case, we want each game screen to exit the screen in the opposite direction it came from to give the feeling of sliding screens.

// components/Intro/

import { useEffect } from 'react'

import { motion, useAnimation } from 'framer-motion'

const containerVariants = {
  exit: {
    x: '-100vh',
    transition: { ease: 'easeInOut' },
  },
}

const Intro = ({ next }: { next: () => void }) => {
  const controls = useAnimation()

  useEffect(() => {
    const sequence = async () => {
      await controls.start('visible')
      return controls.start('loop')
    }

    sequence()
  }, [controls])

  return (
    <motion.div
      className="flex-vertical"
      variants={containerVariants}
      exit="exit"
    >
      <h1>Memory Game</h1>
      <button onClick={next}>Play</button>
    </motion.div>
  )
}

export default Intro

In this case, we add an exit variant that moves the content to the left, away from the viewport.

If you try this code, it won't work, you will have to specify the parent element that needs to be aware of the presence of the components with AnimatePresence. In this case, the parent component is the single page containing the whole game:

// pages/index.tsx

import { useState } from 'react'

import { AnimatePresence } from 'framer-motion'
import type { NextPage } from 'next'

import Game from '@/components/Game'
import Intro from '@/components/Intro'
import SelectDeck from '@/components/SelectDeck'
import SelectDifficulty, { Difficulties } from '@/components/SelectDifficulty'
import { Deck } from '@/types'
import { DECKS } from '@/utils/Decks'

const UIStates = {
  IntroScreen: 0,
  DifficultyScreen: 1,
  DeckScreen: 2,
  GameScreen: 3,
} as const

const Home: NextPage = () => {
  const [UIState, setUIState] = useState<number>(UIStates.IntroScreen)
  const [deck, setDeck] = useState<Deck>(DECKS['Dragon Ball'])
  const [difficulty, setDifficulty] = useState(Difficulties.Normal)

  return (
    <div>
      <AnimatePresence>
        {UIState === UIStates.IntroScreen && (
          <Intro next={() => setUIState(UIStates.DifficultyScreen)} />
        )}
        {UIState === UIStates.DifficultyScreen && (
          <SelectDifficulty
            next={() => setUIState(UIStates.DeckScreen)}
            setDifficulty={setDifficulty}
          />
        )}
        {UIState === UIStates.DeckScreen && (
          <SelectDeck
            next={() => setUIState(UIStates.GameScreen)}
            setDeck={(deckName: string) => setDeck(DECKS[deckName])}
          />
        )}
        {UIState === UIStates.GameScreen && (
          <Game
            selectedDeck={deck.slice(0, difficulty)}
            backToDifficulty={() => setUIState(UIStates.DifficultyScreen)}
            backToDeck={() => setUIState(UIStates.DeckScreen)}
          />
        )}
      </AnimatePresence>
    </div>
  )
}

export default Home

And I'm sorry to say that, despite adding AnimatePresence, it still doesn't work! And that's because framer doesn't distinguish which component we are trying to animate when switching screens, so you need to specify an unique key for each screen.

{UIState === UIStates.IntroScreen && (
    <Intro
        next={() => setUIState(UIStates.DifficultyScreen)}
        key={UIStates.IntroScreen}
     />
 )}

Now it's working, but you'll see some weird animation where the first screen and the second screen exist at the same time. So, to fix that and the last step to get this animation working, is to tell framer that we want to delay the following animations until the exit animation is completely finished.

<AnimatePresence exitBefoeEnter>

Animations for SVG

A cool utility is the ability to animate the SVG, and it's as easy and simple as using pathLength to animate the SVG path drawing process.

First, let's add this SVG to the introduction page:

// components/Intro/index.tsx

<svg
        className={styles.Container}
        xmlns="http://www.w3.org/2000/svg"
        viewBox="0 0 512 512"
      >
        <motion.path
          fill="none"
          stroke="var(--primary)"
          strokeWidth={6}
          strokeLinecap="round"
          variants={pathVariants}
          d="M256 224C238.4 224 223.1 238.4 223.1 256S238.4 288 256 288c17.63 0 32-14.38 32-32S273.6 224 256 224zM470.2 128c-10.88-19.5-40.51-50.75-116.3-41.88C332.4 34.88 299.6 0 256 0S179.6 34.88 158.1 86.12C82.34 77.38 52.71 108.5 41.83 128c-16.38 29.38-14.91 73.12 25.23 128c-40.13 54.88-41.61 98.63-25.23 128c29.13 52.38 101.6 43.63 116.3 41.88C179.6 477.1 212.4 512 256 512s76.39-34.88 97.9-86.13C368.5 427.6 441 436.4 470.2 384c16.38-29.38 14.91-73.13-25.23-128C485.1 201.1 486.5 157.4 470.2 128zM95.34 352c-4.001-7.25-.1251-24.75 15-48.25c6.876 6.5 14.13 12.87 21.88 19.12c1.625 13.75 4.001 27.13 6.751 40.13C114.3 363.9 99.09 358.6 95.34 352zM132.2 189.1C124.5 195.4 117.2 201.8 110.3 208.2C95.22 184.8 91.34 167.2 95.34 160c3.376-6.125 16.38-11.5 37.88-11.5c1.75 0 3.876 .375 5.751 .375C136.1 162.2 133.8 175.6 132.2 189.1zM256 64c9.502 0 22.25 13.5 33.88 37.25C278.6 105 267.4 109.3 256 114.1C244.6 109.3 233.4 105 222.1 101.2C233.7 77.5 246.5 64 256 64zM256 448c-9.502 0-22.25-13.5-33.88-37.25C233.4 407 244.6 402.7 256 397.9c11.38 4.875 22.63 9.135 33.88 12.89C278.3 434.5 265.5 448 256 448zM256 336c-44.13 0-80.02-35.88-80.02-80S211.9 176 256 176s80.02 35.88 80.02 80S300.1 336 256 336zM416.7 352c-3.626 6.625-19 11.88-43.63 11c2.751-12.1 5.126-26.38 6.751-40.13c7.752-6.25 15-12.63 21.88-19.12C416.8 327.2 420.7 344.8 416.7 352zM401.7 208.2c-6.876-6.5-14.13-12.87-21.88-19.12c-1.625-13.5-3.876-26.88-6.751-40.25c1.875 0 4.001-.375 5.751-.375c21.5 0 34.51 5.375 37.88 11.5C420.7 167.2 416.8 184.8 401.7 208.2z"
        />
</svg>

And the real magic behind it, the pathVariants

// components/Intro/Intro.variants.ts

const pathVariants = {
  hidden: {
    pathLength: 0,
  },
  visible: {
    pathLength: 1,
    transition: {
      duration: 4,
      yoyo: Infinity,
      ease: 'easeInOut',
    },
  },
}

I've overcomplicated this with a bunch of additional properties that we already know about at this point but the key is to go from 0 pathLenght to 1, framer motion will follow the path description of our SVG and draw that path with the animation values we specify.

Conclusion

With this simple project we have seen how easy, reliable and aligned with our current skills it is to include both simple and complex animations in our projects.

This is just an introductory guide to framer-motion, there is a lot more inside the library, especially a lot of utility hooks to make even crazier animations effortlessly and advanced topics like 3D animations by combining this library with react-three/fiber for example.

Be sure to check out the official documentation and try out different animations to take your projects to a new level.

Intro to MongoDB and Mongoose - How Every Web Developer Can Become FullStack With Node.js

dastasoft — Thu, 17 Mar 2022 16:17:24 +0000

In the previous post about MERN Stack we developed a simple REST API with Node.js and Express, our fake database was a collection of JSON and there was no real interaction with a database, only with the filesystem.

In this post we will continue that project about companies and jobs by adding a real database into the mix, for that we will use MongoDB, check what relational and non-relational databases are, what packages to use to improve our developer experience and where and how to manage the database.

Example project

You can check the first entry of this series if you want to learn more about how Node.js and Express work or start right where we left off last time in this branch.

The example project is a fictitious project about companies posting jobs to work on Mars.

Why MongoDB?

I used JSON files in the previous post because the data structure is very similar on how document based databases work so, the transition from one to the other will be easier, but why use MongoDB instead of other databases?

The first reason is because it is the M in the MERN stack and what kind of MERN stack guide would it be if I dare to use another one!

The real reasons come when compared to traditional databases as we will see below. But in short, Mongo was created to address problems such as evolving applications quickly without database migrations and having data that is frequently read in the same place to increase performance.

Different concepts for different types of databases

In the following sections I will refer to traditional databases also known as SQL or relational databases such as MySQL or PostgreSQL and non-tabular databases such as MongoDB or Apache Cassandra.

*You will also see the definition of NoSQL or non-relational databases but it is partially incorrect because there are relationships, but not in the traditional way we know and there is also Structured Query Language in this kind of databases although it is not SQL, we will see both topics later.

Storing Data

Traditional database → The structure of the data is predefined and fixed, meaning that it stores the data in Tables which are defined by Columns.

*Document database → The structure is optional and flexible, the data is stored in Collections containing Documents, each Document can have the same fields, slightly different or totally different.

*I use the document database here as an example because we will use MongoDB in this guide, but NoSQL databases can be key-value, graph and wide-column oriented data, not just document oriented data.

So to summarise the evolution of these concepts a bit:

Table → Collection

Row → Document

Column → Field

Relations

Traditional database → This is done with a primary key column in one table and a foreign key column in the other table linking the relationship.

Document database → There are different ways to achieve this:

The data contained in a Document is of JSON type so the direct way to achieve relationships is: embed data.
Create different Collections and link the Documents by their id, very similar to the SQL DB approach.

Embedding data

Here we have a Document on a Job that contains another scope of data relating to the Company in the same Document.

This approach is good when your document is small, if you are nesting large trees you may face performance issues at some point. It can also be used with things that don't have their own entity because when you want to update some value it can be a mess to go one by one making updates.

Relationship to id

As you can see this Document contains the information relating to the Job but it also has companyId which links this particular Document to another one in another Collection.

This approach is useful when you want to keep the scopes separate and for example update a field in a Document and all its relationships will get that single change without modifying anything.

Queries

Some examples of simple queries:

SELECT * FROM users WHERE username="dastasoft"
SELECT * FROM companies ORDER BY _id DESC
SELECT name, salary FROM jobs WHERE availablePositions > 10

db.users.find({username="dastasoft"})
db.companies.find().sort( { _id : -1 })
db.jobs.find({ availablePositions : {$gt: 10}}, { name : 1, salary : 1})

As I said before, MongoDB does not use SQL, but it has its own syntax to achieve the same behaviour.

As you can see, the type of database depends entirely on the needs and nature of your project, with traditional databases you need to do a lot of hard work beforehand to design the database and NoSQL databases are more suitable for projects that are unsure of the features they will have, the scale or the need to adapt quickly to changing requirements.

In short, there is no best option per se, it all depends on your needs.

Setup

If you want to use MongoDB as your database there are many options for where you can store your data. I'll just list a few options and give a brief description.

Install locally

Installing MongoDB on your machine may be one of the best options, especially if it is your first time using MongoDB, it is a good option to install locally and play around with it.

Docker

With the example project this option is provided, if you install Docker on your system you will be able to run a MongoDB instance without installing MongoDB itself, the best thing about this option is that it is highly portable and convenient, also this option tries to end the "on my local machine it works" quote because you will be able to deploy that same Docker container to a PROD environment.

The scope of this guide does not cover Docker stuff so, inside the example project you can check how the initial data is stored in the DB and the Docker related configuration but if you are not interested in that part, just run npm run start:docker.

MongoDB Atlas

Atlas is a multi-cloud database service from the creators of MongoDB, it is the most complete option because you don't have to install anything on your computer, you can choose from the major cloud providers to store your database and like many services nowadays you can start for free and pay as you go.

Also the database at the free level can be provisioned with sample data, one of my previous sample projects Apartmentfy was built entirely with sample data, check out the different sample collections and maybe your next project already has data ready to use.

MongoDB Shell, MongoDB for VS Code and Compass

Whichever installation option you chose, you'll need to check the data, and there are three options beyond checking the MongoDB Atlas web site if you chose that option.

If you have installed MongoDB on your machine, the MongoDB Shell is also installed, so you can connect to the database provided in the example project with:

mongo -port 27017 -u root -p password

There is a MongoDB for VS Code plugin that will allow you to check data and test queries directly in VSCode, you will have to provide the connection string or fill in the form, for example to connect to the example project:

The other option is to install MondoDB Compass, a graphical interface that is very similar to what you will see on the MongoDB Atlas website.

Interacting with the DB from Node.js

The most basic way to interact with MongoDB is using the Official MongoDB Node.js Driver, in this guide we will use Mongoose an object modeling tool.

Before diving into Mongoose it is important to know why we choose one or the other. Mongoose is built on top of MongoDB Native Driver so, as you can imagine if you need more control or a more raw approach, Mongoose is an extra layer that you may not need.

While Mongoose is intended to allow developers to create and force specific schemas, validations and different utilities at the application layer, MongoDB Native Driver relies on the database layer.

This means that if you use Mongoose you will code very javascript-like relationships, validations and so on and that will only be alive in your Node.js, the database won't be aware of any of this.

With MongoDB Native Driver you will have full control of what you are doing, and the configuration, like validations, will be in the database itself.

There is no bad option here, but there is some rule of thumb for deciding which one to use:

If your data structure is simple, chances are you don't need Mongoose.
If your data structure is very undefined and will change a lot, not being tied to a schema, as Mongoose tries to do, may be good for you.
If you want to take advantage of the built-in validations, optimisations and other functionalities instead of doing it yourself, Mongoose can be a time saver.

At the end of the day Mongoose has a lot of work already done for you, which is why it is the choice of many developers but both options have a lot of support and both will give you more knowledge about how MongoDB works but remember that the official support from the MongoDB team will only be for Native Driver.

My recommendation is to start with what you want and learn the basics, if you work best in a defined/limited schema, Mongoose will be more suitable for you, if you want to do simple testing and try different things quickly, Native Driver will be a better experience. When you have all the basics, reread this section, it will make a lot more sense with that knowledge.

Also after this guide, spend some time going through Native Driver to get a good understanding of what is going on under the hood and to be able to choose the one that best suits your project. The whole example project is straightforward and can be done perfectly well without Mongoose.

Connection

// lib/db.ts

import mongoose from 'mongoose'

export default async function connectDB() {
  try {
    const Mongoose = await mongoose.connect(`${process.env.MONGO_URI}`)
    console.log(`💿 MongoDB Live: ${Mongoose.connection.host}`)
  } catch (error) {
    console.error(error)
    process.exit(1)
  }
}

Connecting to the database is simple, just provide the URL of the MongoDB, depending on the option you have selected to store your database this will change but it will more or less follow this syntax:

mongodb://USER:PASSWORD@localhost:PORT/DATABASE?authSource=admin

Because this string contains sensitive information it is highly recommended to use environment variables and not to upload env files to the repo to avoid leaks.

Models and Schemas

As we saw before, one of the features of Mongoose is to interact with the DB, that is done through Schemas and Models.

The Schema will be a mapping of a MongoDB collection, we will control the form of the documents through the Schema, with TypeScript we will even control more explicitly this part.

Models will be a representation of a document, and will provide us with the different built-in instance methods to perform the different operations we need. Later we can add our own methods to the Model to perform custom operations.

//models/job.ts

import { Schema, Model, model } from 'mongoose'

import { Job as JobProps } from '../types'

const JobSchema = new Schema<JobProps, Model<JobProps>>(
  {
    availablePositions: { type: Number, min: 1 },
    companyId: { type: Schema.Types.ObjectId, ref: 'Company', required: true },
    description: { type: String, required: true },
    function: { type: String, required: true },
    industry: { type: String, required: true },
    location: { type: String, required: true },
    numberApplicants: Number,
    postDate: { type: Date, default: () => Date.now() },
    published: { type: Boolean, required: true },
    requirements: { type: [String], required: true },
    salary: Number,
    workType: { type: String, required: true },
  },
  { timestamps: true }
)

const JobModel = model<JobProps>('Job', JobSchema)

export default JobModel

Let's take a look at the model of a Job:

We create the Schema based on Mongoose, thanks to TypeScript we can ensure that the form of the Schema is according to the type we define for a Job.
Each property is defined at least with its type, if you need to specify more parameters, then you need to use the longer syntax. As you can see companyId is what we will use later to retrieve information about companies that are in a different collection. This relationship is done by defining the ref attribute and the special type that MongoDB uses for internal ids ObjectId.
Finally we create the Model based on the Schema.

*Properties can be as simple as String, Number, Date etc. or more complex like a nested object. In the example above you can find a good range of different possibilities.

**You don't need to specify an _id for your Schema, Mongoose will add it automatically but, if you need to set manual ids, you can define it explicitly.

Validators

In some properties I have placed validators, like min or required, in addition to the built-in validations you can create your own, for example let's imagine we want the numberApplicants to never be greater than the availablePositions.

numberApplicants: {
      type: Number,
      validate: {
        validator: value => value <= this.availablePositions,
        message: props =>
          `${props.value} is higher than the available positions`,
      },
}

Both built-in and custom validations will be executed ONLY when the save or create methods are performed on the model as we will see below.

In the User model you can see more examples of validators.

// models/user.ts

const UserSchema = new Schema<UserDocument, UserModel>(
  {
    avatar: String,
    email: {
      type: String,
      required: true,
      lowercase: true,
      trim: true,
      unique: true,
    },
    firstName: { type: String, required: true },
    lastName: String,
    password: { type: String, required: true, minlength: 8 },
    type: {
      type: String,
      enum: ['applicant', 'recruiter'],
      default: 'applicant',
    },
    username: {
      type: String,
      required: true,
      unique: true,
      minlength: 6,
      maxLength: 24,
    },
  },
  { timestamps: true }
)

The timestamps you can check in both examples are to specify that we want the fields automatically createdAt and updatedAt.

So all this configuration gives us two things:

Even before we run the project, we have type safety with TS.
At runtime, if we mistakenly send a String to availablePositions or any other error that fails validations, we get a Mongoose error preventing that action.

Due to the nature of MongoDB and JS, each document may be different, without Mongoose or TS we may end up with a collection of these example documents

{
    name: "Capsule Corp",
    about: "Like WinRAR but we accept more file extensions.",
    industries: ["automobile", "house", "engineering"],
    numberEmployees: 2,
    yearFounded: 1990,
        someImportantProperty: "If I'm empty all explodes"
  },
  {
    name: "Red Ribbon",
    about: "We deliver the best Android you can ever had",
    industries: ["militar", "artificial intelligence", "engineering"],
    numberEmployees: '2000', // In this example this field is an string
    yearFounded: 1000,
  },

If this is not what is intended, finding these errors in a database with large documents can be a daunting task.

Controller

In the previous version of the example project all the communication was with a fake database made with JSON files but, the basic actions will remain the same, we will list, create, update and delete, this time, we will be using the Model we created in the previous step to interact with MongoDB.

// controllers/job.ts

import { Request, Response } from 'express'

import JobModel from '../models/job'
import { Company } from '../types'

const list = async (req: Request, res: Response) => {
  try {
    const job = await JobModel.find()
      .populate<{ companyId: Company }>('companyId')
      .sort({
        createdAt: -1,
      })

    res.json(job)
  } catch (error) {
    res.status(500).json({ error, message: 'No jobs were found.' })
  }
}

const create = async (req: Request, res: Response) => {
  if (!req.body) res.status(400).json({ message: 'No job has provided' })

  try {
    const job = await JobModel.create(req.body)
    res.status(201).json(job)
  } catch (error) {
    res.status(500).json({ error, message: 'Error creating the job' })
  }
}

const details = async (req: Request, res: Response) => {
  const { id } = req.params

  try {
    const job = await JobModel.findById(id)
    if (!job)
      res.status(404).json({ message: `No jobs were found with id ${id}` })

    res.status(200).json(job)
  } catch (error) {
    res.status(500).json({ error, message: 'Error retrieving the job' })
  }
}

const update = async (req: Request, res: Response) => {
  const { id } = req.params

  try {
    const job = await JobModel.findByIdAndUpdate(id, req.body, {
      useFindAndModify: true,
    })

    if (!job)
      res.status(404).json({
        message: `Cannot update Job with id ${id}. Job was not found.`,
      })

    res.status(200).json(job)
  } catch (error) {
    res.status(500).json({
      error,
      message: `Error updating Job with id ${id}.`,
    })
  }
}

const remove = async (req: Request, res: Response) => {
  const { id } = req.params

  try {
    const job = await JobModel.findByIdAndRemove(id)
    if (!job)
      res.status(404).json({
        message: `Cannot delete Job with id ${id}. Job was not found.`,
      })

    res.status(200).json(job)
  } catch (error) {
    res.status(500).json({
      error,
      message: `Error deleting Job with id ${id}.`,
    })
  }
}

export { list, create, details, update, remove }

*This version it is also done with async/await instead of using callbacks as in the previous version of this tutorial to show a different version.

As you can see in the different methods, we use the Model which provides a lot of functionality to perform all the actions in a clear way.

Some of the basic functionalities are:

Retrieve data

find to retrieve all documents that pass the filter, in the example there is no filter but the method accepts an object to be used as a filter:

// find all documents in job collection that are from the electronics 
// industry and have 100 or more available positions
JobModel.find({industry: "electronics", availablePositions: { $gte: 100 }})

You can query the data using regular expressions, exact numbers and many other combinations that give you a lot of flexibility.

Another way to query the data is to use where:

// Find jobs that...
JobModel.where("published").equals(true) // are published
JobModel.where("availablePositions").gt(1) // Has more than 1 available position

You can also chain multiple conditions as in the example above.

JobModel.where('industry')
    .equals('electronics')
    .where('availablePositions')
    .gte(100)

Two important utilities for data retrieval are limit and select:

JobModel.where('industry')
    .equals('electronics')
    .where('availablePositions')
    .gte(100)
        .limit(10)
        .select("description")

limit will set a maximum number of results returned.
select will return only that field for each document retrieved (plus the _id)

Joining documents

In the Job schema we have defined there is a reference to the Company schema with the companyId field. Each job will have a company that posts the actual job, what if I want to retrieve information about the company along with the job?

There are several ways to achieve this behaviour, one of which is included in the above example from the Controller, using populate.

JobModel.find().populate<{ companyId: Company }>("companyId")

With this, we are telling Mongoose that we want the Company information that is bound by the companyId field. The square brackets are part of TS specifying the type of object it will return, in this case a Company.

It is also worth mentioning that you can fill in certain parts of the other document instead of retrieving everything.

JobModel.find().populate("companyId", "name")

Save data

save to store new documents in the database, you can find an example in the create method in this example.

// req.body example data
// {
  //   availablePositions: 10,
  //   companyId: _id,
  //   description: "Senior Radar Engineer",
  //   function: "Develop a trusty and reliable green radar.",
  //   industry: "engineering",
  //   location: "Tempe Terra, Mars",
  //   numberApplicants: 9,
  //   postDate: "2021-07-12T11:33:51.563Z",
  //   published: true,
  //   requirements: [
  //     "At least three years of experience with Radar related hardware and Radar.js framework.",
  //   ],
  //   salary: 40000,
  //   workType: "full time",
 // }, 

const job = new JobModel(req.body);
jobOffer.save().then(() => console.log("Job saved!"))

You can achieve the same behaviour in one step with create.

JobModel.create(req.body).then(() => console.log("Job offer saved!"))

Note that save is a method of the Model so you need to create an instance of that Model but create is a static method so you can use it directly.

Update data

The findByIdAndUpdate is a shortcut to perform both the search and the update, but remember that the update part will bypass the validators we defined in our Schema. If you want to run the validators using that function, you need to specify the runValidators option.

For example, let's imagine we put a min validator on numberEmployees in our company schema

// numberEmployees: { type: Number, required: true, min: 2 }
// req.body = { numberEmployees: 1}
const company = await CompanyModel.findByIdAndUpdate(id, req.body)

This will update correctly even if we have defined that min validator.

If you need the validators in this operation, you must explicitly specify it.

const company = await CompanyModel.findByIdAndUpdate(id, req.body, {
      runValidators: true,
    })

Also by default the document before the update is returned, if you need the updated document:

const company = await CompanyModel.findByIdAndUpdate(id, req.body, {
      new: true
    })

Remove data

Finally, findByIdAndRemove is like the above but for deletion purposes.

This is just a small number of examples of the methods that Mongoose provides.

Getting more from the schema

We now know the basics of how to perform CRUD operations with Mongoose, but there is more functionality available to go further with our Schema definition.

Schema methods

Apart from the built-in methods we can add our own custom logic to the schema.

For example in the user model we want to add a custom method to check if the password provided in the login is the same as the one we have in the database.

// models/user.ts

UserSchema.methods.isCorrectLogin = function (password: string) {
  return new Promise<Error | boolean>((resolve, reject) => {
    bcrypt.compare(password, this.password, function (err, result) {
      if (err) return reject(err)
      if (result) return resolve(true)
      return resolve(false)
    })
  })
}

Custom methods will be used via the new keyword or after retrieving a Document never directly from the model.

// controllers/user.ts

const login = async (req: Request, res: Response) => {
  if (!req.body) {
    res.status(400).json({ message: 'No user data has been provided' })
  }

  const { email, password } = req.body

  try {
    const user = await UserModel.findOne({ email })
    let isCorrectLogin: boolean | Error = false

    if (user) {
      isCorrectLogin = await user.isCorrectLogin(password)
      if (isCorrectLogin)
        res.status(200).json({ message: `Welcome ${user.fullName}` })
    }

    res.status(401).json({
      message: 'Email password combination is not correct',
    })
  } catch (error) {
    res.status(500).json({ error, message: 'Error retrieving the user' })
  }
}

For TypeScript users, you will need to declare the following interface to bind properties, statics and custom methods to your schema.

//models/user.ts

interface UserDocument extends Document, UserProps {
  isCorrectLogin(password: string): Promise<Error | boolean>
}

Schema Statics

If you need to use a custom functionality directly from the Model you can declare a static instead of a method.

// models/user.ts

UserSchema.statics.getUser = function (username: string) {
  return new Promise((resolve, reject) => {
    this.findOne({ username }, (err: Error, user: UserDocument) => {
      if (err) reject(err)
      resolve(user)
    })
  })
}

Note that this in this example refers to a user model and not to a user document as in the previous example.

For TS users, statics will be defined in the UserModel instead of the UserDocument.

// models/user.ts

interface UserModel extends Model<UserDocument> {
  getUser(username: string): Promise<Error | UserDocument>
}

Both statics and methods must be declared using function and not with arrow functions, because arrow functions prevent linking this explicitly.

Virtual

In some cases properties are needed in the retrieved document but it may not be necessary to persist that data, the virtual are just for that.

Virtuals can be getters and setters, you will use getters when you need to combine data FROM the database and setters when you want to combine data WITHIN the database.

// models/user.ts

UserSchema.virtual('fullName').get(function (this: UserDocument) {
  return this.firstName + this.lastName
})

For TS users, you will need to include these fields as UserDocument properties.

// models/user.ts

interface UserDocument extends Document, UserProps {
  fullName: string
  isCorrectLogin(password: string): Promise<Error | boolean>
}

Pre and Post Operations

Finally, if we want to execute something before or after a certain operation we can use the pre and post middlewares, for example in the sample project we encrypt the password provided by the user when perform singup

// models/user.ts
const ROUNDS = 10

UserSchema.pre<UserDocument>('save', async function (next) {
  this.updatedAt = new Date()

  if (this.isModified('password')) {
    const hash = await bcrypt.hash(this.password, ROUNDS)
    this.password = hash
  }
  next()
})

In this case, this will be executed before saving the user to the DB, we will take the password provided by the user, encrypt with bcrypt and modify the UserDocument to store.

Remember to use a regular function instead of an arrow function to preserve this as a UserDocument.

Conclusions

As you can see MongoDB is very flexible, and I hope you now understand a little more about its popularity, although here we have only scratched the surface of what MongoDB is capable of, I suggest you try this same exercise with the official MongoDB native driver just to expand your knowledge and really understand how it all works.

But the truth is that creating and maintaining a REST API can be a less daunting task with the help of Mongoose and through this article you have seen how to take advantage of its capabilities. In addition, we saw the basics of Express CRUD operations with MongoDB, why to use Mongoose or Native Driver and some TypeScript helpers.

From here you can try this same project with other databases beyond MongoDB, even relational databases, this project is now small enough to allow you to switch quickly and see the differences easily.

How to get better and easier state management with Redux Toolkit

dastasoft — Wed, 01 Dec 2021 16:04:29 +0000

State management is a necessary part of almost every React project and the idea of "how it needs to be done" has changed over the years. In this article you will learn how to use the new Redux Toolkit, what problems it solves and when it can be useful for your projects.

As always I provide a demo project that uses the things we will see here, feel free to try it and check out the source code.

Resources

The demo project

Simple demo project of a shop displaying Pokemon Trading Card Game cards with prices and the option to add them to a cart to proceed to checkout.

The demo aims to demonstrate how Redux's RTK Query is used to fetch data from a third party API and how the Redux Toolkit handles client state for the cart logic.

In addition to Redux the project is made with Next.js, TypeScript, ChakraUI and Pokemon TCG API.

Don't worry if you are not used to Next.js, TS or ChakraUI, I have not used any advanced feature and the code will be explained in detail, but if you want to know more about these tools you can check my other articles:

Why you should use Chakra UI in React
Here is what every React Developer needs to know about TypeScript
I don't have an article about Next.js yet but, you can start your journey with my Next.js boilerplate

How state management has evolved

Within the React ecosystem there are multiple state management options and every now and then there is a new trend that dominates all the guides and projects and there really isn't such a bad option, the problem here is that one size doesn't fit all.

I'm going to talk about my experience, but I'm sure you may face a different way on this and I'd love to hear how it went for you. If you want to go straight to how the Redux Toolkit works and avoid all the historical stuff, skip this section 😁.

this.setState

In the beginning React handled state without the help of any third party library, inside class components, which at that time was the only component type that had state, we defined a state and mutated it through setState.

class Clock extends React.Component {
  constructor(props) {
    super(props);
    this.state = { date: new Date() };
  }
  componentDidMount() {
    this.timerID = setInterval(() => this.tick(), 1000);
  }
  componentWillUnmount() {
    clearInterval(this.timerID);
  }
  tick() {
    this.setState({ date: new Date() });
  }
  render() {
    return (
      <div>
        <h1>Hello, world!</h1>
        <h2>It is {this.state.date.toLocaleTimeString()}.</h2>
      </div>
    );
  }
}
ReactDOM.render(<Clock />, document.getElementById("root"));

Problems like trying to mutate state directly, which happened a LOT, or losing data from nested objects were common errors at the time.

Another big concern at the time was prop drilling, back then there was no Context and you were forced to go through the tree every state you needed, that's why the idea of having a global state and plugging it in where you needed it became so popular, but that's just the next point.

Redux Everywhere

It is very likely that when you first take a look at React, Redux was the option of choice at the time.

Many articles and guides talked about React with Redux as the perfect combination and the benefits of having the state decoupled and centralised. At one point it even seemed that if you used React, you had to use Redux.

Global state was such a big thing that every piece of data, every button state, UI change and so on ended up in the Redux store, no more props drilling was needed.

The problem to start with was that not all projects took enough advantage of using Redux and not everything had to be in a central store and a lot of boilerplate code was needed, especially when you need to get asynchronous data, and most of our projects ended up with code like this:

import * as actionTypes from '../actions/actionsTypes';

const initialState = {
    orders: [],
    loading: false,
    purchased: false
};

const reducer = (state = initialState, action) => {
    switch (action.type) {
        case actionTypes.PURCHASE_INIT:
            return {
                ...state,
                purchased: false
            };
        case actionTypes.PURCHASE_START:
            return {
                ...state,
                loading: true
            };
        case actionTypes.PURCHASE_SUCCESS:
            const newOrder = {
                ...action.orderData,
                id: action.orderId
            };

            return {
                ...state,
                loading: false,
                orders: state.orders.concat(newOrder),
                purchased: true
            };
        case actionTypes.PURCHASE_FAIL:
            return {
                ...state,
                loading: false
            };
        case actionTypes.FETCH_ORDERS_START:
            return {
                ...state,
                loading: true
            };
        case actionTypes.FETCH_ORDERS_SUCCESS:
            return {
                ...state,
                loading: false,
                orders: action.orders
            };
        case actionTypes.FETCH_ORDERS_FAIL:
            return {
                ...state,
                loading: false
            };
        default:
            return state;
    }
};

export default reducer;

And also define what each action did:

const purchaseSuccess = (id, orderData) => {
    return {
        type: actionTypes.PURCHASE_SUCCESS,
        orderId: id,
        orderData
    };
};

const purchaseFail = error => {
    return {
        type: actionTypes.PURCHASE_FAIL,
        error
    };
};

const purchaseStart = () => {
    return {
        type: actionTypes.PURCHASE_START
    };
};

In addition, components must be connected and mapped in this way:

const Orders = () => {
    // ...
}

const mapStateToProps = state => {
    return {
        orders: state.order.orders,
        loading: state.order.loading
    };
};

const mapDispatchToProps = dispatch => {
    return {
        onFetchOrders: () => dispatch(actions.fetchOrders())
    };
};

export default connect(
    mapStateToProps,
    mapDispatchToProps
)(Orders);

In short, this was a lot of code, and was often overkill for small and medium-sized applications, but to be honest, in many cases it was more a misunderstanding or perhaps a dogmatic way of how and when to use Redux, than Redux's fault.

Hooks to the rescue

With version 16.8 we got hooks and useState, useContext ,useEffect and the less used but no less effective useReducer came to save the day.

Thus began the rise of the "you don't need Redux at all".

Personally I jumped on that boat right away, the promise was that I didn't have to install multiple packages, no more boilerplate code, and useState can be used multiple times so I don't fall into complex nested objects, useContext eliminates props drilling so.... everything was nice and shiny but...

Some things I noticed after a few happy projects:

If the application gets bigger, it's harder to maintain a spread of state across the application.
Sometimes components were built with a context in mind, later that component moved out of the sub-tree of that context and everything broke.
When a new co-worker joins the company/team/project it is less obvious how the data flow is currently working than if you just have a separate store and reducers that clearly show how the data is updated.
When a bug appears, it is a challenge to find out what happened, Redux Dev Tools was and still is a blast.

But I must admit that for small and medium projects, it was faster (in development time I mean) and more convenient because as I said before, not every kind of project needed Redux in the first place.

Again, if I'm honest this wasn't React's fault either, the problem was going all in on one solution instead of using each piece where it fits best.

Redux + Hooks

React Hooks was a big deal and Redux introduced his own Hooks some time later.

The problem of having to write the common pattern for asynchronous actions with states for START, SUCCESS and ERROR was still there but at least the connection and mapping was easier:

mapStateToProps was replaced by useSelector.

const { video: currentVideo } = useSelector(
    (state: AppState) => state.CurrentVideo
  );

And the mapDispatchToProps was replaced by a combination of useDispatch and the functions directly:

const dispatch = useDispatch();
dispatch(fetchVideoWithExtraInfo(page));

The main benefits of this approach besides being less boilerplate code, is easy to understand because with connect the component "magically" got new props, but with useSelector and useDispatch it is clear where that data comes from and why you have access to it.

In short, it was an improvement but the problem with the middleware for asynchronous actions was still there. And in my case that boilerplate code was the big reason not to give it a chance.

react-query

Then react-query came along and for me it was like magic.

I discovered react-query because I was using react-table and it was from the same author Tanner Linsley, I encourage you to try his stack because it works like a charm and will save you a lot of time.

react-query came with a solid purpose, filling the gap that no other library was big and opinionated about, how to get asynchronous data. So this library wasn't here to replace any of the previous state managers, as those were there to handle client and server state, but react-query focused only on server state.

const { isLoading, error, data } = useQuery('repoData', () =>
     fetch('https://api.github.com/repos/tannerlinsley/react-query').then(res =>
       res.json()
     )
   )

With the above code, you instantly have something very similar to the reducers in Redux where you put those START, SUCCESS and ERROR but with almost 0 config and no boilerplate code. In this case data will contain the data fetched from the API, already cached and merged with the updates, and the other params will tell you the status directly.

Anywhere in your code if you did something to that source, like mutate the data, if it is properly bound, the binding was done by the repoData query key in this case, it will work.

You have a component that fetches all your products and you have different components to create, update or delete them? No problem, all queries are connected by the query key.

As an example, it's much more available in react-query, like in this code from a Pokedex project:

const {
    status,
    data,
    error,
    isFetching,
    isFetchingMore,
    fetchMore,
    canFetchMore
  } = useInfiniteQuery('fetchPokemons', fetchPokemons, {
    initialData: [initialPokemonList],
    getFetchMore: lastGroup => lastGroup?.next
  });

Things like automatic fetching when the browser loses and regains focus or when a certain time elapses, caching the data and at the end of the day, synchronising and updating the server state was a lot of work already done for you and easily configurable but with a solid initial setup. It's worth mentioning that react-query also has development tools.

As I said before, this time it was not possible to bet all your money on this library because it handles only server state, you still need something for client state.

In the projects where I used this library, the challenge was more to have a solid architecture defined to avoid wild queries and mutations throughout the whole project and to have that effect we were talking about before that new people don't easily understand what the data flow was like.

At this point, I was using react-query in combination with React Hooks, but I thought that Redux, which had some great development tools and a good idea of global state could be a good ally if react-query handled the one element I don't tolerate in Redux, the boilerplate for asynchronous data.

When I decided to write a guide about that, Redux Toolkit appeared and I felt like someone read my mind and I started tinkering with it.

Redux Toolkit, the opinionated version of Redux

What problems solve?

If you have read the previous section you can already guess this point, but let's dive into the most important thing, or one of the most important things at least, when choosing a library for your project, knowing what problems it will solve:

As I mentioned earlier in previous versions of Redux a lot of boilerplate code was required to do simple things like having statuses for load or error, we'll go into this in detail later but RTK Query is a package included in the Toolkit that will introduce more or less the same magic as react-query and all that boilerplate code will be MUCH reduced.
The other biggest gripe with Redux development was the need to install a lot of packages depending on what you want to do, for example when going from client state to also managing server state, middleware and thunk was required, inside the Toolkit you will have everything you need.
As in the first point, configuring the store was complicated and with a lot of boilerplate code, as we will see below, now the process is an abstraction and they already have a lot of configuration done for us.

So Redux Toolkit is an abstraction and opinionated version of the common Redux that tries to standardise the way we manage state with Redux.

Also for TypeScript users, Redux Toolkit has been built with TS in mind, as we will see in the examples typing will be much easier than with previous versions of Redux but also many types will be provided automatically.

I must migrate to Redux Toolkit?

So if you are using previous versions of Redux there is no need to worry about staying on those versions, they work and will continue to work, there are no breaking changes here.

I would say that if after reading the following examples you realise that the decisions go in the same direction you were planning, your application will be simplified or become easy to maintain and scale maybe the refactoring will be worth it for you.

If you are using only React's built-in tools or other libraries, read the next section, which will be applicable to any version of Redux.

When to use Redux?

Normally we tend to simplify and use the size of the app as a delimiter for when to use Redux or for example React Hooks only, it is true that Redux is more necessary when the code base is larger but in fact it will come in handy especially in apps that:

You need to access and/or update state from many different places.
You work with different people on the same codebase and need to keep track of how the status changes frequently.
People join the project often, so you need a clear way to show app state changes.
In the case of data fetching, you want a cache, optimistic updates, status tracking and/or to avoid duplication of requests without having to write them yourself.

Remember that having a need for state management does not mean you have to use Redux.

Installing Redux Toolkit

Assuming you are already in a React-based project, you need to install Redux Toolkit and React-Redux.

npm install @reduxjs/toolkit react-redux

And now, you're ready to go!

Starting configuration

Let's start with what every project will need to properly set up Redux Toolkit, a store:

// app/store.ts

import { configureStore } from '@reduxjs/toolkit'

export const store = configureStore({
  reducer: {}
})

export type AppDispatch = typeof store.dispatch
export type RootState = ReturnType<typeof store.getState>

We created a store, but in fact, configureStore also has the Redux Dev Tools enabled, which in previous versions you needed to put in some "weird" code to enable it. Also reducer will do the job of the old combine reducers.

The last two lines are for TS users, with that when you add more reducers, it will automatically infer the type and you can get information and type check when using/consuming/dispatching the store so, if your buddies implement more state logic, you don't need to go into the reducers to check how to use it, TS will cover you with a nice IntellIsense.

Now let's connect Redux and React:

// pages/_app.tsx

import { AppProps } from 'next/app'
import { Provider } from 'react-redux'

import { store } from 'app/store'

import 'styles/globals.css'

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <Provider store={store}>
        <Component {...pageProps} />
    </Provider>
  )
}

export default MyApp

As I'm using NextJS I'm going to add the same example in React:

// src/index.tsx

import React from 'react'
import ReactDOM from 'react-dom'
import { Provider } from 'react-redux'

import App from './App'
import store from './app/store'

import './index.css'

ReactDOM.render(
  <Provider store={store}>
    <App />
  </Provider>,
  document.getElementById('root')
)

And with that we've done our setup!

For TS users there is one more step in this setup, yes, I know what JS users will be thinking right now, see, TS needs more steps, I don't want that! I can promise that this will pay off when we use Redux in our components.

So, React-Redux has hooks, the problem is that the generic versions of useSelector and useDispatch don't know the types and capabilities of our application, but we can create custom versions that do:

// app/hooks.ts

import { TypedUseSelectorHook, useDispatch, useSelector } from 'react-redux'

import { RootState, AppDispatch } from 'app/store'

export const useAppDispatch = () => useDispatch<AppDispatch>()
export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector

Later on in our components we will use these custom versions that are fully aware of the types we are handling in our application instead of the generic versions provided by react-redux. As you can see, we are providing the types we created earlier in the store file.

Redux State Slice

We are going to create our first slice, in previous versions of Redux at this point you will create a reducer and actions for your desired feature, which in this case will be the Cart of our Pokemon TCG shop that will contain the different cards that we place in the cart to buy them later in a purchase process.

In Redux Toolkit we will create a slice that will contain all the logic and data of a portion of our Redux state, in this case the portion referring to the cart:

// features/Cart/cart-slice.ts

import { createSlice, PayloadAction } from '@reduxjs/toolkit'

import { IPokemonCard } from 'components/Card'

export interface IStoredPokemonCard extends IPokemonCard {
  uuid: string
}
interface CartState {
  cards: IStoredPokemonCard[]
}

const initialState: CartState = {
  cards: [],
}

const cartSlice = createSlice({
  name: 'cart',
  initialState,
  reducers: {
    addItem(state, action: PayloadAction<IStoredPokemonCard>) {
      const pokemonCard = action.payload

      state.cards.push(pokemonCard)
    },
    removeItem(state, action: PayloadAction<string>) {
      const pokemonCardUUID = action.payload
      const cards = state.cards.filter(({ uuid }) => uuid !== pokemonCardUUID)

      state.cards = cards
    },
  },
})

export const { addItem, removeItem } = cartSlice.actions
export default cartSlice.reducer

Let's analyse what happens:

createSlice is our main function to create the slice.
PayloadAction is a TS type to check what is coming from the component.
initialState will be the initial state of this slice when it is created, in this case, an empty array of Pokemon cards.
The name which, as we will see later, will be used to name different things as well as being the unique identifier of the slice.
reducers will contain the update logic for our part of the shop, in this case how we handle adding new cards to the cart, and removing them.
cartSlice.actions is what we were putting in the actions file so far, but with createSlice they are created automatically.

It is also worth mentioning that in the different reducers we are not returning anything and we are writing code that seems to be directly mutating the state, in previous versions of Redux we would have written something like this:

reducers: {
    addItem(state, action: PayloadAction<IStoredPokemonCard>) {
      const pokemonCard = action.payload

            return {
                ...state,
                cards: [...state.cards, pokemonCard]
            }
    },
    removeItem(state, action: PayloadAction<string>) {
      const pokemonCardUUID = action.payload

      return {
                ...state,
                cards: state.cards.filter(({ uuid }) => uuid !== pokemonCardUUID)
            }
    },
  },

And that's right, that's how you should write immutable code, but Redux Toolkit uses under the hood the library Immer which will handle the changes and take care of the immutability for you.

Now update the store to contain our shiny new slice:

// app/store.ts

import { configureStore } from '@reduxjs/toolkit'

import cartReducer from 'features/cart/cart-slice'

export const store = configureStore({
  reducer: {
        cart: cartReducer,
    }
})

export type AppDispatch = typeof store.dispatch
export type RootState = ReturnType<typeof store.getState>

Client State

So far we have a store set up and we have already made a slice that contains the logic and data for our cart function, let's use what we have so far to make the Cart.

As it is a long component, I will put an example, you can see the complete code in the example project

// features/cart/Cart.tsx

// import { useDispatch, useSelector } from 'react-redux'
import { useAppDispatch, useAppSelector } from 'app/hooks'
import Card from 'components/Card'
import { removeItem } from './cart-slice'

export default function Cart() {
  const { cards } = useAppSelector((state) => state.cart)
  const dispatch = useAppDispatch()

  const totalPrice = cards
    .reduce((acc, card) => acc + card.cardmarket.prices.averageSellPrice, 0)
    .toFixed(2)

  return (
    <div>
      <div>Total Price: {totalPrice}</div>
      {cards?.map((card) => (
        <Card
          flavor="item"
          key={card.uuid}
          {...card}
          onRemove={() => dispatch(removeItem(card.uuid!))}
        />
      ))}
    </div>
  )
}

We use useAppDispatch and useAppSelector instead of the generic react-redux versions, this is for TS users only.
We extract the cards from the state.cart.
The cards have access to the removeItem action.

If you inspect what happens with React Dev Tools you will see that the name of the slice is also used for the different actions created automatically:

This completes a basic example of how to manage client state with Redux.

RTK Query and how to manage server state

We need to get the Pokemon cards from the API, so this is the perfect time to explain how to use RTK Query and what improvements this tool, which is part of Redux Toolkit, brings.

We don't need to install anything else because RTK Query is inside Redux Toolkit, to use it:

import { createApi } from '@reduxjs/toolkit/query/react'

Let's see this in action while fetching the Pokemon TCG API:

// features/pokemonTCGAPI/pokemon-tcg-api-slice.ts

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

import { ORDER_BY } from './OrderBy'
import { IResponse } from './types'

interface IQueryParams {
  name?: string
  page?: number
  pageSize?: number
  orderBy?: string
}

export const apiSlice = createApi({
  reducerPath: 'pokemon-tcg-api',
  baseQuery: fetchBaseQuery({
    baseUrl: 'https://api.pokemontcg.io/v2',
  }),
  endpoints(builder) {
    return {
      fetchCards: builder.query<IResponse, IQueryParams | void>({
        query({
          name = '',
          page = 1,
          pageSize = 20,
          orderBy = ORDER_BY.SET_RELEASE_DATE,
        }: IQueryParams) {
          const queryName = name ? `&q=name:${name}` : ''
          return `/cards?page=${page}&pageSize=${pageSize}&orderBy=${orderBy}${queryName}`
        },
      }),
    }
  },
})

export const { useFetchCardsQuery } = apiSlice

Take a look at what's inside createApi:

reducerPath will be the name of where we store the data in the store, and will be used for a few more things we'll see later.
baseQuery specifies how to get the data, in this case fetchBaseQuery is already built into RTK Query and is a wrapper around fetch, we also specify a baseUrl which will be used in the different queries.
The endpoints object will return an object with the different endpoints available, RTK Query will auto-generate the hooks for those endpoints as you see in the last line for useFetchCardsQuery.

In this case, there is only one endpoint to get the fetchCards which will call https://api.pokemontcg.io/v2/cards with a bunch of parameters to perform the search.

Under the hood RTK Query has generated for us the reducer, the actions and everything we need to set it up and use it, this would be the equivalent of adding thunk in an earlier version of Redux and you'll see how much simpler it is now.

First we need to add a new reducer and configure the middleware:

// app/store.ts

import { configureStore } from '@reduxjs/toolkit'

import cartReducer from 'features/cart/cart-slice'
import { apiSlice } from 'features/pokemonTCGAPI/pokemon-tcg-api-slice'

export const store = configureStore({
  reducer: {
    cart: cartReducer,
    [apiSlice.reducerPath]: apiSlice.reducer,
  },
  middleware: (getDefaultMiddleware) => {
    return getDefaultMiddleware().concat(apiSlice.middleware)
  },
})

export type AppDispatch = typeof store.dispatch
export type RootState = ReturnType<typeof store.getState>

We import the apiSlice of our newly created slice.
Using the previously configured reducerPath we name the reducer and as I said before, the reducer is provided automatically.
Finally, we have to extend the capabilities of the default middleware with the one generated by RTK Query.

And that's it, now it's time to see RTK Query in action right in our code, I'm going to put a small example but you can check the full code:

// pages/index.tsx

import { useState } from 'react'

import { useFetchCardsQuery } from 'features/pokemonTCGAPI/pokemon-tcg-api-slice'
import { ORDER_BY } from 'features/pokemonTCGAPI/OrderBy'

export default function Home() {
  const [inputName, setInputName] = useState('')
  const [name, setName] = useState('')
  const [page, setPage] = useState(1)
  const [pageSize, setPageSize] = useState(20)
  const [orderBy, setOrderBy] = useState(ORDER_BY.AVERAGE_SELL_PRICE)

  const { data, isFetching, isLoading, isError } = useFetchCardsQuery({
    name,
    page,
    pageSize,
    orderBy,
  })

  if (isFetching || isLoading) return <div>Loading...</div>

  if (isError) return <div>Error</div>

  return (
    <div>
      {data &&
        data.data.map((card) => {
          return <div key={card.id}>{card.name}</div>
        })}
    </div>
  )
}

As you can see, we use the useFetchCardsQuery that we generated earlier and return:

data which will have the response from the API call.
isFetching and isLoading will be our old friend LOADING action.
The isError will be the ERROR action.

The query will be called automatically when the component is mounted, if you don't want that behaviour, in the pokemon-tcg-api-slice you can also export a function called useLazyFetchCardsQuery that will be called when you call the trigger method.

const { data, isFetching, isLoading, isError, trigger } = useLazyFetchCardsQuery({
    name,
    page,
    pageSize,
    orderBy,
  })

Along with the query, we pass a bunch of parameters that if at some point they change, the query will trigger again and will be stored in the cache.

An easy way to check the benefits of caching, is to try paging backwards, you will notice that the results are not fetched again and so the load time is almost 0.

Conclusion

If you, like me, at some point jumped ship from Redux to try other things, now is the perfect time to give it a try again. I still maintain a few projects with react-query + React Hooks and I'm happy with that solution, but I think most of my concerns about using Redux are gone.

In case you are jumping into React and/or state management I think it would be better to build small projects purely with React Hooks first and experiment with what problems you will encounter to better appreciate things like Redux Toolkit or react-query.

Outside there are more solutions for state management like Zustand, MobX and Recoil to name a few, so even if you have experience (or not) with those tools I would love to hear your feedback and experiences with state management!

How Every Web Developer Can Become FullStack With Node.js

dastasoft — Fri, 10 Sep 2021 15:05:09 +0000

I'm sure you've heard of Node.js but maybe you haven't delved into it or you only have a general idea of what it is and what it's for. I want to explain what Node is and why you should use it, especially if you are in web development and want to expand your tool belt or your job opportunities. We are also going to see why to use some libraries and frameworks that are built on top of Node to make our life easier and our code cleaner.

Through this guide we will see what Node and Express is and how it works, build a REST API to store and retrieve data, test endpoints and upload our application.

By the end of this series you will have a complete overview of the MERN stack (MongoDB, Express, React and Node) and testing skills.

Roadmap

I want to give you also a roadmap of this series, the idea is that starting from a basic knowledge of Node and Express, we will see how to store and retrieve data from the server but for now using only the file system. In future guides we will see how to transform this into a real database data retrieval/storage and even how to deploy to the cloud.

In this series we will also create a React application that will use this back-end we are creating now. If you use or have just started using Next.js you may have noticed that Next.js comes with a Node "inside", the api.js. I think it is important to experiment with flat Node before you first encounter it inside Next.js but we will see how much of the code we are building today is reused in a project built with Next.js too.

TypeScript

In the sample project I will be using TypeScript instead of plain JavaScript, you can follow it without worries because the syntax is quite similar but if you wonder why you should bother dealing with TS instead of JS I recommend you read my last post.

My last post was for TypeScript on the front-end but everything explained there is applicable here. If in the front-end TS is useful in the back-end it is even more useful because back-end development usually has more logic and let's say more critical than front-end development, but take this statement with a grain of salt.

Resources

Project Sample

In this guide we are going to work on a simple REST API that stores and retrieves data from JSON files stored on the server. This REST API is intended to build a job posting application, where users can enter a company, and different job postings.

What is Node.js?

As you know, we are divided into front-end and back-end, until Node.js was released, if we think of JavaScript it was directly targeted at front-end development.

With Node.js, we can run JavaScript on the server side or even directly on a computer. Well, technically a server is a computer, but you get the point. But JavaScript only runs inside the browser, so how can it now run directly on a computer? Node.js is mainly built in C++, Node inside has Google's V8 engine, this engine converts the JavaScript directly into native machine code.

So basically you write your normal JavaScript, which Node passes to V8 which generates machine code and the computer is able to read that code.

But Node is much more than a bridge between your JS and V8, through different modules Node allows us, to give some examples, to communicate with the computer's file system or to set up a server that reacts to requests and serves content from/to a database.

That's great but, I'm a web developer who doesn't intend to write applications for Windows or any other OS, how do you put Node.js on the server and replace my fancy Java Spring Boot + Hibernate dynamised with Lombok annotations?

You'll send a request to the server, from your React or whatever front-end you have, on the server we have a Node.js running that will listen to the request and make a response back to the client. That response, it can be a file, because we have access to the file system, like a full HTML and image or any other binary data.

It can also communicate with a database, retrieve some data, do some calculations and give us back a beautiful JSON ready to use in our front-end.

Why to use Node.js?

It's all JavaScript → Even if you look at this from the perspective of your own or the point of view of a company it is still true, just one language and you can make a complete application, both sides. For you it's interesting, reusing your current skills with a language in another field, but for companies this is a good point too, they can reuse the current expertise of their workers.
It's all JavaScript x2 → Because both sides are JavaScript, it's very possible to reuse code between both sides, do you already have a function that validates ID cards? Use exactly the same on the front-end and back-end.
Community → There are a lot of utilities, packages and even frameworks built on top of Node.js, you will get a lot of support and there are tons of ready to use tools available.
It's highly used → Take a look at this screenshot from State of JS 2020, Express which is built on top of Node.js is in a terrible shape. But yes, the "everyone uses it" argument should be taken very carefully.

Setup

The easiest way to install Node.js on your system is to go to the official website, especially https://nodejs.org/en/download/current/ where all the platforms and options are listed. You can choose between the Long Term Support or the latest version, choose what you want, for the case of this guide both options are good, personally I am using the current version which is 16.5.0.

For Windows and Mac there is no mystery with the installation so if you are Linux user like me, you will find this resource more useful.

For example for Ubuntu users:

curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs

Installing Node.js also installs npm which stands for Node Package Manager, if you come from web development you are more than used to using it.

To check that everything is OK, run the following commands in your terminal

node --version
npm --version

If you type node in your terminal, you will be able to execute JavaScript code in the same way as you do in a Developer Tools inside the browser. If you want to exit, type .exit or use Ctrl+C.

Open your favourite IDE and create a server.js file (the name is totally up to you), in this JS file you can write your normal JavaScript and run it by typing node server on your terminal.

Congratulations, you are now running JavaScript code outside the browser!

Differences running JS on Front and Back

As we have already seen Node.js allows us to execute JavaScript in the back-end of our project but as that JavaScript is executed outside the browser there are some minor differences.

Global Object

In the front-end our global object is the window object, if you inspect that object you will find a number of utilities and variables such as the fancy window.document.getElementById. In Node.js the window object is replaced by the global object.

Use your server.js file created earlier to make console.log(global) and check what's inside. You'll find some familiar functions like setTimeout or setInterval.

console.log(global);

/* <ref *1> Object [global] {
  global: [Circular *1],
  clearInterval: [Function: clearInterval],
  clearTimeout: [Function: clearTimeout],
  setInterval: [Function: setInterval],
  setTimeout: [Function: setTimeout] {
    [Symbol(nodejs.util.promisify.custom)]: [Getter]
  },
  queueMicrotask: [Function: queueMicrotask],
  performance: [Getter/Setter],
  clearImmediate: [Function: clearImmediate],
  setImmediate: [Function: setImmediate] {
    [Symbol(nodejs.util.promisify.custom)]: [Getter]
  }
} */

If you look closely, you'll miss a few things, such as the fact that Node doesn't have a document object or any of the other objects related to DOM manipulation.

As in the front-end, you don't need to type global every time you need to access something inside this object, you can use setTimeout directly instead of going to global.setTimeout.

dirname and filename

There are two new utilities available in global that you will use a lot:

__dirname will tell you the path to the directory in which the current script is running.
__filename returns the name and absolute path of the currently running script.

console.log(__dirname); // /workspace/my-new-project
console.log(__filename); // /workspace/my-new-project/server.js

Splitting Code

If you want to split your code into different files you might be used to import and export from ES6 JavaScript, in Node it's also possible but a lot of the code you'll find on the internet will be with commonJS modules so I think it's important to know that too.

To export members from your current module to others you can use these options:

// module1.js
const name = "dastasoft";
const ultimate = "instant sleep";

module.exports = { name, ultimate };

// module2.js
const animes = ["Death Note", "Jujutsu Kaisen"];

module.exports = animes;

// module3.js
module.exports.today = () => new Date().getDay();

The difference is not only the number of parameters you want to export, but how you use the values:

// module4.js
const { name, ultimate } = require("/module1");
const animes = require("./module2");
const aFunction = require("/module3");

console.log(name); // dastasoft
console.log(ultimate); // instant sleep
console.log(animes); // ["Death Note", "Jujutsu Kaisen"]
console.log(aFunction.today()); // 5

As you can see instead of importing we use require as a keyword to include other modules. The module is just a simple JavaScript variable that is included in all Node modules.

If you try to use ES6 modules you will most likely get the following error:

(node:22784) Warning: To load an ES module, set "type": "module" in 
the package.json or use the .mjs extension.(node:22784) 
Warning: To load an ES module, set "type": "module" in the package.json 
or use the .mjs extension.

There are different ways to solve this:

Using the .mjs extension for files you want to use and consume as a module.
Setting the type to module in your package.json.
Using TypeScript and in the tsconfig.json set the module to commonjs so the TS you write will be transformed into JS using commonjs and Node will be happy with that.

Built-in modules

Along with Node there are some utility modules that you can use without any additional installation, let's see some examples:

OS

The operating system module provides a lot of information about the system it is running on:

const os = require("os");

console.log(os.arch()); // x64
console.log(os.version()); // #86-Ubuntu SMP Thu Jun 17 02:35:03 UTC 2021
console.log(os.platform()); // linux

FS

The filesystem module is one of Node's game changers, you can access the filesystem and perform a lot of actions.

Let's create a filesystem.js to do some testing with the filesystem module:

// filesystem.js
const fs = require("fs");

fs.readFile("./assets/test.txt", (error, data) => {
  if (error) console.log(error);
  else console.log(data.toString());
});

If you do node filesystem you will get the following error message Error: ENOENT: no such file or directory, open './assets/test.txt'.

Create a folder called assets and a test.txt file with some content in it, try again.

Let's add a writeFile function:

// filesystem.js
const fs = require("fs");

fs.readFile("./assets/test.txt", (error, data) => {
  if (error) console.log(error);
  else console.log(data.toString());
});

fs.writeFile("./assets/test.txt", "I'm soooo fast", () => {
  console.log("Done sir");
});

If you try this code, you will see that before you can read the file it is already written with the new text and when readFile does its job it prints the new content. This happens because these two methods are asynchronous and do not block the execution of the code, the code continues to execute line by line and writeFile terminates first.

This is one of the key points of Node.js and the reason why many large companies are looking for Node, its asynchronous nature and non-blocking I/O. With this your server can receive a lot of requests without blocking the application. Node has a library called libuv which is multithreaded, it will handle all the asynchronous processes that Node's single thread cannot and return the response.

Try this code instead:

console.log(fs.readFileSync("./assets/test.txt").toString()); // I'm soooo fast

fs.writeFileSync("./assets/test.txt", "I'm actually faster");

Now you are using the synchronous methods and the code is enclosed in those statements.

FS allows a lot more actions but you have the basic idea, with this module we can, for example, read a file, do some calculations, modify it and return its content to the front-end.

http/http

With these modules we can configure our Node as a HTTP/HTTPS server, this will be the module we will use to create the REST API.

// server.js
const http = require("http");

const HOSTNAME = "localhost";
const PORT = 3000;

const server = http.createServer((req, res) => {
  console.log(req);
  console.log(res);
});

server.listen(PORT, HOSTNAME, () => {
  console.log(`Server started on http://${HOSTNAME}:${PORT}`);
});

If you use node server and open a browser with localhost:3000 you will see in the server console those console.log which contain two useful parameters: the request and response objects. These objects contain some useful information that we'll look at in detail later, but for now you can take a look at what is printed.

We use the built-in http module.
The hostname from which the server will respond will be our localhost.
As a convention, port 3000 is used for local development, but you can use any port you like if it is available.
We use the createServer function.
We start the server with listen.

As you can see, the console.log is not printed to the browser console it is only printed to the server console, this is because we are running server code here, in the next section we will see how to send data to the front-end which will be the core of our REST API.

Creating a Server

// server.js
const http = require("http");

const HOSTNAME = "localhost";
const PORT = 3000;

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.write("Hello from the Server!");
  res.end();
});

server.listen(PORT, HOSTNAME, () => {
  console.log(`Server started on http://${HOSTNAME}:${PORT}`);
});

Now try accessing localhost:3000 in your browser and check the results.

We set up the server to respond (using the response object) to incoming requests with plain text, indicating a 200 status code and terminating the communication.

If you look closely at the example in the previous section, once you access localhost:3000 the browser never resolves the request, that was because we were not using end to notify the end of the communication.

Status Codes

If you do not know what status codes are see this list, in short the status code serves to notify whether the communication has been successful or what kind of problem has occurred.

Content Type

This header is used to tell the client what is the type of content returned. If you want to check the different types see this list.

Useful external packages

We already saw some useful built-in modules, but the community has developed tons of well-done packages worth mentioning and you will find many when you check the internet.

If you don't already, you can initialize your project with npm in your project folder:

npm init -y

This will generate a simple package.json which will be useful in the next sections and is necessary to install external packages.

nodemon

If you try to modify the code above with the server running, you will probably have noticed that the changes require a restart of the node process. The nodemon external package watches for changes to our files and applies them automatically without the need for a restart.

See the official nodemon page but in short

npm install -D nodemon

Install as a development dependency and configure your start script as follows:

"start": "nodemon server.js"

And execute it:

npm start

Your server will automatically react to changes.

Express

We will see this package in detail in the next section, for now let's say that Express is a web framework for Node, it simplifies the process of developing a web application and aims to build efficient and fast web applications. Express is also the E of the MEAN/MERN/MEVN stack.

You can achieve that result without Express or even with other packages but let's look at the advantages of this particular package.

To add Express to your project:

npm install express

Morgan

Morgan is an external package that is part of Express, this package allows us to log events in an easy and simple way, it is very convenient for these first steps to check what is happening in our server.

In the next section we will see how to use it, for now let's add it to our project:

npm install -D morgan

One tip, when using an external package, even if you have seen it in a tutorial, make sure that it really solves a problem, for example body-parser is a package that is present in almost all such guides but Express really has its own solution nowadays.

Express

As we saw in the last section we will use Express in our project but I think the most important thing when you add a new package to your project is to know why and what problem it actually solves.

We are going to build a simple REST API as an example. You can achieve this behavior without installing Express and just using Node.

First let's create a database folder and a companies.json inside it, this file will act as a simple database.

// companies.json
[
  {
    "id": "0",
    "name": "Capsule Corp",
    "about": "Like WinRAR but we accept more file extensions.",
    "industries": ["automobile", "house", "engineering"],
    "numberEmployees": 2,
    "yearFounded": 1990
  },
  {
    "id": "1",
    "name": "Red Ribbon",
    "about": "We deliver the best Android you can ever had",
    "industries": ["militar", "artificial intelligence", "engineering"],
    "numberEmployees": 2000,
    "yearFounded": 1000
  }
]

// server.js
const fs = require("fs");
const http = require("http");

const HOSTNAME = "localhost";
const PORT = 3000;
const DB_PATH = `${__dirname}/database/companies.json`;

const getCompanies = res => {
  fs.readFile(DB_PATH, (error, data) => {
    if (error) {
      console.error(error);
      res.statusCode = 500;
      res.end();
    } else {
      res.setHeader("Content-Type", "application/json");
      res.statusCode = 200;
      res.end(data);
    }
  });
};

const deleteCompany = (res, id) => {
  fs.readFile(DB_PATH, (error, data) => {
    if (error) {
      console.error(error);
      res.statusCode = 500;
      res.end();
    } else {
      const companies = JSON.parse(data);
      const filteredData = JSON.stringify(
        companies.filter(company => company.id !== id),
        null,
        2
      );

      fs.writeFileSync(DB_PATH, filteredData);

      res.setHeader("Content-Type", "application/json");
      res.statusCode = 200;
      res.end(filteredData);
    }
  });
};

const server = http.createServer((req, res) => {
  const baseURL = "http://" + req.headers.host + "/";
  const url = new URL(req.url, baseURL);

  if (url.pathname === "/companies" && req.method === "GET") {
    getCompanies(res);
  } else if (url.pathname === "/companies" && req.method === "DELETE") {
    deleteCompany(res, url.searchParams.get("id"));
  } else {
    res.statusCode = 404;
    res.end();
  }
});

server.listen(PORT, HOSTNAME, () => {
  console.log(`Server started on http://${HOSTNAME}:${PORT}`);
});

Starting with the createServer as before we set up a server that listens for requests and depending on the URL and method used executes one logic or another.

Within the two different methods we read the JSON file and return the content, in deleteCompany we look for a specific Company and filter the array and write to the file while returning the resulting array.

If you want to try the previous example, I recommend you to use Postman, an application that we will see in detail later, with which you can execute different requests to a specific endpoint using different methods.

As you can see, the REST API above is incomplete, we only have the get, delete and not found endpoints, but it's enough to see some advantages of using Express, so let's compare it with an Express version of the same application.

Create a new file app.js:

// app.js
const express = require("express");
const fs = require("fs");

const HOSTNAME = "localhost";
const PORT = 3000;
const DB_PATH = `${__dirname}/database/companies.json`;
const app = express();

const getCompanies = (req, res) => {
  fs.readFile(DB_PATH, (error, data) => {
    if (error) {
      console.error(error);
      res.status(500).end();
    } else {
      res.status(200).send(JSON.parse(data));
    }
  });
};

const deleteCompany = (req, res) => {
  const { id } = req.params;

  fs.readFile(DB_PATH, (error, data) => {
    if (error) {
      console.error(error);
      res.status(500).end();
    } else {
      const companies = JSON.parse(data);
      const filteredData = JSON.stringify(
        companies.filter(company => company.id !== id),
        null,
        2
      );

      fs.writeFileSync(DB_PATH, filteredData);
      res.status(200).send(JSON.parse(filteredData));
    }
  });
};

app.get("/companies", getCompanies);

app.delete("/companies/:id", deleteCompany);

app.use((req, res) => {
  res.status(404).send("Not found");
});

app.listen(PORT, HOSTNAME, () => {
  console.log("Server running");
});

Let's check the differences between the two versions.

Server listening

The server does not need to specify the default value of localhost.

You can also use an extended version:

app.listen(PORT, HOSTNAME, () => {
  console.log("Server running");
});

Routes

As you can see the routes section is simplified, cleaner and more readable. Each route is declared with a function that uses the same name as the method being used, e.g. the endpoint to list all companies is a get method and the endpoint to delete a particular company is a delete method.

All routes accept a function that receives the request and response objects:

app.get("/companies", (req, res) => {
  // Do something
});

With this in mind we can isolate that logic within a function and pass the function directly:

// app.get("/companies", (req, res) => getCompanies(req, res));
app.get("/companies", getCompanies);

For the deletion endpoint, we need to know the id of the Company, for that we can use identifiers with : those identifiers will travel under req.params.identifierName where identifierName is id in this case.

Finally, in case someone tries to access a route we don't have defined, we define 404 Not Found. The app.use method is a special method that we will cover in the next section.

Response

In the Node version we send back and end the communication with end method which still it's available but Express allows us to do in a simpler way:

res.send(data);

send will automatically set the Content-Type for us.

Status codes

Setting status codes is also easier with Express, most of them will be handled automatically by Express, but if you need to define something explicitly:

res.status(200).send(data);

Middlewares

Remember the app.use we saved for later? Now is the time. Try pasting the app.use lines at the beginning of the file, put them before the other routes and see what happens when you make a request.

// app.js

app.use((req, res) => {
  res.status(404).send("Not found");
});

app.get("/companies", getCompanies);

app.delete("/companies/:id", deleteCompany);

app.listen(PORT, HOSTNAME, () => {
  console.log("Server running");
});

As you can see, now every request is responding with Not found because use is catching all requests and doing an action. Now remove that and try these statements at the top of the file:

// app.js

app.use((req, res, next) => {
  console.log("I'm watching you");
  next();
});

app.get("/companies", getCompanies);

app.delete("/companies/:id", deleteCompany);

app.use((req, res) => {
  res.status(404).send("Not found");
});

app.listen(PORT, HOSTNAME, () => {
  console.log("Server running");
});

Now every request prints I'm watching you first but executes correctly. To understand why this happens you first have to learn about middlewares.

Middleware functions have access to the request and response object and are executed on every execution between a request and a response. If you think about the definition you come to the conclusion that the whole Express is made up of middleware functions, not just app.use.

The difference with other functions like app.get or app.delete is that those functions are limited to those methods, but app.use is executed with any request.

Middleware functions have two possible exits, continue to the next middleware function using next or make a response and terminate the chain.

In the diagram above you can see the following:

A request arrives at the server.
The first app.use is executed and performs next.
The second app.use is executed and performs next.
The request was a get method that asked for the path /, so the app.get executes and sends a response.

Sending a response is what breaks the middleware chain so it is important to note the order.

Built-in middlewares

It is likely that if you are building a front-end that submits data to a REST API, to submit a form for example, you will need to read those values. In the past, to do this we used an external middleware called body.parser to read these values from the req.body. Nowadays this is already integrated in Express and is one of the built-in middlewares.

app.use(express.urlencoded({ extended: true }));

External middlewares

There are lots of external packages for Express, but earlier I mentioned morgan, this package is just an external middleware that if I show you now how to use it you will understand the idea perfectly:

import morgan from "morgan";

app.use(morgan("dev"));

Extending the capabilities of Express with external middleware as you can see is simple and clean.

Best practices

MVC

MVC stands for Model-View-Controller and is a well-established software design pattern in different systems that can be useful here as well. A graphical summary of what MVC is:

At this stage of the tutorial we will only use the Controller, the Model we will add later when we define a model for the database and the View in this case is not applicable because we are not serving HTML from the server, the view will be our React application in any case.

Even the lack of certain parts, splitting our code following the MVC pattern is useful for readability and maintainability purposes, so let's isolate all the different functions for manipulating data that we have seen before in the controller.

Under the controller folder, we'll place the company.js and joboffer.js files, with code similar to the following: (check out the example project for the full code)

// controller/company.js
import path from "path";
import fs from "fs";

const DB_PATH = path.resolve("database/companies.json");

const list = (req, res) => {
  fs.readFile(DB_PATH, (error, data) => {
    if (error) {
      console.error(error);
      res.status(500).end();
    } else {
      res.status(200).send(JSON.parse(data));
    }
  });
};

const delete = (req, res) => {
  const { id } = req.params;

  fs.readFile(DB_PATH, (error, data) => {
    if (error) {
      console.error(error);
      res.status(500).end();
    } else {
      const companies = JSON.parse(data);
      const filteredData = JSON.stringify(
        companies.filter(company => company.id !== id),
        null,
        2
      );

      fs.writeFileSync(DB_PATH, filteredData);
      res.status(200).send(JSON.parse(filteredData));
    }
  });
};

export { list, delete }

*The other methods can be found in the example project.

By doing so, we have isolated the code relating to working with the data in a single file, which we can then reuse as needed, as in the next section.

Routes using router

There is a better way to organise the routes, especially now that we want to add another context, so far we only talked about routes about company but now we want to add routes for job offer. Let's use the router to organise the routes in a better way.

Inside the routes folder, we'll place two files company.js and joboffer.js, which will contain something similar to this code: (check the example project for the full code)

// routes/company.js
import express from "express";

import { list, create, details, update, remove } from "../controller/company";

const router = express.Router();

router.get("/", list);
router.post("/", create);
router.get("/find/:id", details);
router.put("/:id", update);
router.delete("/:id", remove);

export default router;

Let's check what happens there:

We use the Router function of Express.
With the router, we can add routes in the same way as we did with app.
Finally we export the router.

Later, we can use this router to define all routes:

import express from "express";

import { companyRoutes, jobOfferRoutes } from "../routes";

const app = express();

// routes
app.use("/company", companyRoutes);
app.use("/job-offer", jobOfferRoutes);

With app.use we define a context for that path (this is entirely optional) and add the paths we defined earlier. The advantage of using the context is that the routes in the example above are simpler and easier to move between contexts.

So instead of declaring all your routes in your app.js or whatever main file you have, isolate them in their own files, it will be easier and less error prone for other developers to modify in the future.

TypeScript

As I said at the beginning of this guide, TS can be useful in this project, and if you check the example project is entery in TS, in later stages of the guide it will be even more useful because of the type checking of the model, but for now here are some benefits:

Clear data structure

// types.ts

type Company = {
  id: string;
  about: string;
  industries: string[];
  name: string;
  numberEmployees: string;
  yearFounded: number;
};

type JobOffer = {
  id: string;
  availablePositions?: number;
  companyId: string;
  description: string;
  function: string;
  industry: string;
  location: string;
  numberApplicants?: number;
  postDate: Date;
  published: boolean;
  requirements: string[];
  salary?: number;
  workType: string;
};

export { Company, JobOffer };

Declaring the types of our objects gives us, and other developers, a snapshot of what we are talking about. Looking at a single file, you now have a clear picture of the form of the data, which parameters are mandatory and which are optional.

This will be even more useful later, but for now we can use these types in the controller to implement less error-prone functions, use IntelliSense efficiently and include these types in our tests.

Readable code

Let's check for an updated version of the remove function in the company's controller:

// controller/company.ts
import { Request, Response } from "express";
import path from "path";
import fs from "fs";

import { Company } from "../types";

const DB_PATH = path.resolve("database/companies.json");

const remove = (req: Request, res: Response) => {
  const { id } = req.params;

  const companies: Company[] = JSON.parse(fs.readFileSync(DB_PATH).toString());
  const company: Company | undefined = companies.find(company => company.id === id);
  const newCompanies: Company[] = companies.filter(company => company.id !== id);

  if (company) {
    fs.writeFile(DB_PATH, JSON.stringify(newCompanies, null, 2), error => {
      if (error) {
        console.error(error);
        res.status(500).end();
      } else {
        res.status(200).send({ message: `Company with id ${id} removed.` });
      }
    });
  } else {
    res.status(404).send({ message: `Company with id ${id} not found.` });
  }
};

Most of the types are inferred and it is not necessary to write it explicitly, but I added it here so that it is better understood that we now know at each step what type of data we are handling and more importantly, the IDE is checking that it follows that form.

Better understand of external tools

Do you see this in the previous example?

import { Request, Response } from "express";

const remove = (req: Request, res: Response) => {}

Good luck finding out what is inside the req and res params, you will need to check the documentation or debug, with TS you will automatically have access to the object form and documentation, directly from the IDE, this is one of the main reasons why I am currently using TS in my projects.

Publish

Let's review what the different options are for publishing our backend so that it is accessible to others, due to the current size of the guide, I will keep this section as a summary but will consider making a more focused guide on this point if I feel it is necessary.

Local

On a basic scale you already have a local environment for your node server but it is not available outside your current local network, with this you may be able to test the server as we saw in the Postman section.

Nowadays it is less common to want to use your local machine as a server, and if you prefer not to do that check the next sections, but if you want to expose your local node server to the world you can use ngrock, the introduction video on the landing page is self explanatory to be honest 😄

AWS

You can use Amazon Web Services to host your Node.js application, I will list the steps but I won't go into the details because using AWS requires some prior knowledge about AWS and is beyond the scope of this guide.

Request an Elastic Compute Cloud (EC2) instance with Ubuntu for example.
Update the system.
Install Node.js on the system as we did in the the Setup section for Ubuntu.
Clone your back-end project or the example project from git.
Perform npm install && npm start which will make the Node.js server available.

This is a simple step-by-step for this guide, there are actually better ways to deal with disconnects, restarts, and so on, check out pm2 if you are more interested in this part.

Be careful with this option because AWS has a free tier but may have additional charges for usage.

Heroku

One of the easiest options and the one I will cover here in more detail is to use Heroku. Heroku is a Platform as a Service (PaaS) that will simplify the process of having to configure your system to be visible from the outside and act as a server.

One of the cool things about Heroku is that we can do this kind of testing without any kind of credit card or fee, so it's perfect for a guide like this and your first tests developing backends with Node.js.

With the example project, I needed to add a postinstall script for TypeScript so that Heroku compiles down to JS code before starting the server.

There are two ways to upload a back-end project like the example project in this guide:

Heroku CLI

Heroku provides a command line interface that we can use to deploy the project in a few steps. First install the cli directly from npm:

npm install -g heroku

Once installed, we need to log in:

heroku login -i

If you want to verify that everything works before uploading to Heroku, you can check it with:

heroku local web

web will check your package.json and look for the start script.

Once everything is verified, let's create the project in Heroku and push it:

heroku create
git push heroku main

After create you will get the URL where it is stored and you are ready to go, if you are using the example project, you can try with your new url + /company for example. In my case https://mars-pot-backend.herokuapp.com/company.

Directly on the web.

Once logged into Heroku, in your dashboard select New and Create new app, you can choose a name and a region.
Then you can select your project from github and deploy a specific branch.
Once deployed, in Settings you can check the Domains section to see the url of your project, if you are using the example project, you can try your new url + /company for example. In my case https://mars-pot-backend.herokuapp.com/company.

For a successful deployment you must have a start script in your package.json in this case it will be the script to start the node server.

Railway

I found Railway during the process of this guide and I'm quite surprised, I try uploading the example project here and within seconds I have an instance ready to go, even with a provisioned MongoDB available but that's for the next iteration of this guide.

I haven't tested this option in depth but I will try it with future iterations of this series because it seems convenient.

BONUS

Postman

Throughout this guide you can test the different api rest endpoints directly in the browser or using curl but one tool that will make life easier for you and your co-workers is Postman.

One of the main benefits of using Postman with your co-workers or even on side projects for yourself is to easily define how to interact with your API, provide examples, and collaborate in the same workspace to maintain that collection.

There are also plenty of APIs available so you can test how things work and plan how to code anything before you start writing, for example the Twitter API workspace.

Testing endpoints

With the example project I also provide a Postman collection, you can use it as an example for your collection or to test the example project.

If you want to create a bunch of endpoints and test your own application, it's as easy as selecting the request method and url.

For endpoints that have to carry data to the server, they can be sent via params or the Body.

Postman provides a lot of information about the request and the response, so you won't miss anything from the Developer Tools Network tab:

Creating examples

Providing examples in the Postman collection is a fantastic way to ensure that your colleagues or collaborators can see the shape of the data without actually running anything, in a regular scenario this may not be necessary but when a service is behind a proxy, authentications or even the service is not yet avialable, it can be a good resource for developers to start coding their part.

To create a new example, click on the three dots at the endpoint you want to add an example and select Add example.

Environment variables

As in programming, you can isolate your constants in environment variables to share different configurations and make it easier to modify the collection or test endpoints with different environments.

In the sample project collection you can find variables to run the endpoints on your local or directly to the published version on Heroku. To use the environemnt provided to the Postman collection you must import the two jsons provided in the same folder which are *environment.json.

Explain Quantum Computers like I'm five

dastasoft — Wed, 18 Aug 2021 08:07:33 +0000

Explanation of Quantum Computers and the difference with regular computers.

Here's what every React Developer needs to know about TypeScript - Part 1

dastasoft — Fri, 28 May 2021 11:44:12 +0000

If you've been using React for a while, you'll have noticed some cases where the freedom and wild nature of JavaScript works against you (and not because of JS 😄), especially if you're working in a team. You may not know it, but you need TypeScript or at least, you need to test it.

Let me be clear, I love JavaScript and the freedom it provides, for a long time I was "against" TypeScript.

So I want to go on a journey together, figuring out if TypeScript is worth using or TS is only for people who don't know how to code properly (this was an inside joke in my team a time ago!).

The idea behind this article is to go through the basics of TS and understand the benefits so you can decide if you want those benefits or not, in a second part I will cover the specifics of TS with React.

Resources

If you want you can go directly to sample project or source code that is a very simple project to test the TypeScript developer experience without Webpack or any other add-ons, just plain TypeScript converted to JavaScript.

The other resources I provide in this article are boilerplates for React and NextJS:

If you like programming games, try PhaserJS you be able to make games for the browser with TypeScript and it's a fun way to learn TS.

Also be sure to check out The Official Handbook of TS with tons of useful documentation and examples.

Why ESLint, Prettier and Husky

On the boilerplates I use Airbnb's ESLint rules, Prettier's recommended rules and Husky's pre-commits actions, this will be very useful especially in a team environment where you need everyone to follow the same style of code, but you can also benefit as a solo developer or as a learner.

The Airbnb rules can be strange at some points, but they provide a great explanation and examples so you can decide if the rule makes sense for you or not, and if not you can disable it in the .eslintrc file.

I found that for junior profiles or people who are just starting out with JS or TS these rules are very useful, so I recommend you at least try to include them in a project and check the results 😉

What is TypeScript

TypeScript or TS is an open source language developed and maintained by Microsoft, TS is also:

A multi-paradigm language (like JavaScript).
An alternative to JavaScript (more precisely a superset)
Allows the use of static types
Extra features (generics, interfaces, tuples, etc which will be explained in detail below)
Allows for gradual adoption*.
Can be used for front-end and back-end development (just like JS)

*You can turn an existing project into a TS project by changing the files one by one, it's not a big bang change.

The browser does not understand TS code, it must be transcompiled into JS. JS has a dynamic type mapping value and TS has static types which is less error prone.

In React you already transcompile JS with Babel, so having to transcompile the code is not an extra inconvenience nowadays.

Why bother dealing with TS?

That's the thing, why bother with TS when you are happy with JS and everything is fine? A while back, as I said before we had an inside joke about languages like TS with types (I was doing Java at the time by the way), that you need types if you don't know how to code correctly.

TypeScript, Java and a bunch of other languages have static typing that will define a type associated with a variable and the type will be checked during compile time. Once you define something to be a string or a boolean you can't change its type.

JavaScript on the other hand has dynamic typing, you can assign a string to a variable, and later convert it to a boolean, a number or whatever you want, the type will be dynamically assigned at run time.

But when you look at the TS code on the Internet, you can see...

So going back to my team's old joke, yes indeed it was correct, if you know exactly what you're doing, you don't need someone constantly telling you that this is a string and only a string, and if at some point it becomes a boolean or something else.... I know what I'm doing!

But the truth is that we are not perfect, and things happen:

Work in a hurry.
Having a bad day.
Leaving an idea on Friday and when you come back on Monday you don't have the same picture of the situation.
Working in a team, and not everyone has the same level and/or vision.

For the same reasons we use an IDE, IDE extensions, syntax highlighting and linterns instead of the notepad app. TypeScript can fit into these aids.

Some mistakes in examples

Let's look at some basic examples with and without TS in the equation:

Please, I know what I'm using

// App.js
import { MemoryRouter as Router } from 'react-router-dom'

import Routes from './routes'

export default function App() {
  return (
    <Router basename="/my-fancy-app">
      <Routes />
    </Router>
  )
}

Do you see anything unusual in the code above? If so, congratulate yourself.

This file was in my boilerplate for a long time, it's not a bug but... MemoryRouter doesn't need any basename at all. This happens because at some point in the past BrowserRouter was used which in fact needs a basename property.

With TS you will be notified by No overload matches this call which tells you that there is no signature for that component with that property.

TypeScript not only works as static typing, but it helps you better understand the needs of other libraries, and by others I mean components and functions from third parties or your co-workers.

Yes I can hear the answer, you must properly know the libraries you are using, and again yes you are right but assuming that everyone involved in a project knows every "external" library and the nuances of the versions can be a daunting task.

The devil's flag

let isVerified = false;
verifyAmount();

// isVerified = "false"
if (isVerified) proceedPayment();

I have seen this error many times, I don't have the exact code and each time it has a different nuance but you can get the point, you have a boolean variable that is responsible for letting some code run or not and at some point someone else or maybe yourself in an error, turn the boolean into a string and a non-empty string is a true value.

With TypeScript you would have had the error: The type 'string' is not assignable to the type 'boolean' and this error will occur at compile time, even if you don't have your application running at the time, so the chances of the error making it to production are very small.

Again, we can apply the same rule as before, if you code correctly this doesn't happen, if you follow the rules of Clean Code and be careful with what you are doing this can also be avoided, TypeScript is not meant to allow us to be lazy and disorganized but it can be a good ally, as syntax highlighting can help to avoid some errors or detect unused variables.

I though the cat was alive inside that box

const MONTH_SELECT_OPTIONS = MONTHS.map((month) => ({
  label: getMonthName(month),
  value: month,
}))

export default function PaymentDisplayer() {
  const [currentMonthFilter, setCurrentMonthFilter] = useState(
    MONTH_SELECT_OPTIONS[0]
  )

  const onChangeHandler = option => {
    setCurrentMonthFilter(option.value)
  }

  return (
    <select onChange={onChangeHandler}>
      {MONTH_SELECT_OPTIONS.map(({ label, value }) => (
        <option key="value" value={value}>
          {label}
        </option>
      ))}
    </select>
  )
}

It is very common (and perhaps not recommended) to change the state's type, sometimes it is on purpose like having an isError flag and suddenly changing it from boolean false to error message string (and again not recommended at all!), but in other scenarios it is by mistake, like the example above.

The person who wrote this in the first instance thought that in currentMonthFilter he would store the actual option of the select, an HTMLOptionElement with label and value. Later, the same person on another day or perhaps another developer makes the changeHandler and sets the value instead of the full option.

The above example works, and is simplified for learning, but imagine this on a large scale, especially in those components where actions are passed underneath as props.

Here TypeScript would help us in two ways:

Static typing will throw an error when trying to change the type of currentMonthFilter from {label: string, value: number} to number.
The person coding the next step of calling a service to retrieve payments with that filter will know through IntelliSense what type they will get from the state and whether it matches the type the service needs.

So TypeScript also allows us to inspect from the IDE the different functions, parameters and documentation of third-party libraries and components of our peers.

Through these examples (which are perhaps not too representative to be honest) we can conclude that TypeScript tries to help us in a React environment with:

Being coherent in typing and consistent with static types
Providing documentation and IntelliSense of the available possibilities
Detecting bugs early

Setup TypeScript

In this article we will use the Global Installation, because I think it is better to first dive into TypeScript in isolation without any Webpack, React or any other variables and see how it works and what problems it solves, but let's see how to install in the different environments:

Installation with CRA (Create-React-App)

You can use the CRA template for TS with yarn create react-app my-app --template typescript
You can use the ready-to-go boilerplate provided in the resources section.

If it is an existing project, you can use the following command, and convert your js files to ts/tsx files.

npm install --save-dev typescript @types/node @types/react @types/react-dom @types/jest

# or

yarn add -D typescript @types/node @types/react @types/react-dom @types/jest

Installation with Nextjs

If you install TypeScript as a dependency, Nextjs will create a tsconfig file for you once you start it.
If you create a tsconfig file, Nextjs will provide instructions for installing TypeScript into the project once you start it.
You can use the ready-to-use boilerplate provided in the resources section.

npm install --save-dev typescript @types/node @types/react @types/react-dom @types/jest

# or

yarn add -D typescript @types/node @types/react @types/react-dom @types/jest

Global Installation

npm install -g typescript

#or

yarn install --global typescript

TypeScript Compiler (tsc)

Once you have installed TypeScript on your system or with any of the other options mentioned above, you can use the TypeScript compiler, the tsc command.

Let's test the compiler with the minimum configuration:

Create a new empty folder
Place an index.html with the basic HTML5 structure inside.
Create an empty index.ts file at the same level as index.html.
Open a terminal and type tsc --init (assuming you have installed global typescript) this will create for you a tsconfig.json (we will look at this file in detail in the next section).

You will have something like this:

- index.html
- index.ts
- tsconfig.json

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body></body>
</html>

Now you need to include the ts file in the HTML but, browsers don't understand TypeScript they understand JavaScript, so you can modify your index.html to:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body></body>
  <script src="./index.js"></script>
</html>

Open a new terminal and type tsc. Your index.ts file will be converted into an index.js that the browser can read.

Instead of typing the tsc command every time you want to compile the TS file into a JS file, you can put TypeScript in watch mode with tsc -w.

Now my recommendation is that you open both TS and JS files side by side, and type regular JS into the index.ts file, and test what the outputs are. (We'll use this a lot in the next sections to test what TS generates).

tsconfig.json

If you are following the article, you have created this file with the tsc --init command which creates the tsconfig.json with some default configuration and a bunch of comments which are great to start with.

Let's look at some of the properties that might be useful to get you started:

target is the version of JS we are converting our TS code to, depending on the browsers you want to support you may need to set some older version. It can be a good learning resource too, try playing with different versions and see what JS code is generated.
module defines what kind of syntax you will use for modules, commonjs which is the default uses require/module.exports and modern JS (ES6+) uses import/export.*
lib In React and Nextjs boilerplates I use this setting, you need it to specify additional libraries you will use in your project and check additional types, e.g. DOM related.
jsx In React you will need to set it to at least preserve this mode assumes that another tool will compile that part (Babel in this case) but TSC will do the type checking.**
outDir where the files will be placed after the compilation, for example in most React projects it will be placed in a build folder.
rootDir where the files will be taken for compilation, on most React projects this will be ./src
strict enables a set of rules for type checking which results in a stronger check for what is considered "correct", I recommend starting with this on false when you are learning and when you feel confident enough turn it on and check what new red flags you have, but remember you will get the full potential of TS with this option enabled. This option also enables all the strict options below, which you can disable individually.
include the folder(s) you want to include to be compiled, for example the src folder
exclude the folder(s) you want to prevent from being compiled, for example the node_modules folder.

*If you want to use import/export you need to change target to ES6 or higher, in the example project we will use this syntax so check the rest of the article for this.

**You can set this property to react or react-native this is used if you want TSC to compile your JSX code into regular JS code, in most cases we will leave this property to preserve which will send the file as regular JSX and Babel/Webpack will do the rest.

In the sample project for this article, we will take the files rootDir from ./src and will place it outDir in public folder.

Shopping List

The sample project is very basic stuff, you can insert different items and their quantities in different sections and later you can remove them while you shop and check what you have to buy next.

The idea behind this example project is to get used to TypeScript and the general workflow, because once you get into the React environment a lot of the magic is done for you by Webpack or any other bundler, so I think it's important to know the very basic things and later enjoy the work that the bundler does for us.

Let's see what we can use from TS to get a better, less error-prone code base.

Modules

If you want to use ES6 import/export modules you must configure tsconfig with:

target: es6 or higher
module: es2015 or more

And in the index.html file you must add the module type:

<script type="module" src="app.js"></script>

However, the use of modules has two drawbacks:

Compatibility with older browsers is less likely.
Files in production will be split, so you will have multiple requests for each file (this can be fixed by using a bundler like Webpack).

Types

In JavaScript types are assigned at runtime, when the interpreter sees your variable and the value, it decides what type it is, so we can do things like this:

let job = "Warrior"; // string
let level = 75; // number
let isExpansionJob = false; // boolean

level = "iLevel" + 75 
// now it's an string

In TypeScript types are assigned at compile time, so once the type is defined it will be protected under that signature.

let job: string = "Samurai";
let level: number = 75;
let isExpansionJob: boolean = true;

level = "iLevel" + 75 
// Error, Type string cannot
// be assign to type number!

Inference

In fact, it is not necessary to explicitly state the type you want the variables to be, TS can infer the type by their value.

let job = "Samurai";
let level = 75;
let isExpansionJob = true;

level = "iLevel" + 75 
// Error, Type string cannot 
// be assign to type number!

In React, which we'll look at in Part 2 of this article in detail, you'll see the inference as well, for example in useState

const [currentMonthFilter, setCurrentMonthFilter] = useState("January")

useEffect(() => {
   setCurrentMonthFilter(1) 
   // Error, Type number cannot 
   // be assign to type string!
}, [])

Any and Unknown

I have said all along that the TS has static types, but there is a nuance to that statement.

let level: any = 10;

level = "iLevel" + 125; 
// OK, still type any

level = false; 
// OK, still type any

Welcome back to JavaScript! any is a dynamic type for when you don't know what type the variable will be in the future but it somehow reverses all the advantages that TS provides.

let level: any = 10;

level = "iLevel" + 125;

level = false;

let stringLevel: string = level;
console.log(typeof stringLevel);
stringLevel.replace("false", "true");

When you assign level to stringLevel of type string it does not become a string, it is still a boolean, so the replace function does not exist and the code fails at runtime. Uncaught TypeError: stringLevel.replace is not a function

For that we have another type which is the safe counterpart of any type:

let level: unknown = 10;

level = "iLevel" + 125;

level = false;

let stringLevel: string = level; 
// Error

With unknown you can assign any type as in any but this time the compiler gets the error when you try to assign to another type. So if you don't know what type it will be, try using unknown instead of any.

Arrays

let job = "Red Mage";
let level = 75;
let isExpansionJob = false;
let jobAbilities = ['Chainspell', 'Convert'];

jobAbilities.push('Composure'); // OK
jobAbilities.push(2); // Error
jobAbilities[0] = 2; // Error

In the example above, we declared an array of strings jobAbilities, we can add more strings, but we cannot add other types or change the current values to values of other types, because in the declaration we have made the inference of type string[].

let job = "Red Mage";
let level = 75;
let isExpansionJob = false;
let jobAbilities = ['Chainspell', 'Convert'];
let swordSkill = ["B", 5, 144, 398]; 

swordSkill.push("B+"); // OK
swordSkill.push(230); // OK

swordSkill[1] = "C"; 
// OK, the type is not position related

swordSkill.push(true); // Error

As in the previous example, type inference is done in the declaration, we now declare an array of strings and numbers for swordSkill.

If you want to explicitly declare the types for the arrays we saw in the examples:

let jobAbilities: string[] = ['Chainspell', 'Convert'];
let swordSkill: (string | number)[] = ["B", 5, 144, 398];

By the way | is for doing an union of different types.

Objects

Let's go back to the example, but now in the form of an object:

let job = {
  name: "Summoner",
  level: 75,
  isExpansion: true,
  jobAbilities: ["Astral Flow", "Elemental Siphon"]
};

job.name = "Blue Mage"; // OK
job.level = "Four" // Error
job.avatars = ["Carbuncle"]; // Error

job.level = "Four" cannot be done because we cannot change the type of a property, properties has static types as well.
job.avatars = ["Carbuncle"] we cannot add new properties, the job object already has a type that has a defined structure.

let job = {
  name: "Summoner",
  level: 75,
  isExpansion: true,
  jobAbilities: ["Astral Flow", "Elemental Siphon"]
};

job = {
  name: "Blue Mage",
  level: 4,
  isExpansion: true,
  jobAbilities: ["Azure Lore", "Burst Affinity"]
}; // OK

job = {
  name: "Corsair",
  level: 25,
  isExpansion: true
}; // Error

We can assign another object, because we define the object as let but it has to be in the exact same form.

Take a moment and think, how many times do you repeat object structures in the front-end without any kind of check like this? How many times have you made a typo by typing data.descrption and days later you discover the bug? If not, I can promise you that this will happen sooner rather than later.

Let's check the explicit type of our example:

let job: {
  name: string;
  level: number;
  isExpansion: boolean;
  jobAbilities: string[];
} = {
  name: "Summoner",
  level: 75,
  isExpansion: true,
  jobAbilities: ["Astral Flow", "Elemental Siphon"]
};

As you can see, this gets a bit bigger for a simple object, so in this case we can use type aliases.

Aliases

type Job = {
  name: string;
  level: number;
  isExpansion: boolean;
  jobAbilities: string[];
};

let Summoner: Job = {
  name: "Summoner",
  level: 75,
  isExpansion: true,
  jobAbilities: ["Astral Flow", "Elemental Siphon"]
};

let BlueMage: Job = {
  name: "Blue Mage",
  level: 4,
  isExpansion: true,
  jobAbilities: ["Azure Lore", "Burst Affinity"]
};

With type aliases we can define a common type for reuse. In React, DOM and other libraries you will find a lot of ready-to-use defined types.

Functions

The syntax of the functions is quite similar to JS, but you can specify the type of the parameter and the type of the return.

type Enemy = {
  name: string;
  hp: number;
  level: number;
  exp: number;
};

let attack = (target: Enemy) => {
  console.log(`Attacking to ${target.name}`);
};

attack = "Hello Enemy"; // Error

I use an arrow function, but you can also use normal function declarations. There are two different things for functions between JS and TS:

You specify the type of the parameters you pass to the function, like our target: Enemy.
The variable attack is given the type of the function's return, so you cannot change its type afterwards.

The type of the function is described as follows:

let attack = (target: Enemy): void => {
  console.log(`Attacking to ${target.name}`);
};

The void type is used when the return type is nothing, and it is also not necessary to explicitly set the type:

// let attack = (target: Enemy): number => {
let attack = (target: Enemy) => {
  return target.hp - 2;
};

As with any the void type has some nuances:

let attack = (target: Enemy): void => {
  console.log(`Attacking to ${target.name}`);
};

attack = (target: Enemy): number => {
  return target.hp - 2;
};

// lizard has 200hp
console.log(attack(lizard)); // 198

The example above has no errors, even if you think you have changed attack from (target: Enemy) => void to (target: Enemy) => number it is still void.

Check what happens if you define the function with the number first.

let attack = (target: Enemy) => {
  return target.hp - 2;
};

attack = (target: Enemy) => {
  console.log(`Attacking to ${target.name}`);
}; // Error

let attackResult = attack(lizard);

Type '(target: Enemy) => void' is not assignable to the type '(target: Enemy) => number'. Type 'void' is not assignable to the type 'number'. So, void works as any in this scenario.

For the attackResult the type will be number, there is no need to specify it, TS will infer the type from the return type of the function.

Optional parameters

Optional parameters can be defined in functions with ?

let heal = (target: Player | Enemy, spell: Spell, message?: string) => {
  if (message) console.log(message);
  return target.hp + spell.power;
};

heal(player1); // Error
heal(player1, cure, "Healing player1"); // OK
heal(skeleton, cure); // OK

The first call won't work because we need to pass at least two parameters, but the second and third are fine, message is an optional parameter, when not passed it will be received as undefined.

If you compare the last example with a simple JS function:

let heal = (target, spell, message) => {
  if (message) console.log(message);
  return target.hp + spell.power;
};

heal(player1); // Error
heal(player1, cure, "Healing player1"); // OK
heal(skeleton, cure); // OK

The basic behavior will be the same, but the difference is that the error will appear at runtime, because in the first call you cannot call power from an undefined value.

As you can see from these examples, working with functions is safer in TS because you don't need to rely on what happens outside, you know what parameters must arrive and what form they take. The same goes for the people using your function, they will know exactly what parameters are needed, the form and what they will get from the function.

Enums

With enums we can define a collection of constants.

enum BattleMenu {
  ATTACK,
  MAGIC,
  ABILITIES,
  ITEMS,
  DISENGAGE
}

enum Equipment {
  WEAPON = 0,
  HEAD = 1,
  BODY = 2,
  HANDS = 3,
  LEGS = 4
}

console.log(BattleMenu.ATTACK, Equipment.WEAPON); 
// 0 0

Enums are auto-indexed by default, both statements in the example above are equivalent.

Enums can also store strings, for example in React I often use enums to store paths:

enum Routes {
  HOME = "/",
  ABOUT = "/about",
  BLOG = "/blog"
}

Generics

const getPartyLeader = (memberList: Player[]) => {
  return memberList[0];
};

const partyLeader = getPartyLeader(partyA);

We want to implement a getPartyLeader function that returns the party leader group that is first in the array.

What if we want to support other types besides Player? We can come up with this solution for now:

const getPartyLeader = (memberList: Player[] | Enemy[]) => {
  return memberList[0];
};

const partyLeader = getPartyLeader(partyA); 
// Player[] | Enemy[]

OK, now we can pass a Player group or an Enemy group but our PartyLeader constant can be either, so the type check is Player[] | Enemy[].

If we want to assign the type exactly one way is to use generics:

const getPartyLeader = <T>(memberList: T[]) => {
  return memberList[0];
};

const partyLeader = getPartyLeader(partyA); // Player

As partyA is full of Player types, partyLeader will be of type Player. But let's check the syntax:

T is the common way to define a generic, but you can call it whatever you want.

Now the problem can be, as with any that T accepts everything, so we can adjust what kind of things we want to be able to pass to that function:

type Player = {
  name: string;
  hp: number;
};

type Enemy = {
  name: string;
  hp: number;
};

type Spell = {
  name: string;
  power: number;
};

const getPartyLeader = <T extends { hp: number }>(memberList: T[]) => {
  return memberList[0];
};

const playerPartyLeader = getPartyLeader(partyOfPlayers); // Ok
const enemyPartyLeader = getPartyLeader(partyOfEnemies); // Ok
const whatAreYouTrying = getPartyLeader(spellList); // Error

We can now only pass types containing the hp property.

Tuples

As we saw before, an Array can contain different types but is not restricted to position, the Tuple type is just to cover that:

type Weapon = {
  name: string;
  damage: number;
};

type Shield = {
  name: string;
  def: number;
};

const sword: Weapon = {
  name: "Onion Sword",
  damage: 10
};

const shield: Shield = {
  name: "Rusty Shield",
  def: 5
};

let equipment: [Weapon, Shield, boolean];

equipment = [sword, shield, true]; // OK
equipment[2] = false; // OK

equipment = [shield, sword, false]; // Error
equipment[1] = true; // Error

We now have an array-like type, which cares about where the types are placed.

Classes

With ES6 classes were added to JavaScript so there is no big difference between JS classes and TS classes.

class Job {
  public name: string;
  private level: number;
  readonly isExpansion: boolean;

  constructor(name: string, level: number, isExpansion: boolean) {
    this.name = name;
    this.level = level;
    this.isExpansion = isExpansion;
  }
}

const whiteMage = new Job("White Mage", 75, false);

console.log(whiteMage.name); // "White Mage"
console.log(whiteMage.level); // Error
console.log(whiteMage.isExpansion); // false

whiteMage.name = "Blue Mage"; // Ok
whiteMage.level = 50; // Error
whiteMage.isExpansion = true; // Error

In TS classes you have access modifiers for the properties of a class:

public - properties and methods will be accessible from all locations, this is the value by default.
private - you can only access to the property inside the same class.
protected - limits the access to the class and sub classes.
readonly - mark the property as immutable.

Interfaces

Similar to what we saw with type aliases, we can define a type through an interface.

interface Enemy {
  name: string;
  hp: number;
}

let attack = (target: Enemy): void => {
  console.log(`Attacking to ${target.name}`);
};

So, it seems to be the same as type aliases, right? Which one to use then? Both have been gaining capabilities over the different versions of TS and the nuances between them are now very slight. I like to follow this rule of thumb from ŧhis article which explains in detail the differences:

If you write object oriented code - use interfaces, if you write functional code - use type aliases.

So in React we are more used to write functional code so use type aliases.

DOM Manipulation

In React we won't use (directly) much DOM manipulation but I think it's useful to know how it works.

Retrieving elements from the DOM

// HTMLFormElement | null
const form = document.querySelector("form");

// HTMLElement | null
const otherForm = document.getElementById("myFancyForm");

// HTMLSelectElement
const select = document.createElement("select");

When we perform document.querySelector("form") our constant form is inferred with type HTMLFormElement or null, but in the second example, we get a form via its ID, and the TS does not know what exact HTML element it is, so it gives a more generic type HTMLElement.

const form = document.querySelector("form");

form.addEventListener("submit", (e: Event) => {
  e.preventDefault();
  console.log(e);
}); // Error

TS doesn't know if it will find anything in the HTML about the query selector, so it can't assign the addEventListener function to a possible null type. You can fix this in three ways.

I promise you that you will find that element:

// HTMLFormElement
const form = document.querySelector("form")!;

With ! you tell TS not to worry, he will find it, it can't be null.

Do it only if it is not null:

const form = document.querySelector("form");

form?.addEventListener("submit", (e: Event) => {
  e.preventDefault();
  console.log(e);
});

You may have already seen ? of JS Optional Chaining operator

It's type casting time:

const otherForm = document.getElementById("myFancyForm") as HTMLFormElement;

otherForm.addEventListener("submit", (e: Event) => {
  e.preventDefault();
  console.log(e);
});

You tell TS what type it will get when it finds that element, with this, you make sure it will be HTMLFormElement and not null.

Conclusion

As we saw, TypeScript puts in a lot of extra syntax that in the final code is not present at all, but that extra effort makes us justify our data structure decisions all the time and be consistent throughout the application.

Sure, working with TypeScript is more time-consuming, especially in the beginning, but it can be a lifesaver in projects that receive a lot of updates, changing requirements or above all, staff turnover.

Coding isn't just about making an efficient algorithm, you're going to be working with other people (even if you're working as a solo developer at some point you might publish your work, seek collaboration or help), in that scenario good communication between members is key.

I like to think of TypeScript as the Babel for humans, you can optimize your code for the CPU with Babel, but you need something to scale and guide others around your ideas and vice versa.

Only one question remains, when to use TypeScript?

If you work with more people or plan to publish your code, chances are you want the code to be as readable and representative of your ideas as possible.
If you're working on a large project.*

*Every big project starts as a small project, so be careful with this statement about only using it on "big" projects.

It has been a long article no doubt, if you have reached this point I must really thank you for your effort and passion, my initial idea was not so broad but I wanted to explain the whys and wherefores. I hope you enjoy this article and if you already switched from JS to TS, are using both, are considering it, at some point thought about it but didn't like it or any other situation I would like to read about your experience.

Why you should use Chakra UI in React

dastasoft — Fri, 30 Apr 2021 17:03:02 +0000

EDIT: An additional project has been added as an example: Apartmentfy

If you want to build an application or a website you need to take care of many things and in that sea of options which component library, css or ui framework will take a big role in the final version of your product.

I have tried some component libraries like Material UI, Antd, React Boostrap and other CSS frameworks like styled-components, TailwindCSS and so on, I even tried to make some mini set of components for myself with React and Bit.

Maintaining a library, or a set of components for your products that follows consistency is very difficult and choosing a library for UI purposes can be a mess if you are too constrained or the API is too complicated. At the end of the day you're trying to save time and focus on what really matters to you.

I'm not going to lie, Chakra UI popped up on my radar because I'm a Naruto fan and in the first second I thought I could style it like a ninja.

Benefits

So what are the main benefits of using this component library.

All components provided by Chakra UI are accessible following WAI-ARIA standards which I think is a pending subject for most of us. If you don't know why this is so important, please check out this article.
Components are easy to theme, expand and fully customize.
Combine components, components are small and are easy to combine to form bigger structures.
Different colour modes, switching between the typical light and dark colours or even any other set of colours will be a piece of cake.
You will do more with less in less time, which is in fact the goal of most libraries and frameworks.
The community is still quite small (which can be a good thing, you can join from the beginning), but it is very active.

Resources

You can go directly to the sample project that uses almost everything I'm going to talk in this article or try the final PWA version.

Additional sample project, Apartmentfy

And be sure to check the official Chakra UI webpage.

Prerequisites

The example project and the code samples in this article are made with NextJS but you can use it with any React-based library/framework such as Gatsby or Create React App.

The code samples in this article will be almost identical to any React platform you choose to use.

Installation

You need to install Chakra UI and the peer dependencies such as emotion and framer-motion.

npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4

yarn add @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4

Once the packages are installed, a provider need to be configured.

// pages/_app.js
import { ChakraProvider } from '@chakra-ui/react'

import Layout from '@/components/Layout'

import '@/styles/globals.css'
import theme from '@/styles/theme'

function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider theme={theme}>
      <Layout>
        <Component {...pageProps} />
      </Layout>
    </ChakraProvider>
  )
}

export default MyApp

In the case of CRA you will configure your provider in the index.js surrounding your App component.

Handy Tools project

I built a simple project with NextJS and Chakra UI that has different small utilities like a password generator or a word counter, very basic stuff.

The idea was to test the component library with the first project and test the speed of building the following utilities.

I must say that the learning curve was very easy, maybe because I'm used to using styled-components but it was by far the easiest component library I've tried so far. The developer experience was also good, so I'm sure I'll come back to this project and add more utilities for fun.

Atomic Components

One of the things I like most about Chakra UI is how the components are designed to be small so you can compose them together. The component library provides atomic components and you can build bigger elements quickly and easily as you are used to doing with normal HTML tags.

For example, let's look at the Layout component composition in Handy Tools:

// components/Layout.js
import { Box, Flex } from '@chakra-ui/react'

import Header from '@/components/Header'
import Footer from '@/components/Footer'

<Flex color="white" direction="column" minH="100%">
  <Header h="4rem" />
  <Box
    color="black"
    flex="1"
    padding="1rem"
    margin="0 auto"
    width="100%"
    backgroundColor="linkedin.100"
  >
    {children}
  </Box>
  <Footer h="3rem" />
</Flex>

Box and Flex are the most basic components you can use, they are like regular <div> tags, as you can guess, Flex is the same as Box but has display: flex in it.

Most of your initial time with the library will be spent going through the official Chakra UI documentation, they have a lot of examples and variations that for sure you will find valuable and sufficient for building your project.

You will find components for the layout of your webpage, for each component of a form, alerts, modals, loadings, typography, navigation, media and even drawers which are quite useful for mobile resolutions and skeleton ui to show the loading status of your components and avoid cumulative layout shift

The first contact with Chakra UI for me was quite similar to working with pre-build components in React Native.

Theming

One of the core values of Chakra UI is the theming, and it is very easy to adapt it to your preferences.

Inside the styles folder I create a theme.js file that has:

import { extendTheme } from '@chakra-ui/react'

const theme = extendTheme({
  fonts: {
    heading: 'Lato',
    body: 'Roboto',
  },
})

export default theme

In this file you can define all the general theme of your application such as font sizes, breakpoints, line heights, etc.

For colours Chakra UI has a default theme inspired by Tailwind CSS with colours ranging from 50 to 900.

Expanding further the theme

One of the things that can be a barrier when using a component library is that maybe your style or the style provided by the designer is different from the base design.

That can be a headache, making all those changes can end up thinking that you need more work adapting the library than doing it from scratch.

Let's see this example extracted from the official documentation:

// styles/theme.js
import { extendTheme } from "@chakra-ui/react"

const theme = extendTheme({
  components: {
    Button: {
      // 1. We can update the base styles
      baseStyle: {
        fontWeight: "bold", // Normally, it is "semibold"
      },
      // 2. We can add a new button size or extend existing
      sizes: {
        xl: {
          h: "56px",
          fontSize: "lg",
          px: "32px",
        },
      },
      // 3. We can add a new visual variant
      variants: {
        "with-shadow": {
          bg: "red.400",
          boxShadow: "0 0 2px 2px #efdfde",
        },
        // 4. We can override existing variants
        solid: (props) => ({
          bg: props.colorMode === "dark" ? "red.300" : "red.500",
        }),
      },
    },
  },
})

export default theme

I think it's clear how much effort the Chakra UI team has made to take the library easly adaptable to your needs. This is just a small example I think if I want to cover all the customisation possibilites of this library that would be enough for a whole article, be sure to check the official documentation about theming.

Maybe this file can be very large if you need a lot of changes, but the base theme with all the accessibility and consistency still will be available to you.

Responsive

Working with responsive styles is very easy, forget about media-queries and rewriting css classes (you can use it if you need to of course).

Chakra UI works with default breakpoints but you can create your own:

import { createBreakpoints } from "@chakra-ui/theme-tools"

const breakpoints = createBreakpoints({
  sm: "30em",
  md: "48em",
  lg: "62em",
  xl: "80em",
  "2xl": "96em",
})

Let's say you have a div and you want to resize it according to different breakpoints:

<Box width={[300, 400, 500]}>
  I am a div
</Box>

The array will be matched internally so:

300 will be applied from 30em
400 will be applied from 48em
500 will be applied from 62em

Another syntax for responsive values can be:

<Box width={{ sm: '300px', md: '400px', xl: '500px' }}>
  I am a div
</Box>

In the example above we are doing the same thing but we are targeting a specific breakpoint. To get the same result in the array example we need to pass a null to skip the lg breakpoint: [300, 400, null, 500].

With this syntax you don't need any media queries (Chakra UI will do it under the bonnet), but if you need to use media queries check out the next section on Hooks.

Dark Mode

The components provided by Chakra UI support dark mode. The only configuration you need to provide is a ColorModeScript:

NextJS

// pages/_document.js
import { ColorModeScript } from '@chakra-ui/react'
import NextDocument, { Html, Head, Main, NextScript } from 'next/document'

import theme from '@/styles/theme'

export default class Document extends NextDocument {
  render() {
    return (
      <Html lang="en">
        <Head />
        <body>
          <ColorModeScript initialColorMode={theme.config.initialColorMode} />
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

CRA

// index.js
import ReactDOM from "react-dom"

import App from "./App"
import theme from "./theme"

ReactDOM.render(
  <>
    <ColorModeScript initialColorMode={theme.config.initialColorMode} />
    <App />
  </>,
  document.getElementById("root"),
)

Let's check in the next section which hooks you need to use to switch between topics.

Hooks

Chakra UI also provides a collection of handy hooks to work faster.

useColorMode

In the previous section we were configuring our application with dark mode, let's see how to build a button to switch between light and dark mode.

// components/ColorChanger.js
import { IconButton, useColorMode, useColorModeValue } from '@chakra-ui/react'
import { SunIcon, MoonIcon } from '@chakra-ui/icons'

export default function ColorChanger() {
  const { toggleColorMode } = useColorMode()
  const text = useColorModeValue('dark', 'light')
  const SwitchIcon = useColorModeValue(MoonIcon, SunIcon)

  return (
    <IconButton
      size="md"
      fontSize="lg"
      aria-label={`Switch to ${text} mode`}
      variant="ghost"
      color="current"
      onClick={toggleColorMode}
      icon={<SwitchIcon />}
    />
  )
}

useColorMode provides the toggleColorMode function and that's all we need to switch between the two themes, try this hook and see how all the components included in the library switch automatically without any configuration.

useColorModeValue

In the example above you can see useColorModeValue this hook is very useful to assign different colours depending on the theme we are in. For example:

// components/WordCounters.js
import { Flex, Text, useColorModeValue } from '@chakra-ui/react'

export default function WordCounters({ value, caption }) {
  const bg = useColorModeValue('whiteAlpha.900', 'gray.800')

  return (
    <Flex flexDirection="column" alignItems="center" padding="1rem" bg={bg}>
      <Text fontSize="3xl" fontWeight="bold">
        {value}
      </Text>
      <Text>{caption}</Text>
    </Flex>
  )
}

In this example we are changing the background of this component from whiteAlpha.900 in the light theme to gray.800 when we switch to the dark theme.

useMediaQuery

As I said before, if we need to use media-query we can use this hook:

import { useMediaQuery } from "@chakra-ui/react"

function Example() {
  const [isLargerThan1280] = useMediaQuery("(min-width: 1280px)")

  return (
    <Text>
      {isLargerThan1280 ? "larger than 1280px" : "smaller than 1280px"}
    </Text>
  )
}

With the help of this hook you can execute code when the media query is triggered.

Comparison with other libraries

There are other well know libraries like Material UI and Antd or TailwindCSS.

Material UI

My biggest concern about Material UI is the API, you have to learn a lot to use the library and you will get a very nice and clean design but on the other hand it is a difficult design to customize to the point that it looks like your own.

The beauty of Chakra UI is that you can leave the library as it is or change some colours (like I did in Handy Tools) or customise it to the point where it looks like your own library and all that without pages and pages of API.

Antd

I use Antd before Chakra UI and the atomic components were awesome too, very easy to use and easy to follow documentation but for customisation I find it more difficult than Chakra UI.

In Antd they did the customisation using Less.

Tailwind CSS

I love working on projects with Tailwind CSS, it definitely speeds up the development process and I find it very useful when it comes to getting things done. The performance is better and if you or your team have experience with bootstrap, you will get the knowledge in no time.

The problem I see with Tailwind CSS is keeping the code clean and especially in projects with more members, having a good architecture for that part is not easy. Things like accessibility or keyboard navigation have to be handled manually.

With Chakra UI in the end it's all props like in any other React component, so I find it easier to use it for teamwork.

Separation of Concerns

Maybe one of the things you don't like about Chakra UI is the fact that it mixes css-related utilities with the application logic, which is not really a problem of Chakra UI but of the design of any CSS-in-JS solution.

In the Handy Tools project, the last utility I added follows the same idea as the styles in React Native:

// pages/px-converter.js
export default function PxConverter() {
  return (
    <Box>
      <Heading {...styles.heading}>Px Converter</Heading>
      <Select
        onChange={onOptionChange}
        defaultValue="pxToREM"
        {...styles.select}
      />
    </Box>
  )
}

const styles = {
  heading: {
    marginBottom: '0.5em',
  },
  flex: {
    alignItems: 'center',
    marginLeft: '0.2em',
  },
  flexCenter: {
    justifyContent: 'center',
    alignItems: 'center',
  },
  input: {
    bg: 'white',
    marginRight: '0.5em',
  },
  select: {
    bg: 'white',
    maxWidth: '400px',
    margin: '0 auto',
  },
  grid: {
    maxWidth: '600px',
    margin: '1.5em auto',
  },
  gridItem: {
    display: 'flex',
    alignItems: 'center',
    marginX: '1em',
  },
  buttonGroup: {
    justifyContent: 'center',
    size: 'sm',
    marginX: '0.5em',
  },
}

I copy the idea from React Native's createStylesheet pattern, with this you can easly split the CSS part of the props that are related to the logic.

But yes, in the end the concern about having separate standard CSS files can be a drawback, check the next section to see if Chakra UI suits your needs or not.

Chakra UI might be for you if...

You are working on a small/medium sized project.*
You don't want to / can't invest the effort in creating a library of components.
Accessibility is important to you and you don't want to / can't invest the effort.
You or your team are more proficient with JS than CSS.**
You are trying to establish a common architecture in your team.***
You need your own component library but from a solid base.
You are using another component library that you find doesn't speed up your development time.

*I'm talking about the size of the project because CSS-in-JS have a common problem, they are JS after all, it's easier for the browser to process CSS files instead of running JS, especially if your application is changing data very often but common web applications are perfectly suited to Chakra UI's performance.

**Don't think you can avoid learning CSS because of Chakra UI or any other CSS-in-JS solution, the syntax is quite similar and knowing proper CSS will help a lot.

**The weakest point of many front end developers is maintaining CSS files, having a solution like Chakra UI that blends seamlessly with the props we already know from React components helps to keep the project clean and mantainable.

Chakra UI might not be for you if...

You're working on a big project and/or changing a lot of data.
You or your team are more proficient with CSS than JS.
You need to share your style files between several projects that don't have Chakra UI.

On top of Chakra UI

Chakra UI Pro A collection of bigger components made by the creators of Chakra UI, you can find some free components that are very common and useful.
Choc UI Another collection of big components for developing common webpages blazing fast. They have a nice roadmap of future components so be sure to check out.

Conclusion

If you need a good quality of components ready to start your next project and/or want to customize the components having a good starting point I think Chakra UI has a perfect balance of effort/results.

For me doing Handy Tools, besides being a very small example project for this article, was a good experience, I would describe Chakra UI as having a clean default design like in Material UI with the simplicity of colours and responsive design provided by TailwindCSS plus the atomic design of the Antd components and a convenient accessibility layer all in one package.

Easy presentations with Fusuma and markdown

dastasoft — Thu, 25 Mar 2021 17:10:40 +0000

The main benefits of using Fusuma are:

Create slides as simply as adding a new md or mdx file.
Responsive design.
Automatically generate the content section.
You don't need to configure it, but it has settings to suit your needs.
Markdown and MDX are supported.
Several themes included.
Code syntax highlighting for your code blocks, diagrams and flowcharts.
Presentation mode, you will have the slides on one screen and the presentation control panel in the other.
- Elapsed time counter.
- Preview of the next slide.
- Preview of the previous slide.
- Presentation notes.
- Current / remaining slides.
- Record audio and actions.
Custom CSS in the global CSS settings.
Easy to deploy to GitHub Pages and any other host like Netlify or Vercel.
Exporting slides as PDF.

Instalation

Make a new empty project with:

npm init -y

Add the following commands under the scripts section:

  "scripts": {
    "init": "fusuma init",
    "start": "fusuma start",
    "start-prod": "npm run build && fusuma start-prod",
    "build": "fusuma build",
    "deploy": "npm run build && fusuma deploy",
    "export-pdf": "npm run build && fusuma pdf"
  }

Install the fusuma dev dependency with npm install -D fusuma.

And finally execute npm run init. You will get a basic Fusuma project with:

├── .fusumarc.yml
├── .github
│   └── workflows
│       └── fusuma.yml
├── package.json
├── slides
│   └── 0-slide.md
└── style.css

You can test it with npm run start and check the first slide 0-slide.md.

Creating new slides

It's as easy as creating a new markdown file in the slides folder. The order of the slides will be numerical and then alphabetical.

Modifying the first slide

Inside the 0-slide.md you can see the following content:

<!-- classes: title -->

# Hello😃

<!-- block-start: grid -->
<!-- account: twitter, your-account-name -->
<!-- block-end -->

---

<!-- section-title: "Bye👋 -->"

## Bye👋

Let's look at some of the syntax on that slide:

classes allows you to include CSS classes that you will declare in the style.css file.
block-start / block-end allows you to include CSS classes to that block.
account generates a class name (in that example account-twitter) an icon and the link for that social network.
--- you can divide slides with that, the content after that will become a new slide.
section-title declares a title for your file, it will be placed in the sidebar and in the table of contents.

There are also other tags available to you.

Creating a contents slide

Let's create the first slide we might need, the content. Make a new markdown file called 1-contents.md, the names are totally up to you by the way.

## Contents

<!-- contents -->

Inside the file, we place a title and a special tag that will automatically retrieve the titles of all the slides to create a nice and clean table of contents.

Presenter Mode

Fusuma has a Presenter Mode that allows you to put the slides on one screen while viewing the speaker's screen on the other. The speaker screen will contain:

The speaker notes that you placed on each slide.
A preview of the last slide and the next slide.
A timer.
How many slides are left.

All the tools you would need if you were making a speech.

To activate presenter mode, go to the side menu and click on the screen icon. If the browser has permision to broadcast, a pop-up will appear asking on which screen/device you want to broadcast the slides.

Config

The configuration is not necessary but many aspects of the presentation can be customised by modifying the .fusumarc.yml file.

meta:
  url:
  title:
  description:
  thumbnail:
  siteName:
  sns:
    - twitter
slide:
  loop: false
  ui:
    sidebar: true
    vertical: false
    pagination:
    effect:
  code:
    languages:
      - javascript
      - html
    plugins: []
    theme: default

meta section is for SEO purposes, if you want to share your presentation across the web these fields will help you to customize the link preview. The thumbnail is automatically generated if nothing is specified and the url field is filled in.
slide settings relative to each slide.
- loop if true, the last slide will continue with the first.
- sidebar toggles on/off the side menu with options and contents.
- pagination you can choose between bullets, progressbar and fraction tho show how many slides there are.
- effect you can choose between fade, cube and flip for animation when changing slides.
code uses Prims.js and babel-plugin-prismjs to highlight code syntax.
- languages you specify here the languages you want to apply syntax highlighting, by default only javascript is enabled.

For code syntax highlight I have to downgrade my project to version 2.6.0 toget it to work properly.

Changes to these parameters requires a restart of the application.

Themes

You can modify the whole look and feel with CSS, but by default Fusuma comes with five different themes.

Open the style.css file and import the css for the theme you want, the possibilities are:

@import '@fusuma/client/assets/style/themes/babel.css';
@import '@fusuma/client/assets/style/themes/default.css';
@import '@fusuma/client/assets/style/themes/node.css';
@import '@fusuma/client/assets/style/themes/pop.css';
@import '@fusuma/client/assets/style/themes/webpack.css';

Test the different themes and if you need some fine tuning add the classes you need in the style.css to modify the theme or create a new one.

If you want to create a new one, change the colors of the following css variables:

:root {
  --color-title: #e53498;
  --color-base: #1c1235;
  --color-background: #e5e5e5;
  --color-link: #6f4dca;
}

React Components

You can import your React Components into the .mdx files and use them as in a normal React project.

Let's create a src folder in the root of your project folder, inside we'll create a folder called components and a file called Counter.js

Inside Counter.js we paste the following example code:

import React, { useState } from 'react'

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

  return (
    <div className="react-component">
      <p>You clicked {count} times</p>
      <button onClick={() => setCount(count + 1)}>Click me!</button>
      <button onClick={() => setCount(0)}>Reset</button>
    </div>
  )
}

export default Counter

And inside of your .mdx file:

import Counter from '../src/components/Counter';

<Counter />

You now have a React Component working directly on the slide, very handy in combination with code blocks to show the source code and the execution of the component.

Distribute

Apart from running the project on your localhost, which can be valid in some cases with npm run start-prod script. You can distribute your slides in two ways.

Make a PDF

If you want to share your slides without hosting you can export them as a PDF. (Be careful with your React Components because they will stop working).

To make the export to PDF first install the dependency:

npm install -D @fusuma/task-pdf

Once installed, run the npm run export-pdf script.

In the root of your project you will get a slide.pdf file with your slides.

Deploy

You can build the project as a regular React project with npm run build and this will create the static files like in any other React project, with that you can deploy to any service like Vercel or Netlify, you only need to configure those services to run the build script every time you perform a git push.

This option is very handy if you want to share your slides directly from the browser.

Lighthouse

If you care about performance, accessibility, best practices and SEO, Fusuma has you covered, you'll get impressive results from Google Lighthouse even from the default settings.

But there are some nuances:

The SEO part of the configuration must be filled out to get to 100 in the SEO section.
Some themes (and your CSS modifications) can lower the score in the Accessibility section.

Resources

And above all, take a look and give love to the creator hiroppy for this awesome and convenient tool!

What changes can mixed reality UIs bring to webdev?

dastasoft — Wed, 03 Mar 2021 11:15:28 +0000

I'm pretty sure you watched Microsoft Ignite 2021 yesterday and if you didn't you might find it interesting.

When I was watching the show I was wondering if those UIs could change our concepts in webdev, in how we do UIs on desktop and mobile or if the field will become main stream or at least heavily adopted.

When mobile came into the ecosystem, we adapted and started launching our websites and webapps with responsive design to the point that today we code following "mobile first" practices.

Do you think that at some point we will be able to talk about "mixed reality first" or "view compatible with mixed reality UI"?

Will there be designers and front ends moving from webdev to mixed reality? (Perhaps this is already happening).

Perhaps the concept of "Full Stack" will expand even further to encompass VR/AR content as well?

What are your bets in this field?

Como montar un blog estático con Next.js y dev.to como CMS

dastasoft — Tue, 03 Nov 2020 14:30:11 +0000

Vamos a montar un blog estático utilizando Next.js y dev.to como headless CMS.

Si quieres ir directamente al resultado final en este repo tienes el proyecto final que también sirve como boilerplate para futuros blogs estáticos.

Motivación

Cuando estaba haciendo el blog para Nimbel necesitaba hacer un blog de forma rápida y que se adaptase a la naturaleza estática del resto de la página. Desde Nimbel queriamos poder publicar articulos en Dev.to y al mismo tiempo mantener actualizado el blog personal.

La estrategia que seguiremos en este tutorial será:

Aprovechar las capacidades estáticas de NextJS y la API de Dev.to para hacer un fetch de los post del usuario en tiempo de build.
Crear las rutas estáticas a todos los post que hemos hecho fetch.
Utilizar los webhooks de Dev.to para que cada vez que el usuario cree y/o actualice un post, se genere un nuevo build de nuestro sitio estático.
Crear una plantilla base (boileplate) que nos servirá para crear cualquier otro blog siguiendo esta misma estrategia.

Paso a paso

Pre requisitos

Cuenta de dev.to
Cuenta de Vercel
NodeJS 10.13+ instalado
npm o yarn

Creación del proyecto

En mi caso utilicé mi propio boilerplate de NextJS con TailwindCSS que podéis descargar desde aquí o simplemente utilizando uno de los siguientes comandos:

yarn create next-app my-app-name --example "https://github.com/dastasoft/nextjs-boilerplate"

npx create-next-app my-app-name --use-npm --example "https://github.com/dastasoft/nextjs-boilerplate"

Esto os creará un nuevo proyecto NextJS con TailwindCSS ya configurado.

Estructura

En NextJS no necesitamos definir rutas, cada JS que esté dentro de la carpeta pages será considerado una ruta accesible (menos _app y otros _ archivos que se consideran privados).

Organizaremos el proyecto con las siguientes rutas:

- pages
|- blog
|-- posts
|--- [slug].js
|- _app.js
|- blog.js
|- index.js

_app.js contendrá el layout general de la aplicación que aplicaremos a todas las rutas de nuestra aplicación.
blog.js contendrá la estructura general de la página dedicada al blog así como el fetch a los posts para poder mostrarlos en forma de tarjetas.
index.js será nuestra pagina de inicio.
blog/posts/[slug].js este punto necesita algo mas de explicación:
- Al crear una estructura le estamos diciendo al router que en la ruta nuestro-dominio/blog/posts/slug encontrará un elemento slug que será dinámico y estará accesible mediante era ruta exacta.
- Dentro de ese JS deberemos definir que valor toma el parametro dinámico slug, que en nuestro caso sera el propio slug (url) del post, por lo que deberemos hacer un fetch de ese post en concreto y consultar sus datos en tiempo de build.
- Deberemos definir todos los paths posibles (uno por cada post) de cara a que cuando el usuario navegue o escriba directamente en la url nuestro-dominio/blog/post/este-post-existe ese slug ya este creado en tiempo de build, ya que la página es totalmente estática y no irá a consultar nuevos datos fuera del build*.

SSG vs SSR vs ISR

SSG (Static Site Generation), es el modo por defecto en el que trabaja NextJS, se puede utilizar en combinación con las funciones getStaticProps y getStaticPaths que provee el propio framework, las diferentes páginas se generan de forma estática en tiempo de build.
SSR (Server Side Rendering), se generán las páginas bajo demanda por cada petición desde el servidor, se utiliza en combinación con la función getServerSideProps.
ISR (Incremental Static Regeneration), disponible a partir de la version 9.5 de NextJS. Te perimite actualizar páginas que se crearon como estáticas y al entrar una nueva petición se detecta que está en un estado obsoleto y debe re-renderizarse. Para activar ISR se añade una propiedad revalidate en la función gettaticProps.

En esta guía vamos a tratar solo SSG, para información mas detallada de los otros metódos consultar la documentación oficial, NextJS no necesita ninguna configuración especial para cambiar (o incluso combinar!) entre los diferentes modos, todo recae en la utilización de las funciones especiales ligadas a cada tipo.

Este es un apartado complejo y muy amplio y es precisamente donde NextJS brilla por la posibilidad de elegir fácilmente entre ellos o incluso combinarlos. Lo dejo para una futura guía :) la cual deberia explicar cuando utilizar unos metódos u otros segun la naturaleza de cada página.

En nuestro caso, debido a que todos los datos los tenemos disponibles en tiempo de build, dado que los vamos a buscar a la API de dev.to y no tenemos que cambiar nada de nuestra web a menos que cambie algo en nuestro CMS (dev.to) no tiene sentido estar repitiendo las mismas consultas por cada usuario que entra.

Variables de entorno

A lo largo de las siguientes secciones utilizaremos una variable de entorno para poder acceder al usuario de dev.to y poder descargarnos los articulos publicados. De cara al desarrollo en local utilizaremos el fichero .env.development en el que añadiremos la siguiente variable de entorno:

DEV_USERNAME=dastasoft

Si utilizáis directamente el boilerplate solo tenéis que cambiar el valor de esta variable para que consulte vuestro usuario en vez del mio.

Esta variable de entorno la necesitaremos configurar también en el momento del despliegue, en este tutorial desplegaremos la aplicación utilizando Vercel por lo que podéis consultar la seccion de Despliegue.

Creando el Blog

Empezaremos creando el blog.js en nuestra carpeta pages.

La parte mas importante es como hacemos fetch de todos los posts de un usuario en tiempo de build para poder pintar los posts como tarjetas, para ello utilizaremos una de las funciones SSG que nos proporciona NextJS, getStaticProps:

export const getStaticProps = async () => {
  const devDotToPosts = await fetch(
    `https://dev.to/api/articles?username=${process.env.DEV_USERNAME}`
  );

  const res = await devDotToPosts.json();

  return {
    props: {
      devDotToPosts: res
    }
  };
};

Creando el Artículo

El siguiente paso a realizar para que la generación estática sea posible es definir todas las posibles rutas que el usuario pueda visitar al entrar en esta página, para que sean accesibles las tenemos que pre-renderizar en tiempo de build y NextJS necesita saber la lista completa, esto lo conseguiremos con otra de las funciones que provee NextJS getStaticPaths.

export async function getStaticPaths() {
  const devDotToPosts = await fetch(
    `https://dev.to/api/articles?username=${process.env.DEV_USERNAME}`
  );
  const posts = await devDotToPosts.json();

  return {
    paths: posts.map(post => {
      return {
        params: {
          slug: post.slug
        }
      };
    }),
    fallback: false
  };
}

Creamos una ruta por cada post publicado, utilizando su slug como en el caso anterior. Definimos fallback como false ya que no planeamos soportar URLs que esten fuera de las que estamos generando estáticamente, tener esta propiedad a false devolverá un 404 si se intenta consultar cualquier URL que este fuera del array que proporcionamos en paths.

Habilitar la propiedad fallback tiene numerosas aplicaciones y puede ser utilizada en combinación con Incremental Static Generation el cual es una opción muy potente dentro de NextJS, para más información sobre este tema consultar la documentación oficial

Datos del artículo

Dentro del artículo en concreto, necesitamos recuperar los datos, para ello consultaremos la API de dev.to usando el mismo slug con el que hemos construido la URL.

export const getStaticProps = async ({ params }) => {
  const devDotToPost = await fetch(
    `https://dev.to/api/articles/${process.env.DEV_USERNAME}/${params.slug}`
  );
  const res = await devDotToPost.json();

  return {
    props: {
      devDotToPost: res
    }
  };
};

Todos los datos que nos llegan desde la API de dev.to los pasamos en tiempo de build a la página del artículo en concreto, estos datos serán accesibles a través de la prop devDotToPost.

export default function Post({ devDotToPost }) {
    ...
}

Imprimir el markdown

Una vez ya tenemos los datos del artículo, entre los múltiples campos que nos llegan de la API, el contenido en markdown está en body_html, para utilizarlo:

<div className="markdown" dangerouslySetInnerHTML={{ __html: body_html }} />

En la clase markdown deberás definir como quieres que se vean los elementos contenidos en el markdown ya que la API devuelve una versión raw del markdown. En el proyecto de ejemplo tienes disponible una propuesta simple.

[slug].js al completo

Así es como queda nuestra template para cualquier artículo, podéis verlo directamente en el repo:

import Head from 'next/head';
import Link from 'next/link';

import TopButton from '../../../components/TopButton';

export default function Post({ devDotToPost }) {
  const {
    title,
    published_at,
    social_image,
    body_html,
    user,
    type_of,
    description,
    canonical_url
  } = devDotToPost;
  const date = new Date(published_at);
  const formatedDate = `${date.getDate()}/${
    parseInt(date.getMonth(), 10) + 1
  }/${date.getFullYear()}`;

  return (
    <div>
      <Head>
        <meta property="og:type" content={type_of} />
        <meta property="og:title" content={title} />
        <meta property="og:description" content={description} />
        <meta property="og:image" content={social_image} />
        <meta property="og:url" content={canonical_url} />
      </Head>
      <div className="flex justify-center">
        <TopButton />
        <article className="text-xs w-full md:w-3/4 ">
          <div className="border-2 text-black bg-white md:rounded-lg overflow-hidden">
            <img className="w-full" src={social_image} alt={title} />
            <div className="p-4 md:p-32">
              <h1>{title}</h1>
              <div className="flex items-center text-gray-600">
                <img
                  className="rounded-full w-12"
                  src={user.profile_image_90}
                  alt={user.name}
                />
                <span className="mx-4">{user.name}</span>
                <span className="text-sm">{formatedDate}</span>
              </div>
              <div
                className="markdown"
                dangerouslySetInnerHTML={{ __html: body_html }}
              />
            </div>
          </div>
          <Link href="/blog">
            <a className="text-blue-500 inline-flex items-center md:mb-2 lg:mb-0 cursor-pointer text-base pb-8">
              <svg
                className="w-4 h-4 mr-2"
                stroke="currentColor"
                strokeWidth="2"
                fill="none"
                strokeLinecap="round"
                strokeLinejoin="round"
                viewBox="0 0 24 24"
              >
                <path d="M19 12H5M12 19l-7-7 7-7" />
              </svg>
              Back
            </a>
          </Link>
        </article>
      </div>
    </div>
  );
}

export const getStaticProps = async ({ params }) => {
  const devDotToPost = await fetch(
    `https://dev.to/api/articles/${process.env.DEV_USERNAME}/${params.slug}`
  );
  const res = await devDotToPost.json();

  return {
    props: {
      devDotToPost: res
    }
  };
};

export async function getStaticPaths() {
  const devDotToPosts = await fetch(
    `https://dev.to/api/articles?username=${process.env.DEV_USERNAME}`
  );
  const posts = await devDotToPosts.json();

  return {
    paths: posts.map(post => {
      return {
        params: {
          slug: post.slug
        }
      };
    }),
    fallback: false
  };
}

Layout

Para crear el layout y que aplique a todas las pantallas, lo crearemos en el fichero _app.js e internamente NextJS lo añadirá a todas las paginas:

import Link from 'next/link';

import '../styles/index.css';

export default function App({ Component, pageProps }) {
  return (
    <div>
      <nav className="p-4 flex justify-center items-center mb-4" id="nav">
        <Link href="/">
          <span className="text-xl font-bold cursor-pointer mr-4">Home</span>
        </Link>
        <Link href="/blog">
          <span className="text-xl font-bold cursor-pointer">Blog</span>
        </Link>
      </nav>
      <main className="container px-5 mx-auto">
        <Component {...pageProps} />
      </main>
    </div>
  );
}

Lo importante en este punto es:

Utilizar el componente Link de NextJS para que la navegación sea correcta
Es el sitio ideal para importar el archivo de css y que aplique de forma global.
Asegurarse de tener <Component {...pageProps} /> ya que sin esto no veremos los componentes hijos, (similar a la utilizacion de children en React)

Home

Definir la pagina principal en NextJS es tan sencillo como crear el fichero index.js dentro de la carpeta pages y NextJS creará automáticamente una ruta, en este caso a /, la cual mezclará lo que hayamos definido en el fichero _app.js mas el propio index.js.

Esta es la propuesta de home page para el proyecto:

import DevDotToLogo from '../public/devdotto.svg';
import NextLogo from '../public/nextjs.svg';

export default function Home() {
  return (
    <div>
      <div className="flex justify-center items-center">
        <a
          href="https://nextjs.org/"
          target="_blank"
          rel="noopener noreferrer"
          aria-label="NextJS"
        >
          <NextLogo className="mr-4" width="100px" height="100px" />
        </a>
        <span className="text-2xl">Blog Boilerplate</span>
      </div>

      <div className="flex justify-center items-center">
        <span className="text-2xl">with</span>
        <a
          href="https://dev.to/"
          target="_blank"
          rel="noopener noreferrer"
          aria-label="Dev.to"
        >
          <DevDotToLogo className="mx-4" width="100px" height="100px" />
        </a>
        <span className="text-2xl">as a CMS</span>
      </div>
    </div>
  );
}

En este caso se utilizan anchor normales ya que son enlaces al exterior y NextJS no tiene que acceder a ningua ruta interna.

CSS

NextJS mostrará errores si intentáis introducir CSS que puedan afectar de forma global fuera del archivo _app.js, por ello en los demas sitios como páginas y/o componentes es recomendable utilizar soluciones como emotionjs, styled-components, css-modules o tailwindcss como en esta guía, que tienen su rango de efecto limitado al propio componente.

NextJS provee su propia solución CSS-in-JS llamada styled-jsx pero últimamente de los propios proyectos quick-start de NextJS se ha optado por implementar css-modules.

Si quereis conocer mejor que opciones tenéis para temas de estilo podéis consultar mi guia de estilos en React la cual aplica en su mayoria para NextJS, la diferencia principal es que no podemos aplicar estilos globales como hemos comentado anteriormente.

Despliegue

Desplegaremos este proyecto en la plataforma de los mismos creadores de NextJS que es Vercel. Para desplegar un proyecto en Vercel debéis seguir los siguientes pasos:

Crear una cuenta en Vercel
Pulsar en Import Project
Importaremos el proyecto directamente de nuestro repositorio Git
Proporcionar la URL del repositorio GIT.
En caso de que el paso anterior os de el error: Couldn’t find the Git repository. If it exists, verify that the GitHub Integration is permitted to access it in the GitHub App Settings. pulsar en GitHub App Settings y añadir el repositorio que intentáis desplegar a la lista de accesos de Vercel, si es el primer despliegue que realizais os pedirá acceso como parte del proceso.
Una vez Vercel tenga visibilidad sobre el repositorio Git podremos darle un nombre, que puede ser cualquiera no tiene porque coincidir con git, un Framework preset que dejaremos tal y como esta marcado en Next.js, Build and Output Settings que por el momento no necesitaremos cambiar nada y por último Environment Variables aqui tendremos que crear la variable de entorno que definimos anteriormente en .env.development
Dentro de Environment Variables definimos la variable DEV_USERNAME con el valor del usuario sobre el que queráis hacer las consultas, en mi caso dastasoft y pulsamos Add
Pulsamos Deploy

Es posible que la primera vez el despliegue falle dando errores de recibir respuestas JSON erroneas, en mi caso intentando el despliegue una segunda vez me funcionó sin problemas.

Podéis ver el resultado final desplegando el boilerplate que hemos construido en este tutorial en [https://dev-cms-static-blog.vercel.app/(https://dev-cms-static-blog.vercel.app/)

Actualización automática

Ya casi estamos, pero nos falta el paso más importante, ahora mismo tenemos un blog que se genera en tiempo de build de forma estática, eso quiere decir que cuando el proyecto se despliega en Vercel, se lanzan todas las consultas necesarias a dev.to para obtener la información necesaria y con eso se construye una web totalmente estática en la que por muchas visitas que tengamos, no se vuelve a consultar a dev.to para recuperar artículos.

Pero y si publicamos/editamos un artículo? Necesitamos una forma de decirle a Vercel que debe volver a pasar esa fase de build y recuperar la información más actualizada, para ello utilizaremos webhooks.

Crear una URL de acceso al despliegue

Dentro del proyecto en Vercel, debemos ir a Settings a la sección referente a Git y buscar el cuadro Deploy Hooks, aquí crearemos un nuevo hook al cual le podemos dar el nombre que queramos y que este en nuestra rama principal de git, en mi caso:

Nombre: dev.to
Git Branch Name: master

Esto nos generará una URL del tipo https://api.vercel.com/v1/integrations/deploy/xxxxxxxxxxxxxxxxxxx

Crear webhooks en dev.to

En el README.md del boilerplate teneis los comandos disponibles para consultar, crear y eliminar webhooks en vuestra cuenta de dev.to.

Necesitaréis acceso a una Terminal y el paquete curl, además en vuestra cuenta de dev.to necesitaréis crear una DEV API Key, esto lo podéis hacer accediendo a dev.to con vuestra cuenta en el apartado Settings, Account y en la sección DEV API Keys.

Para crear la DEV API Key hay que proporcionar un nombre y pulsar en Generate API Key, esto nos generará un hash que necesitaremos en los siguientes comandos.

Con una terminal abierta utilizamos el siguiente comando para crear el webhook en nuestra cuenta de dev.to

curl -X POST -H "Content-Type: application/json" \
  -H "api-key: API_KEY" \
  -d '{"webhook_endpoint":{"target_url":"TARGET_URL","source":"DEV","events":["article_created", "article_updated"]}}' \
  https://dev.to/api/webhooks

Donde API_KEY es la DEV API Key que hemos creado en dev.to y TARGET_URL (importante mantener las ") es la URL de acceso al despliegue que hemos creado en Deploy Hooks de Vercel. En este ejemplo estamos poniendo a la escucha el webhook para los eventos de creación de artículos y también para la edición, podéis dejar los eventos que os interesen.

Comprobar webhook

En una terminal con curl disponible ejecutar el siguiente comando:

curl -H "api-key: API_KEY" https://dev.to/api/webhooks

Donde API_KEY es la DEV API Key que hemos creado en dev.to.

Debe respondernos con un array el cual no debe estar vacío ya que en el paso anterior creamos un webhook. Si os sale como respuesta un array vacío, comprobad el paso anterior.

Conclusión

Si se ha creado satisfactoriamente el webhook, lo que habremos conseguido es que cada vez que un artículo se cree o se edite (segun los eventos que hayais utilizado) llamará a la URL que le hemos porporcionado, esta URL desencadenará un nuevo build en Vercel que volverá a consultar la API de dev.to y encontrará el nuevo artículo generando de nuevo una versión totalmente estática de nuestro blog.

Con esto ya tendríamos completados los requisitos que nos habiamos fijado al principio de este tutorial! Os animo a indagar más en el proyecto boilerplate sobre el que esta basado este tutorial para que lo podáis utilizar como base para futuros proyectos.

Ahora es vuestro turno, cual es vuestra experiencia creando blogs? Crees que es más sencillo de la forma que lo haces actualmente o con esta forma? Ya utilizabas esta forma o una parecida, cuentame tu caso de éxito o tus preguntas :D

Con un poco de suerte, este post creará una nueva entrada en el Blog de Nimbel

Disfrutad!

Simple Static Blog with Next.js and dev.to as CMS

dastasoft — Mon, 26 Oct 2020 23:37:17 +0000

UPDATE: Added Next v10 with new Image component

We are going to set up a static blog using Next.js and dev.to as a headless CMS.

If you want to go directly to the final result in this repo you have the final project that also serves as a boilerplate for future static blogs.

Motivation

When I was blogging for Nimbel I needed to make a blog quickly that would fit the static nature of the rest of the page. Nimbel wanted to be able to publish articles in Dev.to and at the same time keep the personal blog updated.

The strategy we will follow in this tutorial will be:

Take advantage of the static capabilities of NextJS and the Dev.to API to fetch the user's posts at build time.
Create the static paths to all the posts we have fetched.
Use Dev.to's webhooks so that every time the user creates and/or updates a post, a new build of our static site is generated.
Create a base template (boileplate) that will be used to create any other blog following this same strategy.

Step by step

Pre-requisites

dev.to account
Vercel account
NodeJS 10.13+ installed
npm or yarn

Creation of the project

In my case I used my own NextJS boilerplate with TailwindCSS that you can download from here or simply using one of the following commands:

yarn create next-app my-app-name --example "https://github.com/dastasoft/nextjs-boilerplate"

npx create-next-app my-app-name --use-npm --example "https://github.com/dastasoft/nextjs-boilerplate"

This will create a new NextJS project with TailwindCSS already configured.

Structure

In NextJS we don't need to define paths, each JS that is inside the pages folder will be considered an accessible path (minus _app and other _ files that are considered private).

We will organize the project with the following paths:

- pages
|- blog
|-- posts
|--- [slug].js
|- _app.js
|- blog.js
|- index.js

_app.js will contain the general layout of the application that we will apply to all the paths of our application.
blog.js will contain the general structure of the blog page as well as the fetch for the posts to be able to display them in the form of cards.
index.js will be our home page.
blog/posts/[slug].js this point needs some additional explanation:
- By creating a structure we're telling the router that in the path our-domain/blog/posts/slug it will find a slug element that will be dynamic and accessible via the exact path.
- Within this JS we must define what value the dynamic parameter slug takes, which in our case will be the slug (url) of the post itself, so we must fetch that particular post and check its data at build time.
- We must define all the possible paths (one for each post) so that when the user navigates or writes directly in the url our-domain/blog/post/this-post that slug is already created at build time, since the page is completely static and will not go to consult new data outside the build.

SSG vs SSR vs ISR

SSG (Static Site Generation), is the default mode in which NextJS works, it can be used in combination with the getStaticProps and getStaticPaths functions provided by the framework, the different pages are generated statically at build time.
SSR (Server Side Rendering), pages are generated on demand for each request from the server, is used in combination with the getServerSideProps function.
ISR (Incremental Static Regeneration), available from version 9.5 of NextJS. It allows you to update pages that were created as static and when a new request is entered it is detected to be in an obsolete state and must be re-rendered. To activate ISR a 're-validate' property is added to the 'object' function.

In this guide we are going to treat only SSG, for more detailed information of the other methods see the official documentation, NextJS does not need any special configuration to change (or even combine!) between the different modes, it all lies in the use of the special functions linked to each type.

This is a complex and very extensive section and it is precisely where NextJS shines by the possibility of easily choosing between them or even combining them. I leave it for a future guide :) which should explain when to use some methods or others according to the nature of each page.

In our case, because we have all the data available at build time, since we are going to look for it in the dev.to API and we don't have to change anything on our website unless something changes in our CMS (dev.to) it doesn't make sense to be repeating the same queries for each user that enters.

Environment Variables

Throughout the following sections we will use an environment variable to access the dev.to user and download the published articles. For local development we will use the .env.development file in which we will add the following environment variable:

DEV_USERNAME=dastasoft

If you use the boilerplate directly, you only have to change the value of this variable.

This environment variable will also need to be configured at the time of deployment, in this tutorial we will deploy the application using Vercel so you can check the section of Deployment.

Creating the Blog

We will start by creating the blog.js in our pages folder.

The most important part is how we fetch all the posts of a user at build time to be able to display the posts as cards, for this we will use one of the SSG functions provided by NextJS, getStaticProps:

export const getStaticProps = async () => {
  const devDotToPosts = await fetch(
    `https://dev.to/api/articles?username=${process.env.DEV_USERNAME}`
  );

  const res = await devDotToPosts.json();

  return {
    props: {
      devDotToPosts: res,
    },
  };
};

Creating the Article

The next step to make the static generation possible is to define all the possible paths that the user can visit when entering this page, to be accessible we have to pre-render them at build time and NextJS needs to know the complete list, this will be achieved with another of the functions provided by NextJS getStaticPaths.

export async function getStaticPaths() {
  const devDotToPosts = await fetch(
    `https://dev.to/api/articles?username=${process.env.DEV_USERNAME}`
  );
  const posts = await devDotToPosts.json();

  return {
    paths: posts.map(post => {
      return {
        params: {
          slug: post.slug,
        },
      };
    }),
    fallback: false,
  };
}

We create a route for each published post, using its slug as in the previous case. We define fallback as false since we do not plan to support URLs that are outside of the ones we are statically generating, having this property set to false will return a 404 if you try to query any URL that is outside of the array we provide in paths.

Enabling the fallback property has numerous applications and can be used in combination with Incremental Static Generation which is a very powerful option within NextJS, for more information on this topic see official documentation

Article data

Within the specific article, we need to retrieve the data, for this we will consult the dev.to API using the same slug with which we have built the URL.

export const getStaticProps = async ({ params }) => {
  const devDotToPost = await fetch(
    `https://dev.to/api/articles/${process.env.DEV_USERNAME}/${params.slug}`
  );
  const res = await devDotToPost.json();

  return {
    props: {
      devDotToPost: res,
    },
  };
};

All the data that comes from the dev.to API is passed in build time to the page of the specific article, this data will be accessible through the prop devDotToPost.

export default function Post({ devDotToPost }) {
    ...
}

Style the markdown

Once we have the data of the article, among the multiple fields that come to us from the API, the content in markdown is in body_html, to use it:

<div className="markdown" dangerouslySetInnerHTML={{ __html: body_html }} />

In the markdown class you must define how you want the elements look, since the API returns a raw version of the markdown. In the example project you have available a simple proposal.

Complete [slug].js

This is how our template looks like for any article, you can see it directly in the repo:

import Head from "next/head";
import Link from "next/link";

import TopButton from "../../../components/TopButton";

export default function Post({ devDotToPost }) {
  const {
    title,
    published_at,
    social_image,
    body_html,
    user,
    type_of,
    description,
    canonical_url,
  } = devDotToPost;
  const date = new Date(published_at);
  const formatedDate = `${date.getDate()}/${
    parseInt(date.getMonth(), 10) + 1
  }/${date.getFullYear()}`;

  return (
    <div>
      <Head>
        <meta property="og:type" content={type_of} />
        <meta property="og:title" content={title} />
        <meta property="og:description" content={description} />
        <meta property="og:image" content={social_image} />
        <meta property="og:url" content={canonical_url} />
      </Head>
      <div className="flex justify-center">
        <TopButton />
        <article className="text-xs w-full md:w-3/4 ">
          <div className="border-2 text-black bg-white md:rounded-lg overflow-hidden">
            <img className="w-full" src={social_image} alt={title} />
            <div className="p-4 md:p-32">
              <h1>{title}</h1>
              <div className="flex items-center text-gray-600">
                <img
                  className="rounded-full w-12"
                  src={user.profile_image_90}
                  alt={user.name}
                />
                <span className="mx-4">{user.name}</span>
                <span className="text-sm">{formatedDate}</span>
              </div>
              <div
                className="markdown"
                dangerouslySetInnerHTML={{ __html: body_html }}
              />
            </div>
          </div>
          <Link href="/blog">
            <a className="text-blue-500 inline-flex items-center md:mb-2 lg:mb-0 cursor-pointer text-base pb-8">
              <svg
                className="w-4 h-4 mr-2"
                stroke="currentColor"
                strokeWidth="2"
                fill="none"
                strokeLinecap="round"
                strokeLinejoin="round"
                viewBox="0 0 24 24"
              >
                <path d="M19 12H5M12 19l-7-7 7-7" />
              </svg>
              Back
            </a>
          </Link>
        </article>
      </div>
    </div>
  );
}

export const getStaticProps = async ({ params }) => {
  const devDotToPost = await fetch(
    `https://dev.to/api/articles/${process.env.DEV_USERNAME}/${params.slug}`
  );
  const res = await devDotToPost.json();

  return {
    props: {
      devDotToPost: res,
    },
  };
};

export async function getStaticPaths() {
  const devDotToPosts = await fetch(
    `https://dev.to/api/articles?username=${process.env.DEV_USERNAME}`
  );
  const posts = await devDotToPosts.json();

  return {
    paths: posts.map(post => {
      return {
        params: {
          slug: post.slug,
        },
      };
    }),
    fallback: false,
  };
}

Layout

To create the layout and apply it to all the screens, we will create it in the _app.js file and internally NextJS will add it to all the pages:

import Link from "next/link";

import "../styles/index.css";

export default function App({ Component, pageProps }) {
  return (
    <div>
      <nav className="p-4 flex justify-center items-center mb-4" id="nav">
        <Link href="/">
          <span className="text-xl font-bold cursor-pointer mr-4">Home</span>
        </Link>
        <Link href="/blog">
          <span className="text-xl font-bold cursor-pointer">Blog</span>
        </Link>
      </nav>
      <main className="container px-5 mx-auto">
        <Component {...pageProps} />
      </main>
    </div>
  );
}

The important thing at this point is:

Use the NextJS Link component to make the navigation correct
It is the ideal place to import the css file and apply it globally.
Be sure to have <Component {...pageProps} /> since without this we will not see the children components, (similar to the use of children in React)

Home

Defining the main page in NextJS is as simple as creating the file index.js inside the pages folder and NextJS will automatically create a path, in this case to /, which will mix what we have defined in the _app.js file plus the index.js itself.

This is the proposed home page for the project:

import DevDotToLogo from "../public/devdotto.svg";
import NextLogo from "../public/nextjs.svg";

export default function Home() {
  return (
    <div>
      <div className="flex justify-center items-center">
        <a
          href="https://nextjs.org/"
          target="_blank"
          rel="noopener noreferrer"
          aria-label="NextJS"
        >
          <NextLogo className="mr-4" width="100px" height="100px" />
        </a>
        <span className="text-2xl">Blog Boilerplate</span>
      </div>

      <div className="flex justify-center items-center">
        <span className="text-2xl">with</span>
        <a
          href="https://dev.to/"
          target="_blank"
          rel="noopener noreferrer"
          aria-label="Dev.to"
        >
          <DevDotToLogo className="mx-4" width="100px" height="100px" />
        </a>
        <span className="text-2xl">as a CMS</span>
      </div>
    </div>
  );
}

In this case normal anchor is used as they are links to the outside and NextJS does not have to access any internal route.

CSS

NextJS will display errors if you try to introduce CSS that can affect globally outside the _app.js file, in the other sites as pages and / or components is advisable to use solutions such as emotionjs, styled-components, css-modules or tailwindcss as in this guide, which have their scope limited to the component itself.

NextJS provides its own CSS-in-JS solution called styled-jsx but lately from NextJS own quick-start projects it has been decided to implement css-modules.

If you want to know better what options you have for style issues you can check my style guide in React which applies mostly to NextJS, the main difference is that we can not apply global styles as we discussed above.

Deployment

We will deploy this project on the platform of the same creators of NextJS which is Vercel. To deploy a project in Vercel you must follow the next steps:

Create a Vercel account
Click on Import Project
We'll import the project directly from our Git repository
Provide the URL of the GIT repository
In case the previous step gives you the error: Couldn't find the Git repository. If it exists, verify that the GitHub Integration is permitted to access it in the GitHub App Settings. click on GitHub App Settings and add the repository you're trying to deploy to Vercel's access list, if it's the first deployment you do it, Vercel will ask you for access as part of the process.
Once Vercel has visibility into the Git repository, you can give it a name, a framework preset that you leave as it is in Next.js, Build and Output Settings that you don't need to change for now, and finally Environment Variables that you create in .env.development
Inside Environment Variables we define the variable DEV_USERNAME with the value of the user about whom you want to make the queries, in my case dastasoft and press Add.
Press Deploy.

It is possible that the first time the deployment failed giving errors of receiving wrong JSON answers, in my case trying the deployment a second time worked without problems.

You can see the final result by deploying the boilerplate we have built in this tutorial at https://dev-cms-static-blog.vercel.app/

Automatic update

We're almost done, but the most important step is missing, right now we have a blog that is generated in a static way at build time, that means that when the project is deployed in Vercel, all the necessary queries are launched to dev.to to obtain the necessary information and with that a totally static website is built in which no matter how many visits we have, dev.to is not consulted again to retrieve articles.

But what if we publish/edit an article? We need a way to tell Vercel that it must go back to that build phase and recover the most updated information, for that we will use webhooks.

Create a URL to access the display

Within the project in Vercel, we must go to Settings to the section referring to Git and look for the box Deploy Hooks, here we will create a new hook to which we can give the name that we want and that this in our main branch of git, in my case:

Name: dev.to
Git Branch Name: master

This will generate a URL of the type https://api.vercel.com/v1/integrations/deploy/xxxxxxxxxxxxxxxxxxx

Create webhooks on dev.to

In the README.md of the boilerplate you have the commands available to view, create and delete webhooks in your dev.to account.

You will need access to a Terminal and curl package, in your dev.to account you will need to create a dev.to API Key, this can be done by logging into dev.to with your account in the Settings, Account and Dev API Keys section.

To create the DEV API Key you have to provide a name and click on Generate API Key, this will generate a hash that we will need in the following commands.

With a terminal open we use the following command to create the webhook in our dev.to account

curl -X POST -H "Content-Type: application/json" \
  -H "api-key: API_KEY" \
  -d '{"webhook_endpoint":{"target_url":"TARGET_URL","source":"DEV","events":["article_created", "article_updated"]}}' \
  https://dev.to/api/webhooks

Where API_KEY is the DEV API Key that we have created in dev.to and TARGET_URL (important to keep the ") is the display access URL that we have created in Deploy Hooks from Vercel. In this example we are using the webhook for the events of creation of articles and also for the edition, you can leave the events that you need.

Check webhook

In a terminal with curl available, execute the following command:

curl -H "api-key: API_KEY" https://dev.to/api/webhooks

Where API_KEY is the DEV API Key we have created on dev.to.

The service must answer us with an array which must not be empty, because in the previous step we created a webhook. If you get an empty array in response, check the previous step.

Conclusion

If the webhook has been successfully created, what we will have achieved is that every time an article is created or edited (depending on the events you have used) it will call the URL we have provided it with, this URL will trigger a new build in Vercel that will again check the dev.to API and find the new article generating again a totally static version of our blog.

With this we would have already completed the requirements that we had set at the beginning of this tutorial! I encourage you to investigate further in the project boilerplate on which this tutorial is based so that you can use it as a basis for future projects.

Now it's your turn, what is your experience creating blogs? Do you think it's easier the way you're currently doing it or with this form? You already used this form or a similar one, tell me your success story or your questions :D

Hopefully, this post will create a new entry in Nimbel's Blog

Enjoy!

What supouses Deno for front end devs?

dastasoft — Wed, 13 May 2020 12:26:58 +0000

With all the hype for deno it would be possible to have webpack/parcel on top of deno and remove node_modules for front end dev? At the end when you execute your webpack/parcel starts behind the scenes is calling nodejs.

Assuming this is possible... If we have imports to urls across our files (instead of regular imports to node_modules) we need the package.json or something similar to control the versions in a centralized spot anyway.

When I say front end dev I thinking this scenario in a create-react-app or something similar client side.