DEV Community: Ivan V.

Progressive web apps with Material UI (MUI), Next.js and Workbox

Ivan V. — Thu, 16 Jun 2022 13:53:05 +0000

Setting up PWA's involves a lot of moving parts, so I've decided to create a template repository, that I would always keep up to date, and it will enable me to get started quickly.

demo: https://material-pwa.vercel.app/

repository: https://github.com/ivandotv/nextjs-material-pwa

Layout

The application supports both desktop and mobile layouts.

The desktop layout has a sidebar on the left side that can open and close.

The mobile layout has two options.

Traditional layout with a sidebar that can be swiped to open/close

Modern layout where menu items are at the bottom

Theming

There are two themes dark and light, and they can easily be customized.

Onboarding slideshow

I've also included an onboarding slideshow which is usually present in native apps. This is optional and it can easily be removed.

Service worker

The real hard part of creating PWA's is service worker integration, both in the build process and in production.
Service worker functionality is implemented with the excellent Workbox library

service worker setup

Service worker is written in Typescript and it will be compiled together with the rest of the code. The service worker will precache all the routes, images, CSS, and google fonts. Every time the app is built new cache manifest is created.

When the service worker is installed, the application will show a prompt to reload the application so the new service worker can take over.

offline fallback

Offline fallback is provided, if navigation happens when there is no network, the fallback page will be shown. Please note that the fallback files must be pure html,css, and js (no react, or css-in-js libraries). Fallback files need to be placed in the public directory.

Also, there is network offline detection, if the browser loses network connection, there will be a notification inside the app that the application is offline. You can test this via the Chrome dev tools network tab.

installation prompt

The application also has a custom prompt for the installation of the app. Please note that the installation prompt only works on the desktop OS'es and Android, no IOS.

app shortcuts

The application also has set some demo shortcuts which show up if the application is installed.

Make sure to check out the demo:

demo: https://material-pwa.vercel.app/

repository: https://github.com/ivandotv/nextjs-material-pwa

Dependency injection without the decorators

Ivan V. — Tue, 14 Jun 2022 12:10:09 +0000

I'm a big fan of dependency injection since I'm working with the front-end a lot, I needed a dependency injection library that is not based on decorators and has a small file size. I couldn't find anything, so I've created one myself.

It's called PumpIt it's less than 2KB and this is how it works.

class A {
  static inject=[B]
  constructor(public b:B){}
}
class B {}

const container = new Pumpa()

container.bindClass(A,A)
container.bindClass(B,B)

const instanceA = container.resolve<A>(A)

You can also register function factories

class B{}

function myFactory(b: B) {
  return function resolvedFunction() {
    // do something with b
  }
}

myFactory.inject = [B]

container.bindFactory(myFactory, myFactory)

const fn = container.resolve(myFactory)
fn === resolvedFunction

There is also another way to register values with the container. It is particularly useful when you don't have access to the values you want to register (third-party libraries).

class A {
  //note: there is no static inject property on the class
  constructor(public b:B){}
}
class B {}

const container = new Pumpa()

//alternative way of registering
container.bindClass(A,{value:A,inject:[B]})
container.bindClass(B,B)

const instanceA = container.resolve<A>(A)
instanceA.b === B

It also supports injecting an array of dependencies.

class A {
  static inject = [getArray([A, B, C])]
  constructor(deps: [A, B, C]) {}
}

And that's the gist of it.

It is written in Typescript, it is modeled similarly to the Microsoft tsyringe (which I was using previously).

I've spent a lot of time on the documentation, so head over to the Github repository to see what else the library can do.

I'm open to new ideas and pull requests.

MongoDB and PostgreSQL database testing with Jest and Docker containers

Ivan V. — Tue, 07 Jun 2022 15:50:19 +0000

I've made an example repository that demonstrates how to test MongoDB and PostgreSQL databases with Docker containers
and Jest.

Currently, I have no time to write the full article but it is on my to-do list. In the meantime, you can check out the repository that has a readme file where everything is explained.

How it works

When Jest is started, and before the tests are executed, we create two docker database containers (MongoDB and PostgreSQL) each test file (Jest Worker) gets a new database inside the container.
If the detected OS is Linux, we use the tmpfs file system inside the containers which increases the speed of execution since in that case all database data is held in memory.

Test execution

Before each test, the database is seeded.
After each test, the database is cleared.
When all tests in the file are done, the database is discarded.
When Jest is done running all the tests, database containers are stopped and removed.

Jest watch mode is supported, in that case, everything works that same, but database containers will not be stopped and removed until you exit watch mode.

Running on Github Actions

Github actions file is included. Default Ubuntu Github Actions image comes with Docker preinstalled so no issues are running the tests in a continuous integration environment.

I use this setup in my projects, so this repository will be kept up to date.

https://github.com/ivandotv/jest-database-containers

Next.js API routes with Koa.js

Ivan V. — Mon, 16 May 2022 11:12:55 +0000

I'll keep this post short and sweet :)

I've been doing some CRUD with Next.js API routes, and I've always liked using Koa.js for creating the API's in Node.js.

I think Koa.js is a great fit for Next.js because it is fully async, error handling is easy, and the codebase is very small so the initialization of the Koa App is very fast.

I've decided to integrate Koa.js (and Koa Router) with the Next.js API routes:

Usage is simple as this (in your API file):

//pages/api/[[...demo]].ts
import { KoaApi, withKoaApi } from 'nextjs-koa-api'

const api = new KoaApi({ router: { prefix: '/api' } })

api.use((ctx) => {
  ctx.body = 'Hello World'
})
.router.get('/:todo',....)
.post('/:todo',....)
.delete('/:todo',....)

//use helper function
export default withKoaApi(API)

//or the standard way
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  return api.run(req, res)
}

Check out the repository where you can find complete documentation and a small Next.js demo app.

https://github.com/ivandotv/nextjs-koa-api

I'm open to suggestions and contributions.

Thanks!

The complete guide to internationalization in Next.js

Ivan V. — Fri, 06 May 2022 10:35:58 +0000

Translating web applications into multiple languages is a common requirement. In the past, creating multilingual applications was not an easy task, but recently (thanks to the people behind the Next.js framework and Lingui.js library) this task has gotten a lot easier.

I have written a blog post for LogRocket where I create a Next.js application with multiple translations, there is a link to the github repository, and an online demo.

So go over there and check it out

Microbundle is not enough

Ivan V. — Mon, 14 Feb 2022 23:19:01 +0000

Setting up a modern Typescript or Javascript development stack is a daunting task, there are a lot of moving parts, and sometimes the whole process seems like magic, so I switched to Microbundle. While microbundle handles the compilation, there are a lot of other moving parts that need to be set up to start developing with Nodejs/Typescript (CI, tests, linting, etc). So I've created an opinionated template repository with Typescript, Microbundle, Jest, eslint, husky, prettier, github actions, pnpm, and a bunch of other scripts. It enables me to start developing a library immediately by using the repository as a starter template. Let me know what you think and if some processes could be improved, or some valuable tools that could be added. Pull requests and suggestions are welcomed.

Microbundle Template Repository

Preventing GraphQL batching attacks

Ivan V. — Mon, 07 Feb 2022 19:06:18 +0000

In this post, I'm going to explain what is GraphQL batching attack, and how you can defend from it.
GraphQL can send multiple queries with a single request, and this can be open to abuse. Consider this mutation where we are trying different password/username combinations.

  mutation {
    login(pass: 1111, username: "ivan")
    second: login(pass: 2222, username: "ivan")
    third: login(pass: 3333, username: "ivan")
    fourth: login(pass: 4444, username: "ivan")
  }

This is effectively the same query (login) that is aliased to different names.

Or this query, which can easily DoS your server.

  query {
    getUsers(first: 1000)
    second: getUsers(first: 2000)
    third: getUsers(first: 3000)
    fourth: getUsers(first: 4000)
  }

There are a couple of techniques that can be used to prevent this kind of problem one of them is GraphQL Query Complexity Analysis which is, as the name suggests, very complex to implement correctly. It requires analysis of how the graphql API is used, and what queries and mutations are most often called. If you get this wrong, there is a danger of the server denying perfectly valid queries.

The second solution that can somewhat eliminate this problem is implementing grapql dataLoader(https://github.com/graphql/dataloader) which is also tricky to get right, and it will require you to change your resolvers.

The third solution which I will present here is to simply disable duplicate queries and mutations.

How it works

While the alias functionality cannot be directly disabled (at least not in the current Grahpql JS implementation), we need to analyze the query that is coming to the server and if it contains duplicate queries and mutations, simply deny the request.

To deny the request we need to hook in the validation phase of the GraphQL server. The validation phase is the phase when the request is received by the server, but before it is executed, at that point we can decide if we want to proceed with the execution of the request, or immediately return to the client with the reason why the request has been denied.

For this, we are going to use GraphQL No Alias library.

There are two ways to use this library:

Using the @noAliasdirective in the schema
Using the configuration options (better performance)

Using the directive

There are two parts, a directive that needs to be added to the schema, and a validation function that needs to be added to the GraphQL validationRules array.
In the next example, we are going to start implementing the @noAlias directive by limiting all mutations to only one of each (by specifying the directive directly on the mutation type), and we are going to limit query hello to maximum 2 calls in the same request. For the actual GraphQL server we are going to use express-graphql but the directive should work with any server implemented in javascript.
In the upcoming examples I'm going to use express-graphql as the graphql server, simply because it is easiest to setup, however useage with any other server is the same.

const express = require('express')
const { graphqlHTTP } = require('express-graphql')
const { buildSchema } = require('graphql')

const {createValidation} = require('graphql-no-alias')

// get the validation function and type definition of the declaration
const { typeDefs, validation } = createValidation()

//add type defintion to schema
const schema = buildSchema(`
  ${typeDefs}
  type Query {
    hello: String @noAlias(allow:2)
  }

  type Mutation @noAlias {
    login(username:String, password:String):String
    getUsers(startingId:String):String
  }
`)

const app = express()
app.use(
  '/graphql',
  graphqlHTTP({
    schema: schema,
    rootValue: root,
    graphiql: true,
    validationRules: [validation] //add the validation function
  })
)
app.listen(4000)

Now if you send a query like this:

  query {
    hello
    hello_2: hello
  }

It will pass however, this query will not (because the maximum allowed calls for query hello is 2 calls)

  query {
    hello
    hello_2: hello
    hello_3: hello
  }

And for the mutation:

  mutation {
    login(pass: 1111, username: "ivan")
    second_login: login(pass: 2222, username: "ivan")
  }

This will fail because you can't have any duplicate mutations (@noAlias directive is set directly on the Mutation type, with no value, which means that the default value of 1 will be used.

And that's it, that is all it takes to manipulate the number of queries and mutations in GraphQL requests.

Next, we are going to look at using the graphql-no-alias validation imperatively.

Imperative configuration

There is another way to use graphql-no-alias validation directive, and that is with the imperative configuration.

When using imperative configuration there is no need for type definition and schema modification, this also results in better performance since the schema is not analyzed (not looking for directives). All we need to do is to create a simple Javascript object with appropriate keys and pass that object to the createValidation function.

const permissions = {
  Query: {
    '*': 2, // default value for all queries
    getAnotherUser: 5 // custom value for specific query
  },
  Mutation: {
    '*': 1 //default value for all mutations
  }
}
const { validation } = createValidation({ permissions })

const schema = buildSchema(/* GraphQL */ `
  type Query {
    getUser: User
    getAnotherUser: User
  }
  type User {
    name: String
  }
`)

const app = express()
app.use(
  '/graphql',
  graphqlHTTP({
    schema: schema,
    rootValue: root,
    graphiql: true,
    validationRules: [validation] //add the validation function
  })
)

That's it, that is all it takes to disable multiple identical queries and mutations to be sent in a single request to a GraphQL server.

Make sure to check out the library on Github for more usage examples.

Bonus

I've also created another validation library: No batched queries, which limits the number of all queries and mutations that could be sent per request. It pairs nicely with this validation, so you could allow, for example, 3 queries to be sent and then use noAlias to disable duplicate queries.

Handling HTML Forms with Mobx and Dumba.js library

Ivan V. — Sun, 23 Jan 2022 19:34:32 +0000

In this short post, I'm going to walk you through how I'm handling HTML forms with Mobx.js. I've developed my own little library (~2.4Kb) for handling HTML forms with Mobx, which makes the forms fully reactive. It supports fields that depend on other fields and asynchronous validation.

You can checkout the demo that shows pretty much all the functionality of the library or check out the source (library and demo)on github

Usage

To use the library we need to create the schema object, which declares what fields exist and what validation tests to use for every field.
In the example below we are going to create a schema with only one field (email) and that field will have only one validation (there could be an array of validations), that will check if the field value is a valid email address.

import { createField, createValidation } from 'dumba'
import isEmail from 'validator/lib/isEmail'

const schema = {
  email: createField({
    value: 'admin@example.com',
    validations: createValidation(
      (str: string) => isEmail(str),
      'Not a valid email'
    )
  })
}

After we create the schema, we use the Form class to create the class instance that will be connected to the actual HTML form. Form instance accepts the schema.

import { Form } from 'dumba'
import { schema } from './schema'
const form = new Form(schema)

When the form instance is created, we use it to connect the fields to the actual HTML form. The form will have all the fields from the schema e.g.

const form = new Form(schema)
form.fields.email.value // field value
form.fields.email.onChange //field change event handler to connect to html input
form.fields.email.errors // array of validation errors (if any)

// also there are properties and methods on the form instance itself

form.isValid // boolean if the form is valid
form.isSubmitting// boolean if form is in the process of submitting
form.isValidating // boolean if the form is in the process of validating (async validations)
form.handleSubmit // submit the form function

Now, let's connect the form to the Material UI TextField as an example

//using material ui just as an example
import TextField from '@material-ui/core/TextField'
import { observer } from 'mobx-react-lite'
import { Form } from 'dumba'
import { schema } from './schema'

//declare it outside of the component, usual Mobx rules apply.
const form = new Form(schema)

const FormDemo = observer(function FormDemo() {
  //form submit function
  const handleOnSubmit = () =>
    form.handleSubmit((form: Form) => Promise.resolve(true))

  return (
    <form onSubmit={handleOnSubmit} autoComplete="off" noValidate>
      <TextField
        type="text"
        id="email"
        name="email"
        label="Email"
        // disable while submit is in progress or async validation is running
        disabled={form.isSubmitting || form.isValidating} 
        value={form.fields.email.value}
        onChange={form.fields.email.onChange}
        onBlur={form.fields.email.onChange}
        // mark field as invalid (if there are any email errors)
        error={!!form.fields.email.errors.length}
        helperText={<DisplayErrors errors={form.fields.email.errors} />} // display error text
        autoComplete="off"
      />
      <Button //form submit button
        variant="contained"
        color="primary"
        type="submit"
        disabled={
          // disable button while submit or async validation is in progress or form is invalid or not yet validated
          form.isSubmitting ||
          form.isValidating ||
          !form.isValid ||
          !form.isValidated
        }
      >
        Submit
      </Button>
    </form>
  )
})

And that's the gist of it. There is a lot more you can do with the library. For example, you can create fields that depend on other fields.

In the next example, we are going to create two schema fields location and numPeople. The latter will depend on the former which means that every time the location field value changes, a validation test for numPeople will also run.

const schema: SchemaType = {
  location: createField({
    value: 'beach' // or pool
  }),
  numPeople: createField({
    value: '',
    dependsOn:['location'] // depends on the location field above
    validations: [
      createValidation(
        (partyPeople: number, _field: Field, locationDependancy?: Field) => {
          if (locationDependancy?.value === 'pool') {
            if (partyPeople > 20) {
              return 'max pool party attendance is 40' // error message
            }
            return true //valid
          }
          if (locationDependancy?.value === 'beach') {
            if (partyPeople > 200) {
              return 'max beach party attendance is 200' // error message
            }
            return true //valid
          }
        }
      )
    ]
  })
}

This little library has sped up my form handling workflow considerably, so I've decided to open source it.
I hope you find it useful.

Demo

Demo source

Library

Full Page Transitions with Next.js

Ivan V. — Sat, 24 Jul 2021 22:12:18 +0000

I'm going to show you how to do full page transitions with Framer Motion and Next.js
Basic familiarity with Framer Motion and next.js is good to have, but the code is short and not complicated so everyone should be able to follow along.

Check out the demo: https://nextjs-full-page-transitions.netlify.app/
Fork the repository: https://github.com/ivandotv/nextjs-page-transitions

What we are building

Not only we are going to enable full page transitions but we are also going to set up a few different transitions for demo purposes.

The code

Spoiler alert, this is all the code that is needed to enable page transitions in Next.js!

// _app.tsx
function MyApp({ Component, pageProps, router }: AppProps) {
  return (
    <div className="app-wrap">
      <LazyMotion features={domAnimation}>
        <AnimatePresence exitBeforeEnter>
          <m.div
            key={router.route.concat(animation.name)}
            className="page-wrap"
            initial="initial"
            animate="animate"
            exit="exit"
            variants={animation.variants}
            transition={animation.transition}
          >
            <Component {...pageProps} />
          </m.div>
        </AnimatePresence>
      </LazyMotion>
    </div>
  )
}

Now let us go through it step by step.

First, you will notice that I'm using LazyMotion component, instead of regular Motion component, this is just for reducing the size of the bundle. Framer is not a small library
(around 25kb full), and since this code goes into the Next.js _app component, which is the main component in the framework, everything that is imported there, will be bundled in the initial bundle download

When you build the project this is indicated by the First Load JS shared by all item in the Next.js build report.

Granted, LazyMotion will not slice the size of the bundle by much (around 5-7kb) but why not use it when it's available. Also, the folks that support Framer
are working on reducing the bundle size even more, so you are ready to receive more size savings in the future.

You will notice that we are using features={domAnimation} on the LazyMotion component which means that we are only bundling a subset of Framer functionality. Things like pan and drag gestures and layout animations will not be available. Check out the official documention for the component to know more.

AnimatePresence Component

AnimatePresence component is used for animating child components when they are removed from the React tree. It
allows the component to defer unmounting until after the animation is complete. The most crucial property for this component is
exitBeforeEnter, it allows Framer to animate one component at a time.
So the page, which is the Component in this whole setup, after a route change will animate out and then the new page (which is also a Component) will animate in. So there will be no overlap and we only get to see one page at any given time.

UPDATE:
I have updated the demo to show how transitions work when exitBeforeEnter is set to false. When this property is false it will enable animations on both pages (new and old at the same time). Make sure to enable the "overlap page transitions" checkbox.

m.div component

Motion and m components are the main building blocks for Framer animations. Anything you want animated should go inside these components.

m.div component is very similar to regular Framer Motion component. It is an optimized version that works in tandem with LazyMotion.

By default, the motion component comes pre-bundled with all of its features. The m component can be used in the same way as Motion, but it comes with no features preloaded. These are then provided by LazyMotion.

Animations

Framer supports a lot of different ways to create the actual animations, in this demo we are going to use the labels functionality of Framer to animate the components. Take a look at this basic example, it will animate ComponentToAnimate opacity from 0 to 1 and then back to 0.

function MyApp() {
  return (
    <m.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      exit={{ opacity: 0 }}
      transition={{ duration: 0.7 }}
    >
      <ComponentToAnimate />
    </m.div>
  )
}

initial - How the element should look when the element is mounted into the React tree (before the animation starts)
animate - How it should look when the animation ends (basically when it's animated into position)
exit - How it should look when it's animated out (just before it's removed from the React tree )
transition - how will the actual animation behave duration, easing, etc. It is similar to the css transitions property.

Our page animations are a little bit more complicated than that, and we are also dynamically changing animations in the demo, so we are going to add another property to the m.div component

variants - this will allow us to organize animations as objects, and refer to them by name, and switch between them on demand.

Simple example is worth 1000 words:

const myAnimation = {
  initial: {
    opacity: 0
  },
  animate: {
    opacity: 1
  },
  exit: {
    opacity: 0
  },
  transition: {
    duration: 0.7
  }
}

function Component() {
  return (
    <m.div
      initial="initial"
      animate="animate"
      exit="exit"
      transition={myAnimation.transition}
      variants={myAnimation}
    />
  )
}

So now we can easily switch animations by providing a different object to the variants property (myAnimation). In the demo, we are doing this via the HTML dropdown elements and simple useState hook. You can refer to the animations.ts file to see all the animations that are used in the demo

// animations.ts excerp
const slideUp = {
  name: 'Slide Up',
  variants: {
    initial: {
      opacity: 0,
      top: '100vh',
      scale: 0.4
    },
    animate: {
      opacity: 1,
      top: '0vh',
      scale: 1
    },
    exit: {
      opacity: 0,
      top: '100vh',
      scale: 0.4
    }
  },
  transition: {
    duration: 0.7
  }
}

const slideRight = {
  name: 'Slide Right',
  variants: {
    initial: {
      opacity: 0,
      left: '-100%',
      scale: 0.6
    },
    animate: {
      opacity: 1,
      left: 0,
      scale: 1
    },
    exit: {
      opacity: 0,
      left: '100%',
      scale: 0.6
    }
  },
  transition: {
    duration: 0.7
  }
}

And that's it. As you can see, full-page transitions in Next.js with Framer Motion library are not that complicated :)

Check out the demo: https://nextjs-full-page-transitions.netlify.app/
Fork the repository: https://github.com/ivandotv/nextjs-page-transitions

Protecting static pages in Next.js application

Ivan V. — Mon, 05 Apr 2021 21:44:30 +0000

In this article, I will explain how to structure your Next.js application so you can protect your static pages from unauthenticated access.
I will concentrate on the implementation logic and authentication flow, and not on any particular authentication provider, so we won't be dealing with client-side tokens or cookies (which I will probably do in a separate blog post).

You can interact with the example
Or you can check out the repository

Authentication Setup

We will create a couple of pages:

public pages accessible to everyone
protected pages where the user if not authenticated, will be automatically redirected to a signin page.
signin page with a simple sign-in form.
signout the page where the user will be redirected to after successfully sign out.

src/pages/
├── _app.tsx
├── index.tsx
├── protected.tsx
├── protected-two.tsx
├── public.tsx
├── signin.tsx
└── signout.tsx

Sign In Flow

It goes like this when the user lands on a public page (or index) those pages will immediately render. If the user lands on a protected page while not signed in, she will be redirected to the sign in page, and after the successful authorization, she will be redirected back to the protected page where she started.

There are two authentication components AuthProvider and AuthGuard, they work in tandem to provide all the logic needed for protecting the pages.

AuthProvider Component

AuthProvider will utilize React context and as I said, we will not concentrate on a particular authentication provider (Firebase, Auth0, AWS Cognito, etc.) rather we will have an abstract demo provider that will expose a hook useAuth that will return a couple of properties, were most important ones are a user object (with all the user data you need) and an initializing property to indicate if the AuthProvider is in the process of initializing i.e. trying to determine if the user is signed in or not ( in case of third party providers it would contact authentication provider service to validate currently present tokens or cookies).

In general you should always abstract any third-party providers that you use in your application so you can always replace them if the need arises with as little refactoring as possible.

So AuthProvider component will be the source of truth for all user authentication data and it will wrap the whole application (it will live in _app.tsx) so we can access user data from anywhere in the application (both on protected and public pages).

AuthGuard Component

AuthGuard component is the second part of the authentication setup. It wraps every page that needs to be protected, and it holds the logic to determine what to do depending if the user is authenticated or not.

Since it is wrapped by AuthProvider (the whole application is) it has access to the user data and it will not render a protected page if the user does not exist rather, it will remember what page the user tried to access while not being authenticated (so it can redirect the user back to that same page after a successful sign-in) and immediately redirect to the signin page. Then after the user sign in (on the signin page) she will be redirected back to where she started.

It is important to note that AuthGuard in this current implementation is redirecting to the sign-in page, but it is very easy to change the component to do something else, for example, to show a sign in form immediately (on the protected page) I just think the best UX is to redirect to a special page that handles the sign-in process.

// AuthGuard.tsx
import { useAuth } from "components/AuthProvider"
import { useRouter } from "next/router"
import { useEffect } from "react"

export function AuthGuard({ children }: { children: JSX.Element }) {
  const { user, initializing, setRedirect } = useAuth()
  const router = useRouter()

  useEffect(() => {
    if (!initializing) {
      //auth is initialized and there is no user
      if (!user) {
        // remember the page that user tried to access
        setRedirect(router.route)
        // redirect
        router.push("/signin")
      }
    }
  }, [initializing, router, user, setRedirect])

  /* show loading indicator while the auth provider is still initializing */
  if (initializing) {
    return <h1>Application Loading</h1>
  }

  // if auth initialized with a valid user show protected page
  if (!initializing && user) {
    return <>{children}</>
  }

  /* otherwise don't return anything, will do a redirect from useEffect */
  return null
}

Creating Protected Pages

It is important to note that protected pages have no logic regarding the protection process. So in our case, it is just a regular Next.js page. If the page component is rendered it means that the user exists and is authorized to access the page. Remember, since that page is wrapped inside the AuthGuard and AuthProvider, all that logic is already resolved by the time the page is rendered.
So by now, you might be asking "How AuthGuard knows what pages to protect?" Good question. The answer is very simple, every Nextjs component has a special property requireAuth set to true.

import { PageLinks } from "components/PageLinks"

export default function Protected() {
  return (
    <div>
      <h1>Protected Page One</h1>
      <PageLinks />
    </div>
  )
}

Protected.requireAuth = true

Then, inside the _app.tsx we check if the component has the requireAuth property and if true we wrap it with the AuthGuard component.

// _app.tsx

export default function MyApp(props: AppProps) {
  const {
    Component,
    pageProps,
  }: { Component: NextApplicationPage; pageProps: any } = props

  return (
   <AuthProvider>
     {/* if requireAuth property is present - protect the page */}
     {Component.requireAuth ? (
       <AuthGuard>
         <Component {...pageProps} />
       </AuthGuard>
     ) : (
       // public page
       <Component {...pageProps} />
     )}
   </AuthProvider>
  )
}

And that's all it takes to have protected and public static pages in Next.js.

But remember, the only source of truth for all your application data is the server, so even though the pages will not render for unauthorized users, your backend server should always check for authorization before doing any CRUD.

You can interact with the example
Or you can check out the repository

Simplify your browser fetch() calls

Ivan V. — Fri, 19 Feb 2021 21:52:47 +0000

This one is going to be short and sweet :). We are going to simplify using browser fetch function by creating a wrapper function (330 bytes gzipped) around fetch.

So after writing the fetch code probably hundreds of times, I've decided it's time to simplify it a little bit.

So instead of this:

try {
  const response = await fetch('https://example.com')
  // ok is true only for 200-299 response codes 
  if (response.ok) { 
    const data = await response.json()
  } else {
    throw response
  }
} catch (e) {
  console.log(e)
}

I can do this:

import fetch from 'nice-fetch'

try {
  const [data, response] = await fetch('https://example.com')
} catch (e) {
  console.log(e)
}

A small improvement I know, but it adds up over time :)

Usage

nice-fetch accepts the same arguments as regular fetch with one additional argument which is the type of the body from the response that you expect to be returned, the default value is json. This determines how the response body content should be handled.

// if (response.ok)
const data = await response.json() // <- json is the default
// } else {

Other parameters are all available methods on the Body mixin

for example:

import fetch from 'nice-fetch'

// data is JSON (default)
const [data, response] = await fetch('https://example.com')

// data is JSON
const [data, response] = await fetch(
  'https://example.com',
  { method: 'GET' },
  'json' // <- explicit
)

// data is Blob
const [data, response] = await fetch(
  'https://example.com',
  { method: 'GET' },
  'blob'
)

// data is string
const [data, response] = await fetch(
  'https://example.com',
  undefined // <-- pass undefined for RequestInit
  'text'
)

Return values

The function returns a tuple of data, which is already handled response content (no need for response.json() call) and the original response object.

Error handling

When you write code like this, all errors can be handled in the catch block.

try {
  const [data, response] = await fetch('https://example.com')
} catch (e) {
  console.log(e)
}

In case that the response.ok is not true (status is not in the range 200–299) fetch will throw with the full Response object

In case that the response body content can't be properly handled e.g. invalid JSON, the function will rethrow the error.

In case there is an error from the fetch call itself ( Network request failed, timeout) function will also rethrow that error.

You can install it with:

npm i nice-fetch

repository: nice-fetch
I hope you find it useful.

Automate Publishing of Your Github Repository to Docker Hub

Ivan V. — Mon, 18 Jan 2021 18:50:33 +0000

In this blog post, I'm going to show you how to create a Docker image from your github repository and publish it to the Docker hub container registry. So anytime you cut a new release or commit to the master branch, Github actions will build your image and push it to the registry.

Why?

Why would you publish your repository as a Linux container image? Good question. Not all projects should be published as Linux container images. The rule of thumb is if your code can be used as a standalone piece of software (front-end and back-end applications, servers, databases, command-line programs) then it could and it should be packaged as a Linux container.

By publishing your code to the container registries ( it doesn't have to be a Docker registry) you can automate the deployment of your apps by pulling those published containers to your hosting providers, stopping the old ones, and running the new ones ( I'm going to show you how to do this in a future article).

The Plan

This tutorial will be software language-agnostic since we are not going to concentrate on the process of packaging the code itself, but we are going to concentrate on setting up continuous integration and tying it all together (although the example repository is a Node.js server application).

The Code

When building software one very important rule is that the master branch should always be deployable. So we are only ever going to publish Docker images from the master branch although you could publish from different branches and create different images such as canary, beta etc...

So we have two options for the master branch. We could publish the images on every commit to the master or we could publish the images only when we create/publish a new release.
If you are unsure what Github releases are and how to use them, you can consult Github documentation.

This is all the code that is needed for the github actions workflow.

name: Build and publish Docker image
on:
  release:
    types: [published]
# on:
#   push:
#     branches:
#       - master
jobs:
  push_to_registry:
    name: Build and publish
    runs-on: ubuntu-latest
    steps:
      - name: Get release tag
        id: tag_name
        run: echo ::set-output name=SOURCE_TAG::${GITHUB_REF#refs/tags/}
      - name: Check out the repo
        uses: actions/checkout@v2
      - name: Npm Install
        run: npm ci
      - name: Npm Build
        run: npm run build
      - name: Login to DockerHub
        run: echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
      - name: Build image
        env:
          SOURCE_TAG: ${{ steps.tag_name.outputs.SOURCE_TAG }}
        run: ./docker-image/build.sh
      - name: Docker Hub Description
        uses: peter-evans/dockerhub-description@v2
        env:
          DOCKERHUB_USERNAME: ${{ secrets.DOCKER_USERNAME }}
          DOCKERHUB_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
          DOCKERHUB_REPOSITORY: ivandotv/grant-server

Now, I'm going to explain each step individually.

First, we need to respond to the event that is triggered on the repository. In our case, we are responding to the release event of type published. This means that the workflow will only ever be triggered when this event happens. There are a few ways you can trigger the release event on the repository, you can automate it (by creating another workflow that does this for you), or you can do it manually. You can read more about the github workflow events from the official documentation.

on:
  release:
    types: [published]

Or if you want to respond to every push to the master branch you can use this code (commented out in the original):

 on:
   push:
     branches:
       - master

Next, we need to set up a job that is going to do all the heavy lifting. The job id is push_to_registry and the name is "Build and publish". It is going to run on Ubuntu 20.04

jobs:
  push_to_registry:
    name: Build and publish
    runs-on: ubuntu-20.04
    steps:
    # see next step

The Steps

1 - Since we are building the image after a new release (which always should have a git tag) we are going to retrieve that tag, which will later be used in step 6. In case if you are using a push to master event then you should use the latest commit data instead of a tag, something like git rev-parse --short HEAD.

- name: Get release tag
  id: tag_name
  run: echo ::set-output name=SOURCE_TAG::${GITHUB_REF#refs/tags/}

2 - Check out the repository. This means that we are going to have the full repository (all the files) to work with inside our workflow.

- name: Check out the repo
  uses: actions/checkout@v2

3 - Since the example is a Node.js application we are going to install all node package dependencies we need:

- name: Npm Install
  run: npm ci

4 - Build the application by running the build script from the package.json.
Note that the build script could run other tasks like lint and test but at this point, we are counting on that the application works as expected since all the testing should be done in some previous workflow that you have set up when pushing commits to your branches.

- name: Npm Build
  run: npm run build

5 - Login to Docker hub. For this step, you need to setup github secrets (that are going to be available inside the workflow). We need docker username and docker password. How to create secrets is explained in Github docs

- name: Login to DockerHub
  run: echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin

6 - Build the image. Building the Docker image involves a few command line calls, so the best thing is to create a script that will group all those commands in a single file that you can run easily. We are setting the SOURCE_TAG environment variable that we are referencing from the previous step (steps.tag_name - step 1), this variable will be picked up by the script ./docker-image/build.sh (this is the file inside the repository itself) and be used to tag the docker image before pushing to Docker hub.

- name: Build image
  env:
    SOURCE_TAG: ${{ steps.tag_name.outputs.SOURCE_TAG }}
  run: ./docker-image/build.sh

7 - Optional. Since Docker hub images also have the concept of a README file, we are going to take the README.md from the repository and also put it up on the Docker hub. That way we have only one source for the documentation, both for the Github repository and the Docker hub.

- name: Docker Hub Description
   uses: peter-evans/dockerhub-description@v2
   env:
    DOCKERHUB_USERNAME: ${{ secrets.DOCKER_USERNAME }}
    DOCKERHUB_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
    DOCKERHUB_REPOSITORY: ivandotv/grant-server

That is all it takes to automate the publishing of container images to the Docker hub.

Now, if you take a look at the repository (link provided below) you will find workflow files in .github/workflows directory.

.github/
└── workflows
    ├── CI.yml
    └── docker-build.yml

There are two files: CI.yml and docker-build.yml. Code referenced in this tutorial is from the later file, the former one is used to test the code, publish to NPM and create and then tag a release. That file triggers the release event that workflow in this tutorial (docker-build.yml) is using to start the publishing process. If you are developing JavaScript applications you might want to look at that file as well.

Next, we have docker-image directory with two files

docker-image/
├── build.sh
└── Dockerfile

I haven't covered those files in this tutorial because they are used for building the actual Docker image itself, build.sh file contains command-line instructions on how to prepare for the build process, and Dockerfile contains instruction for building the image.

Repository: ivandotv/grant-server
Docker hub page: Grant server

Thank you for reading.