DEV Community: Tom Ray

How to build a NestJS Docker image for production

Tom Ray — Sun, 15 May 2022 10:16:33 +0000

When deploying my NestJS project, I found there wasn't loads online on how to write the Dockerfile to build the Docker image needed for containerized deployment.

So I wrote this guide which takes you through step-by-step how to setup a Docker image for your NestJs project!

Ready? Let's dive in.

P.S. if you want to just copy and paste the production ready Dockerfile, just skip to this section.

Writing the Dockerfile

A container image is an isolated package of software that includes everything you need to run the code. You can define container images by writing a Dockerfile which provides the instructions on how to build the image.

Let's add the Dockerfile now:

touch Dockerfile

And then let's add the instructions to the Dockerfile. See the comments which explain each step:

# Base image
FROM node:18

# Create app directory
WORKDIR /usr/src/app

# A wildcard is used to ensure both package.json AND package-lock.json are copied
COPY package*.json ./

# Install app dependencies
RUN npm install

# Bundle app source
COPY . .

# Creates a "dist" folder with the production build
RUN npm run build

# Start the server using the production build
CMD [ "node", "dist/main.js" ]

Similar to a .gitignore file, we can add a .dockerignore file which will prevent certain files from being included in the image build.

touch .dockerignore

Then exclude the following files from the image build:

Dockerfile
.dockerignore
node_modules
npm-debug.log

Test the container locally

Let's now do some testing locally to check if the Dockerfile behaves as we expect.

Let's first build the image using the command in your terminal at the root of your project (you can swap out nest-cloud-run with your project name). Don't forget the .!

docker build -t nest-cloud-run .

You can verify the image has been created by running docker images which will output a list of Docker images you have on your local machine:

docker images
REPOSITORY                   TAG       IMAGE ID       CREATED          SIZE
nest-cloud-run               latest    004f7f222139   31 seconds ago   1.24GB

Let's now start the container and run the image with this command (be sure to same image name used above):

docker run -p80:3000 nest-cloud-run

You can now access the NestJS app by visiting https://localhost in your browser (just https://localhost without any port numbers).

I ran into a couple of issues on my machine when running the container, mainly due to with conflicts with ports from other containers I had running.

If you run into similar trouble, you can try running the command docker rm -f $(docker ps -aq) which stops and removes all running containers.

Optimize Dockerfile for production

Now that we've confirmed the image is working locally, let's try to reduce the size of the image.

Deployment tools like Cloud Run factor in the size of the image when calculating how much to charge you, so it's a good idea to keep the image size as small as possible.

Running the command docker images gives us our image size:

docker images
REPOSITORY                   TAG       IMAGE ID       CREATED          SIZE
nest-cloud-run               latest    004f7f222139   31 seconds ago   1.24GB

1.24GB is pretty big! Let's dive back into our Dockerfile and make some optimizations.

Use Alpine node images

It's recommended to use the Alpine node images when trying to optimize for image size. Using node:18-alpine instead of node:18 by itself reduces the image size from 1.24GB to 466MB!

Use multistage builds

In your Dockerfile you can define multistage builds which is a way to sequentially build the most optimized image by building multiple images.

In practice, here's how we can use multistage builds in our Dockerfile:

# Base image
FROM node:18-alpine As development

# Create app directory
WORKDIR /usr/src/app

# Copy application dependency manifests to the container image.
# A wildcard is used to ensure copying both package.json AND package-lock.json (when available).
# Copying this first prevents re-running npm install on every code change.
COPY package*.json ./

# Install app dependencies
RUN npm install

# Bundle app source
COPY . .

# Creates a "dist" folder with the production build
RUN npm run build

# Base image for production
FROM node:18-alpine As production

# Create app directory
WORKDIR /usr/src/app

# Copy application dependency manifests to the container image.
# A wildcard is used to ensure copying both package.json AND package-lock.json (when available).
# Copying this first prevents re-running npm install on every code change.
COPY package*.json ./

# Install production dependencies.
# If you have a package-lock.json, speedier builds with 'npm ci', otherwise use 'npm install --only=production'
RUN npm ci --only=production

# Bundle app source
COPY . .

# Copy the bundled code
COPY --from=development /usr/src/app/dist ./dist

# Start the server using the production build
CMD [ "node", "dist/main.js" ]

Once you've updated your Dockerfile, you'll need to re-run the commands to build your image:

docker build -t nest-cloud-run .

And then the command to spin up your container:

docker run -p80:3000 nest-cloud-run

If you run docker images again to check our image size, you'll see it's now signifantly smaller:

docker images
REPOSITORY                   TAG       IMAGE ID       CREATED          SIZE
nest-cloud-run               latest    004f7f222139   31 seconds ago   189MB

Troubleshooting

You might come into the following errors:

Error: Cannot find module 'webpack'

It's likely you're using the wrong node version in your base image if you're getting errors like the following:

Error: Cannot find module 'webpack'
ERROR [development 6/6] RUN npm run build
npm ERR! nest-cloud-run@0.0.1 build: nest build

Instead of using FROM node:14-alpine, use FROM node:18-alpine to solve this issue.

Conclusion

In summary, here is our production optimized Docker image for a NestJS project:

# Base image
FROM node:18-alpine As development

# Create app directory
WORKDIR /usr/src/app

# Copy application dependency manifests to the container image.
# A wildcard is used to ensure copying both package.json AND package-lock.json (when available).
# Copying this first prevents re-running npm install on every code change.
COPY package*.json ./

# Install app dependencies
RUN npm install

# Bundle app source
COPY . .

# Creates a "dist" folder with the production build
RUN npm run build

# Base image for production
FROM node:18-alpine As production

# Create app directory
WORKDIR /usr/src/app

# Copy application dependency manifests to the container image.
# A wildcard is used to ensure copying both package.json AND package-lock.json (when available).
# Copying this first prevents re-running npm install on every code change.
COPY package*.json ./

# Install production dependencies.
# If you have a package-lock.json, speedier builds with 'npm ci', otherwise use 'npm install --only=production'
RUN npm ci --only=production

# Bundle app source
COPY . .

# Copy the bundled code
COPY --from=development /usr/src/app/dist ./dist

# Start the server using the production build
CMD [ "node", "dist/main.js" ]

Do you have any further optimizations you can make to the above image? Drop them in the comments below!

How to setup & deploy an Express GraphQL server

Tom Ray — Fri, 20 Aug 2021 13:01:24 +0000

This is a quick start guide to setting up a GraphQL API using Express, Apollo Server, Prisma, Heroku, Postgres, Docker and TypeScript.

When we're done, we'll have a GraphQL server that can be used by a front end to query and persist data from a Postres database.

I've noticed this tech stack rise in popularity in recent times.

Why? Probably because Heroku offers a free plan and the developer experience for Prisma and Apollo is 🔥.

Ready? Let's dive in 🤿.

Here's the Github repository if you'd like to review the code.

Prerequisites
Creating the project
Configuring Typescript
Hot reloading and scripts
Setting up the server with Apollo
Deploy to Heroku
Set up Postgres locally with Docker
Build your database schema with Prisma
Connect database to Graphql API
Adding Postgres to Heroku

Prerequisites

You'll need to ensure you have the following setup in order to complete this tutorial:

Git and Node.js installed on your machine
Docker installed on your machine. This is not required if you use something else for serving postgres locally
A free Heroku account for deploying the API

Creating the project

Jump into your terminal, create the directory and push the code up to a new repository in Github. You can skip this section if you're familiar with this process.

mkdir graphql-typescript-api-starter

Then let's setup Node.js in the project:

cd graphql-typescript-api-starter
npm init

This will walk you through a few questions to answer. These are optional - hit enter in your keyboard to skip through them.

Next, still in your terminal, add a .gitignore file which tells git which files to ignore.

touch .gitignore

Open up the project in your favourite editor and add the following to your .gitignore file for now:

node_modules

Next, create a Github repository and in the terminal, push your code up to the repository:

git init
git add -A
git commit -am "first commit"
git branch -M main
git remote add origin <your remote Github repository url>
git push -u origin main

Configuring TypeScript

We're going to be using TypeScript in this tutorial.

If you're not too familiar with TypeScript - don't fret.

This tutorial doesn't focus on how to use TypeScript, just how to set it up for a Node JS server side project.

First of all, add TypeScript as a dependency to your project:

npm install typescript --save-dev

This give us access to the tsc command locally which will compile our code from TypeScript to Javascript.

Let's now add type safety and auto-completion for core Node APIs (like path, http and fs):

npm install @types/node --save-dev

Next, we need to add a tsconfig.json file which sets our TypeScript compiler options. First, add the file to the root of your project:

touch tsconfig.json

Then paste in these compiler options:

{
  "compilerOptions": {
    "target": "es5",                          
    "module": "commonjs",                    
    "lib": ["es6"],                     
    "allowJs": true,
    "outDir": "build",                          
    "rootDir": "src",
    "strict": true,         
    "noImplicitAny": true,
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

Take a look at the docs if you'd like to learn what each configuration means and if you'd like to add more configuration options.

Hot reloading and scripts

Hot reloading in your local set up is fundamental to a decent developer experience. Otherwise you'll need to quit and restart the server everytime you make changes to your code.

We're going to use the packages nodemon and ts-node to set up hot reloading:

npm install ts-node nodemon --save-dev

nodemon watches for any changes in your code and restarts the server automatically, while ts-node enables the server to understand TypeScript directly (removing the requirement for compiling).

Next add a nodemon.json config file to the root of your project:

touch nodemon.json

And then add the following configuration:

{
  "watch": ["src"],
  "ext": ".ts,.js",
  "ignore": [],
  "exec": "ts-node ./src/index.ts"
}

Whenever you use nodemon in the command line, it will use these configurations.

A typical script to run your local dev environment is:

npm run dev

Let's set that up now. Open up your package.json file and add this script:

{
  ...

  "scripts": {
    ...
    // for running the server on your local machine, using nodemon
    "dev": "nodemon"
  },

  ...
}

Now you can run npm run dev in the root of your project to start up your server (which we'll do in the next step when we add a index.ts file).

We'll set up the build and start scripts (for production) in a later step when we deploy to heroku.

Setting up the server with Apollo

With some of the admin out of the way, let's set up our server!

We're going to use 3 packages to get started:

express: The Javascript server side framework
apollo-server-express: Allows us to setup a GraphQL API on top of Express
graphql: Allows us to write GraphQL in Javascript

Let's add them to our project now:

npm install express apollo-server-express graphql

Instead of using express and apollo-server-express, we could've just gone with apollo-server which is easier and simpler to get going.

However, I've opted with the Express option because it means we can add Node.js middleware like authentication and rate-limiting - things you'll very likely need if you're building out an API for use in production 👌.

With the packages installed, we can now whip up a server.

Create an index.ts file inside a directory called src:

mkdir src
touch src/index.ts

Then add the following code to the new file:

import { createServer } from "http";
import express from "express";
import { ApolloServer, gql } from "apollo-server-express";

// 1
const startServer = async () => { 

  // 2
  const app = express()
  const httpServer = createServer(app)

  // 3
  const typeDefs = gql`
    type Query {
      hello: String
    }
  `;

  // 4
  const resolvers = {
    Query: {
      hello: () => 'Hello world!',
    },
  };

  // 5
  const apolloServer = new ApolloServer({
    typeDefs,
    resolvers,
  })

  // 6
  await apolloServer.start()

  // 7
  apolloServer.applyMiddleware({
      app,
      path: '/api'
  })

  // 8
  httpServer.listen({ port: process.env.PORT || 4000 }, () =>
    console.log(`Server listening on localhost:4000${apolloServer.graphqlPath}`)
  )
}

startServer()

This code starts a server and listens on port 4000.

I've added numbered comments to the code - Let's dive into each part to understand what's going on here:

Create an asynchronous function to start the server. At the end of the code, you can see the function is called startServer().
Here we are creating an instance of express with const app = express() and then creating an HTTP server with const httpServer = createServer(app)
typeDefs define your API schema. Here you describe what data can be read and mutated by the frontend. For example:
- Fetch a list of items
- Fetch details about a profile
- Login a user
- Sign up a user
resolvers are responsible for handling the logic and response for each typeDef you defined. It's where the business logic is executed. Each typeDef will have a matching resolver. For example, in the typeDefs you might have defined a query to fetch a list of items. You'll need a matching resolver to handle the query (e.g. find the items in the database and return them)
Here you initialize an instance of ApolloServer, passing in the typeDefs and resolvers. This creates your GraphQL server, but as we're using Express, we'll need to apply it as middleware in the next step.
You must await apolloServer.start() before applying the ApolloServer instance as middleware
The ApolloServer instance is applied as middleware to the Express instance, enabling the GraphQL server. GraphQL is served over a single endpoint in contrast to REST APIs which expose a range of endpoints. By default, Apollo sets this endpoint to /graphql, but I've updated it to /api - this is optional.
If you've built any Express applicatons before, this step will be familiar to you. Here, we are telling the server to listen on a specific port, and log something to the server. We first look in a env file for the PORT key, and if it doesn't exist, then we'll use 4000 by default. The reason for the env lookup is for when we deploy with Heroku - using the env key allows the port to be defined by Heroku (otherwise there may be errors, such as a request timeout)

Nice work if you've made it this far!

Let's now start our server using the script we set up earlier.

npm run dev

In response, the terminal should output:

Server listening on localhost:4000/api

ss

Open localhost:4000/api in your browser and you'll be prompted to enter Apollo Studio. Press the "Query your server" button:

This is a testing environment for you to run your GraphQL queries and mutations.

For example, write the following query on the left side and hit the Run button:

query {
  hello
}

You should see on the right hand side the response:

{
  "data": {
    "hello": "Hello world!"
  }
}

You've just set up the foundations for a GraphQL API! Great work.

Everything you'll do from here will build on top of this foundational mental model:

typeDefs describe the queries and mutations available in the API
resolvers handle the logic and send the data back in the response

Next up, we'll be adding some more scripts and configuring our deployment to our production environment, Heroku.

Deploy to Heroku

You might be thinking:

"Isn't it too soon in the project to worry about deployment?"

Possibly. It's down to personal preference.

I prefer to release early and often.

Just like running the command npm run dev to run your server on your local machine, Heroku needs to know about a command so it can execute the script to start the server.

We'll create 2 scripts:

build - This will clean and compile our TypeScript code so it's ready for production
start - This will first run the build command and then it will execute the compiled code

In order to run the build script, we need to install a package called rimraf which takes care of the cleaning for us:

npm install rimraf --save-dev

Then you can add both the build and start scripts to your package.json file:

{
  ...

  "scripts": {
    ...
    "dev": "nodemon",
    "build": "rimraf ./build && tsc",
    "start": "npm run build && node build/index.js",
  },

  ...
}

Okay nice work! Your scripts are all now set up, so let's configure Heroku for deployment.

Firstly, You need to add a Procfile (this is a special Heroku file that tells the server what command to run when the application launches) to the root of your project:

touch Procfile

Then go into this new Procfile and add the following (this leverages the script we defined in the package.json file we added earlier on).

web: npm start

Okay! Make sure you've pushed up all the changes up to Github, then log in to your Heroku account.

First, create a new app:

Then, connect the project to the Github repository:

And then enable automatic deploys. This will mean every time you push a commit to the master branch, it will deploy a new version of the app:

By default, Heroku prunes the devDependencies when the server is launched. This is problematic as the server needs to use the rimraf script for the build script.

Therefore, you need to add an ENV variable in the Heroku app called NPM_CONFIG_PRODUCTION=false. Go to the Settings tab and add a Config Vars:

Finally, go back to the Deploy tab and press the Deploy Branch button to deploy the app:

Once it's finished, press the "Open app" in the top right, and edit the url to end in /api which is the path you defined in an earlier step.

And there you have it, you should see Apollo's default screen:

If you'd like to enable the GraphQL playground on the production environment, take a look at the Apollo docs.

Nice work! You've just set up a very basic GraphQL API and deployed it to production.

Set up Postgres locally with Docker

There's a little more admin work we need to do before we get into the fun stuff.

The goal for this tutorial is build a GraphQL API that can query and mutate directly to a database.

That means we'll need access to a database in our local and deployed environments.

We will set up the Postgres server for our deployed application in Heroku in the final step.

We'll use Docker for our local database.

If you're comfortable configuring your database server locally (e.g. you might use the Postgres app instead of Docker), you can skip this section.

That being said, Docker is pretty simple to setup, so as long as you have Docker installed on your machine, I'll walk you through it.

First of all, add a new file to the root of your project:

touch docker-compose.yml

Then navigate to this file and add the following code:

version: '3.8'
services:
  postgres:
    image: postgres:10.3
    restart: always
    environment:
      - POSTGRES_USER=test-user
      - POSTGRES_PASSWORD=test-password
    volumes:
      - postgres:/var/lib/postgresql/data
    ports:
      - '5432:5432'
volumes:
  postgres:

This file is responsible for running the Postgres server on your local machine.

The environment variables set the credentials for the database which we'll use when connecting Prisma to the database.

Now go ahead and launch this server by running:

docker-compose up -d

If you're using VSCode, I recommend installing the official Docker extension.

Once installed, it will apear in your left menu and show you which containers (i.e. local servers) you have running:

Nice work, your local Postgres server is now up and running.

Build your database schema with Prisma

In order for our GraphQL API to query and mutate data to a database, we first need to define how the database is structured.

We're going to use Prisma to define this structure. We'll also use Prisma in the next section to connect our GraphQL API to the database.

You can think of Prisma as a bridge between your database and your API - they provide a set of tools that make working with databases much easier.

First of all, add the Prisma CLI as a development dependency:

npm install prisma --save-dev

This allows you to use the Prisma CLI moving forward (the Prisma CLI is always prefixed with npx).

Next you need to set up Prisma in your project by running this command in the root of your project:

npx prisma init

This does two things:

Creates a directory called prisma with a file inside called schema.prisma
Adds an .env file to the root of the project

Let's first move the prisma directory into the src directory to keep things clean:

mv prisma/ src/

Because we've moved the prisma directory, we just need to add this to our package.json file so Prisma knows where to find it:

{
  ...

  "prisma": {
    "schema": "src/prisma/schema.prisma"
  }

  ...
}

The schema.prisma file is the main configuration file for Prisma. If you open up the file, you'll see the following:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

The datasource provides the connection to your Postgres database by looking up a url in the ENV file.

This is important - by using the env file, it allows us to have a different Postgres database for our various environments.

Right now, we have a local environment and a production environment in Heroku. We'll configure the Heroku Postgres database in the final step.

Your local Postgres server already exists (as we set this up in the previous step) - so we just need to grab these credentials and update our env file.

Open your docker-compose.yml file and grab the environment variables:

...
  postgres:
    ...
    environment:
      - POSTGRES_USER=test-user
      - POSTGRES_PASSWORD=test-password
...

In my case, the user is test-user and the password is test-password.

You can update these to your liking, but just make sure you restart your local Postgres server and then add the values to your env file:

DATABASE_URL="postgresql://test-user:test-password@localhost:5432/mydb?schema=public"

Now your Prisma configuration is using your local Postgres server as the data source.

It's now time to get to the fun stuff - creating tables in your database.

This is done inside the Prisma configuration file (schema.prisma) by adding models and then running a special Prisma command.

This tutorial won't get in to much detail on how to use Prisma - we'll stick to a simple example that you can expand on - their docs are very good.

Let's say we are building a Trello clone.

We could start with a model for the "Board". Add the following to your prisma.schema file:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Board {
  id          Int       @id @default(autoincrement())
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt
  title       String
  description String?
  path        String    @unique
}

The code is fairly self-explanatory (which is a testament to the Prisma team in itself!). Either way, here's a quick explainer of what's happening:

A new model (i.e. table in the database) has been defined as "Board"
The table is defined with a field name, a field type and optional attributes
- The field name maps to the column in that table. Typically is camelCase.
- The field type defines the native database type
- Attributes are handy modifiers Prisma provide you. E.g. the @unique attribute on the path field means that each record in the "Board" table must have a unique string stored as a path.
- You may have noticed the ? appended to the String field type for the description. This is a type modifier. ? makes a field optional.

If you open a GUI tool like TablePlus and open up your local Postrgres server to view the tables, you'll see nothing.

That's because we need to run a Prisma command to map the model you've defined into your database (i.e. run "migrations").

Here's the command to run:

npx prisma migrate dev --name init

Everytime you add a new model (or tweak any existing model structure), you'll need to run this command. So I find it helpful to add a new script for this:

{
  ...

  "scripts": {
    "dev": "nodemon",
    "build": "rimraf ./build && tsc",
    "start": "npm run build && node build/index.js",
    // for running database migrations
    "migrate": "npx prisma migrate dev",
  },

  ...
}

Now anytime you need to run migrations you can run npm run migrate instead.

Great work, you just created your first table in a database with Prisma Migrate 🎉.

Now open up your GUI again and your table will be there:

You can take this example further by adding other models to your prisma.schema file, for example by adding some relations.

Just remember everytime you make changes to your models, you'll need to run your new script npm run migrate!

Whenever you run npm run migrate, you'll be prompted to add a name for the migration. This is optional, but a good idea to give the migration a name so you can easily look at your migration history.

Connect database to Graphql API

So we've defined the structure of our database with Prisma Models.

Now let's move into how we can access and manipulate that data.

We'll use Prisma Client to help make queries to our database. For that, we'll need to install an additional Prisma package:

npm install @prisma/client

One this package is installed, create a new file inside the prisma directory called client.ts:

touch prisma/client.ts

And then inside this new file, you need to instantiate the Prisma Client:

const { PrismaClient } = require('@prisma/client');

module.exports = {
  prisma: new PrismaClient(),
};

Now inside your src/index.ts file, you can import Prisma client so it's available to use for your queries and mutations:

const express = require('express')
const { ApolloServer, gql } = require('apollo-server-express')
const { prisma } = require('../prisma/client')

...

Okay, with that set up, let's build on our Trello clone example and use Prisma Client to fetch a list of "Boards" from the database.

Fetch a list of boards

Before we dive in to adding this a query for fetching a list of boards, it's worth adding some data to our database.

Otherwise, we'll build our query and get back empty results. Adding some records to the database will help us to validate our queries are working properly.

Thankfully, Prisma have made this super easy.

Run this command to open up Prisma Studio, a simple way to explore and manipulate the data in the database:

npx prisma studio

It will open Prisma Studio in a new tab in your browser, looking something like this:

Navigate into the Board model and press the "Add record" button:

Now, back to writing some GraphQL.

We want to write a query that looks up all Boards in the database, and returns them in an array.

Let's hop back into our src/index.ts file and add a new typeDef:

...

const typeDefs = gql`
  type Query {
    boards: [Board]
  }

  type Board {
    id: ID!
    title: String!
    description: String
    path: String!
  }
`;

...

The purpose of typeDefs is to:

Define the name of the query / mutation
Define the structure of the response

So here, we are creating a query called boards. This is the name of the query.

And you can see that this query returns [Board]. This defines the structure of the response. We're basically saying here:

When a boards query is called to the server, return an array (that's what the square brackets are for) of items, and each item should have the structure defined by the Board type.

But we've still not hooked up that array to retrieve data from the database - that's where resolvers come in:

...

const resolvers = {
  Query: {
    boards: () => {
      return prisma.board.findMany()
    }
  },
};

...

Here we're using a Prisma Client query called findMany, which pulls in all of the records.

If you now start up your server with npm run dev and run the query in the left section:

query {
  boards {
    id
    title
    description
    path
  }
}

Assuming you added some records with Prisma studio, your API will return a response:

Great work! You now have an GraphQL API that fetches data from a database.

If you're following this tutorial, review the Prisma docs and try to build out some CRUD functionality for "Boards":

Create a new board
View a board
Edit a board
Delete a board

Adding Postgres to Heroku

Our API is working locally.

With our local Postgres server and running npm run dev, we can run queries and mutations on our GraphQL API to view and manipulate data in our local database.

However, this is currently limited to our local machine.

The final step in this tutorial is to add to our Heroku set up we started earlier on by adding a hosted Postrges server.

Inside your Heroku project, navigate to the Resources tab, search for "Heroku Postgres" and enable the "Hobby Dev" plan:

This is a free plan so you won't be charged for it.

Once you've added this, if you navigate to the Settings tab and look at the Config Vars, you'll see that the DATABASE_URL has been added automatically for you.

The Config Vars in Heroku is the env file equivalent.

If you navigate to your prisma.schema file, you'll see that the datasource is pointing towards the DATABASE_URL in the env file.

This means that in the deployed Heroku environment, it will use the DATABASE_URL defined in the Config Vars.

The final step is the considerations for the database changes.

If you make some changes to the Prisma Models in your local machine and then run the npm run migrate command, this will make the database changes to your local database server.

However, the hosted database in Heroku will not know about these changes.

Therefore, you need to add a command that tells Heroku to run a migration command whenever there is a new deployment.

You can achieve this by adding to your Procfile:

web: npm start
release: npx prisma migrate deploy

And you're done!

Here's the Github repository again if you'd like to review the code. The repository is available as a Template Repository, which means you can use it as a starter repo for your next project!

If you have any questions about this tutorial, drop a comment below, open up an issue in the Github repository or send me a DM on Twitter!

Styled Components: A Quick Start Guide

Tom Ray — Sun, 09 Aug 2020 17:27:48 +0000

This is a quick start guide to learning Styled Components, the component-driven CSS methodology.

If you want to start practicing and applying Styled Components to your projects, this guide will help you get started.

Ready? Let's dive in:

Bonus: Download a free cheat sheet that will show you how to quickly get started with styled-components.

Styled Components Overview

Styled Components is a library for React & React Native to write and manage your CSS.

It's a "CSS-in-JS" solution, meaning you write your CSS in Javascript files (specifically within your components, which are Javascript files).

It's an extremely popular solution for managing CSS in React, with around 8 million npm downloads/month and 30k stars in Github.

A familiarity and understanding of React is recommended before diving into Styled Components.

A few benefits of the styled-components library are:

It's plain CSS. Yes, you're writing the CSS in a JS file, but the CSS syntax is unchanged.
Vendor prefixes are automatically added when using Styled Components, improving performance across browsers.
All unused CSS and styling gets removed automatically
You don't write any class names, whatsoever. Class names are generated automatically, so there's no need to manage a CSS class naming methodology like BEM. (This'll make more sense as you go through the article)

Installing styled-components

To get started with styled-components, you first need to install it into your project:

npm install styled-components

And on every file that you use styled-components, you'll need to add this import:

import styled from 'styled-components';

And that's it! You're ready to start working with styled-components.

Building your first styled component

Open up an existing React project you're working on (or quickly whip up a new project with create-react-app), and open up one of your existing components.

Here, you can add your first Styled Component.

Now that you have styled imported, here's how you get started:

// App.js
import React from 'react';
import styled from 'styled-components';

// Button component that'll render an <a> tag with some styles
const Button = styled.a`
  background-colour: teal;
  color: white;
  padding: 1rem 2rem;
`

const App = () => {
  return (
    <Button>I am a button</Button>
  )
}

export default App;

Let's break this code down:

Just like writing a React functional component, declare the name of the component with const Button
styled is what we imported above, and gives us the Styled Components functionality
Notice the a after styled? This represents the anchor HTML element: <a>. When declaring a Styled Component, you can use any HTML element here (e.g. <div>, <h1>, <section> etc.)

Make sense?

The <Button> returned inside the App component looks like a normal React component. And that's because it is a React component!

In our previous example, we created a Styled Component inside an existing component.

But you can also create a Styled Component in its own file.

For example, create a new component file called Button.js, and add a Styled Component:

// Button.js
import styled from 'styled-components';

const Button = styled.a`
  background-colour: teal;
  color: white;
  padding: 1rem 2rem;
`

export default Button;

Button now works like any other React component. For example, we can now import this component into other components files:

// App.js
import React from 'react';
import styled from 'styled-components';
// import the styled component:
import Button from './Button';

const App = () => {
  return (
    <Container>
      <Button>I am a button</Button>
    </Container>
  )
}

export default App;

And there you have it!

Congratulations, you just built your first Styled Component!

Using props to customize Styled Components

Imagine you have a <Button /> component, and you need to style different variants of that button (primary, secondary, danger, etc).

Styled Components have an elegant solution for this, where you leverage props to make your component styles dynamic.

Let's dive right into an example to show you what I mean.

Here we are rendering two Button components, one with a primary prop:

// App.js
import React from 'react';
import styled from 'styled-components';
import Button from './Button';

const App = () => {
  return (
    <>
      <Button>I am a button</Button>
      <Button primary>I am a primary button</Button>
    </>
  )
}

export default App;

And now, inside our <Button /> component, we can add the dynamic styles:

// Button.js
import styled from 'styled-components';

const Button = styled.a`
  display: inline-block;
  border-radius: 3px;
  padding: 0.5rem 0;
  margin: 0.5rem 1rem;
  width: 11rem;
  border: 2px solid white;
  background: ${props => props.primary ? 'white' : 'palevioletred' }
  color: ${props => props.primary ? 'palevioletred' : 'white' }
`

export default Button;

What's happening here is you're interpolating a function that is returning a CSS value (using a ternary operator) based on the props.

That was quite a mouthful.

To put it more simply, background: ${props => props.primary ? 'white' : 'palevioletred' } essentially means:

If the prop primary is true, then the background should be white, else the background should be palevioletred.

Handling props like this works in some use-cases, but it can get messy if you have multiple props (e.g. primary, secondary, danger, etc.) as well as multiple lines of CSS.

Often, it makes more sense to import { css } from styled-components like this:

// Button.js
import styled, { css } from 'styled-components';

const Button = styled.a`
  display: inline-block;
  border-radius: 3px;
  padding: 0.5rem 0;
  margin: 0.5rem 1rem;
  width: 11rem;
  background: transparent;
  color: white;
  border: 2px solid white;

  ${props => props.primary && css`
    background: white;
    color: palevioletred;
  `}
`

export default Button;

This keeps your dynamic styles separate for different props.

For example, adding styles for a danger prop would look like this:

// Button.js
import styled, { css } from 'styled-components';

const Button = styled.a`
  display: inline-block;
  border-radius: 3px;
  padding: 0.5rem 0;
  margin: 0.5rem 1rem;
  width: 11rem;
  background: transparent;
  color: white;
  border: 2px solid white;

  ${props => props.primary && css`
    background: white;
    color: palevioletred;
  `}

  ${props => props.danger && css`
    background: red;
    color: white;
  `}
`

export default Button;

Nice! We're making some good progress.

How about making this <Button /> a little more responsive, eh?

Bonus: Download a free cheat sheet that will show you how to quickly get started with BEM.

Using media-queries to make your styled-components responsive

Thankfully, making your Styled Components responsive is super simple.

Add media queries inside your template literal, like this:

// Button.js
import styled from 'styled-components';

const Button = styled.a`
  display: inline-block;
  border-radius: 3px;
  padding: 0.5rem 0;
  margin: 0.5rem 1rem;
  width: 9rem;
  background: transparent;
  color: white;
  border: 2px solid white;

  @media (min-width: 768px) { 
    padding: 1rem 2rem;
    width: 11rem;
  }

  @media (min-width: 1024px) { 
    padding: 1.5rem 2.5rem;
    width: 13rem;
  }
`

export default Button;

If you're looking for a more involved example with multiple different device sizes, I recommend checking out this Javascript Ramblings article.

Handling hover states and other pseudo-selectors with Styled Components

Similarly to adding media queries to your Styled Components, adding pseudo selectors is pretty straightforward.

For example, adding a hover state to our <Button /> component would look like this:

// Button.js
import styled from 'styled-components';

const Button = styled.a`
  display: inline-block;
  border-radius: 3px;
  padding: 0.5rem 0;
  margin: 0.5rem 1rem;
  width: 9rem;
  background: transparent;
  color: white;
  border: 2px solid white;

  :hover {
    border-color: green;
  }
`

export default Button;

Creating global styles

One of the main mental models of React is how you treat everything as components.

You essentially break an interface down into tiny chunks and piece it all together in a scalable way.

This approach comes with many advantages, but does however surface a challenge:

How to style parts of your design that are consistent across multiple components?

Or put another way:

How can you set global styles?

For example, you might want to:

Set a font-family for all your typography
Set the background color on every page
Override some browser default styling

Styled Components has a solution for global styles using the createGlobalStyle function.

First, navigate to the component which is at the top of your React tree.

For example, if you're working in a create-react-app project, that'll be your App.js file.

Here, you'll need to import createGlobalStyle into your project, and set some styles to a GlobalStyle component (you can name this component how you like):

// App.js
import React from 'react';
import styled, { createGlobalStyle } from 'styled-components';
import { Container, Nav, Content } from '../components';

const GlobalStyle = createGlobalStyle`
  body {
    margin: 0;
    padding: 0;
    background: teal;
    font-family: Open-Sans, Helvetica, Sans-Serif;
  }
`;

const App = () => {
  return (
    <Container>
      <Nav />
      <Content />
    </Container>
  )
}

export default App;

This isn't going to apply the styles to the project yet.

Now we need to use the GlobalStyle component to apply the global styles to the application.

You do this by placing the GlobalStyle component at the top of your React tree:

// App.js
import React from 'react';
import styled, { createGlobalStyle } from 'styled-components';
import { Container, Nav, Content } from '../components';

const GlobalStyle = createGlobalStyle`
  body {
    margin: 0;
    padding: 0;
    background: teal;
    font-family: Open-Sans, Helvetica, Sans-Serif;
  }
`;

const App = () => {
  return (
    <>
      <GlobalStyle />
      <Container>
        <Nav />
        <Content />
      </Container>
    </>
  )
}

export default App;

Notice the use of fragments short syntax?

This is required as you're placing the <GlobalStyle /> component as a sibling at the top of the tree.

And that's it!

Global styling is now all set up with Styled Components.

Conclusion

Nice job if you've made it all the way to the end.

We covered a lot! Specifically:

What Styled Components are and why you should consider using them
How to install styled-components
Building your first styled component
Making your Styled Components dynamic with props
Using media queries to make your Styled Components responsive
How to handle pseudo selectors with Styled Components
Setting global styles

Those are the fundamentals to get you off and running with Styled Components.

Like learning anything new, practicing is key. Give Styled Components a shot in your next project and see where it takes you!

Download Free Styled Components Cheat Sheet

Want to start practicing styled-components and looking for a no-nonsense, quick start action guide?

Download a free cheat sheet covering styled-components basics so you can dive in and start practicing today.

How to Create Global Styles with Styled Components

Tom Ray — Tue, 02 Jun 2020 14:46:13 +0000

If you've opted to use styled-components as a solution for managing your CSS, you'll quickly ask yourself:

The Styled Components library is all about styling individual components. So how can you apply styles globally to an application?

For example, you might want to:

Set a font-family for all your typography
Set the background color on every page
Override some browser default styling

In this post, I'll dive into exactly how you can achieve this with the createGlobalStyle function.

Please note: This solution is only applicable to web, so this won't work for react-native!

Ready? Let's do it.

Step 1: Create a global styles file

The first step is to create a file that contains all your global styles.

Inside your src/ folder, add a file called globalStyles.js.

Here, we'll use the createGlobalStyle function from styled-components and add some global styles:

// globalStyles.js
import { createGlobalStyle } from 'styled-components';

const GlobalStyle = createGlobalStyle`
  body {
    margin: 0;
    padding: 0;
    background: teal;
    font-family: Open-Sans, Helvetica, Sans-Serif;
  }
`;

export default GlobalStyle;

Inside the GlobalStyle variable is where you define all your global styles.

This isn't going to apply the styles to the project yet.

Now we need to use that file to apply the global styles to the application.

Step 2: Place GlobalStyle at the top of your React tree

Find your component which is at the top of your React tree.

In many react applications, that's typically the App.js file.

Here, import your GlobalStyle component and place it inside the the top of your React tree:

// App.js
import React, { Fragment } from 'react';
import GlobalStyle from './theme/globalStyle';
import Content from './components/Content';


function App() {
  return (
    <Fragment>
      <GlobalStyle />
      <Content />
    </Fragment>
  );
}

export default App;

In the above code example, <Content /> is a component that contains all the other components for the application.

This is just an example, and you might structure the top of your React tree differently, like this:

// App.js
import React, { Fragment } from 'react';
import GlobalStyle from './theme/globalStyle';
import Wrapper from './components/Wrapper';
import Nav from './components/Nav';
import Content from './components/Content';


function App() {
  return (
    <Fragment>
      <GlobalStyle />
      <Wrapper>
        <Nav />
        <Content />
      </Wrapper>
    </Fragment>
  );
}

export default App;

The important thing to remember is to place the GlobalStyle component as a sibling component to your main application component(s).

And that's it!

Global styling is now all set up with Styled Components.

Download The Free Styled Components Cheat Sheet

I'm currently working on a styled components 1-pager. Grab it here.

Quick Start Guide to Attrs in Styled Components

Tom Ray — Mon, 25 May 2020 13:27:31 +0000

When learning styled components, you may have noticed the use of attrs and be thinking:

Huh. What does this do? When would I need to use attrs?

The best way to explain the use case of attrs() in styled components is to dive right into some examples.

Ready? Let's do it.

Use Case 1: Defining Default Attributes

Here I've put together a simple button styled component:

import styled from 'styled-components';

const Button = styled.button`
  display: block;
  font-size: 1rem;
  font-weight: bold;
  color: white;
  border-radius: 4px;
  transition: 0.2s;
  cursor: pointer;
  border: none;
  padding: 1rem;

  &:hover {
    opacity: 0.7;
  }
`

export { Button };

And I'm going to use a couple of these styled button components in my app:

import React from 'react';
import { Button } from 'components/common';

const App = () => {
  return (
    <>
      <h1>Buttons</h1>
      <Button>Hello there</Button>
      <Button>Wassuuuupppp</Button>   
      <Button>Click me</Button>   
    </>
  )
}

export default App;

In case you didn't know, the default type for HTML buttons is type="submit".

So in my above design, when a button is clicked it will result in a page reload (becuase of the default behaviour).

But what if you wanted to change the default type to type="button"?

Or set any HTML attribute as default for that matter?

Well, you could add this as a prop directly to the component like this:

import React from 'react';
import { Button } from 'components/common';

const App = () => {
  return (
    <>
      <h1>Buttons</h1>
      <Button type="button">Hello there</Button>
      <Button type="button">Wassuuuupppp</Button>      
      <Button type="button">Click me</Button>      
    </>
  )
}

export default App;

However, if the attribute can be considered a default across your application, it's better to use the attrs() function instead and define the default there:

import styled from 'styled-components';

const Button = styled.button.attrs(props => ({
  type: props.type || 'button'
  // Every <Button /> will now have type="button" as default
}))`
  display: block;
  font-size: 1rem;
  font-weight: bold;
  color: white;
  border-radius: 4px;
  transition: 0.2s;
  cursor: pointer;
  border: none;
  padding: 1rem;

  &:hover {
    opacity: 0.7;
  }
`

export { Button };

This is much more efficient than adding a prop to every component if you find yourself turning to the same atrribute over and over.

Or put another way:

The rule of thumb is to use attrs when you want every instance of a styled component to have that prop, and pass props directly when every instance needs a different one
-Styled Components Docs

This means that we can ommit the default attribute, and only pass props when we want to change the default:

import React from 'react';
import { Button } from 'components/common';

const App = () => {
  return (
    <>
      <h1>Buttons</h1>
      <Button>Hello there</Button>
      <Button>Wassuuuupppp</Button>      
      // Add a prop to override the default defined in attr
      <Button type="submit">Click me</Button>      
    </>
  )
}

That is the simplest way to get started with attrs!

If you're looking to get more dynamic continue on to the next use case...

Use Case 2: Defining Dynamic Props

Building from the previous use case, using attrs also allows you to attach dynamic props to a component.

Sticking with our button example from use case 1, let's add a default size of our button:

import styled from 'styled-components';

const Button = styled.button.attrs(props => ({
  type: props.type || 'button'
}))`
  display: block;
  font-size: 1rem;
  font-weight: bold;
  color: white;
  border-radius: 4px;
  transition: 0.2s;
  cursor: pointer;
  border: none;
  /* define default margin and padding: */
  margin: 1rem;
  padding: 1rem;

  &:hover {
    opacity: 0.7;
  }
`

export { Button };

The above code will make the margin and padding for all buttons 1rem by default.

We can, however, make this more dynamic.

Let's say we want to make a larger version of the button, we could pass a size prop like this:

const App = () => {
  return (
    <>
      <h1>Buttons</h1>
      <Button size="2rem">Hello there</Button>
      <Button size="3rem">Wassuuuupppp</Button>      
      // Add a prop to override the default defined in attr
      <Button type="submit">Click me</Button>      
    </>
  )
}

And then in our styled component, we can make the margin and padding dynamic:

import styled from 'styled-components';

const Button = styled.button.attrs(props => ({
  type: props.type || 'button',
  size: props.size || '1rem'
}))`
  display: block;
  font-size: 1rem;
  font-weight: bold;
  color: white;
  border-radius: 4px;
  transition: 0.2s;
  cursor: pointer;
  border: none;
  /* pass the dynamic props: */
  margin: ${props => props.size};
  padding: ${props => props.size};  

  &:hover {
    opacity: 0.7;
  }
`

export { Button };

This leverages what we learned in use case 1:

We set the default size as 1rem, but if a specific prop is passed, it overwrites the default.

With this override, we can now dynamically set the margin and padding using the passed prop.

Summary

In short, the use case of attrs() in styled components is:

To define default HTML attributes in your styled components to save you passing the prop
When you want to override the default HTML attribute, pass props to a component that dynamically styles the component

Download The Free Styled Components Cheat Sheet

I'm currently working on a styled components 1-pager. Join the waiting list and be notified when it launches.

Launching BEM Basics: A Free Email Course on BEM

Tom Ray — Tue, 03 Mar 2020 11:58:27 +0000

Learning BEM is tricky.

Perhaps that's because BEM is a concept; a way of thinking.

Applying BEM in practice was always difficult for me as I struggled to find real, practical examples.

So I made a free course covering BEM fundamentals, with a focus on code snippets and examples.

Get access to the free course now.

This course is a sequence of emails that you’ll receive over the next 5 days.

Specifically, we’ll go over:

BEM Overview
BEM Ground Rules
B - Blocks
E - Elements
M - Modifiers

Enjoy!

How To Name Containers And Wrappers In BEM

Tom Ray — Tue, 18 Feb 2020 07:20:56 +0000

Are you unclear on BEM best practices for the naming conventions of wrapper and container CSS classes?

For example, you might have multiple blocks and you need to add a wrapper class to style the positioning of those blocks.

It becomes difficult to know how to name wrapper and container classes as they fall out of the 'block, element & modifier' mental model.

Let's dive right in and look at ways to solve this.

Bonus: Download a free cheat sheet that will show you how to quickly get started with BEM.

Repeated Wrappers: Airbnb Example

Here's a screenshot from Airbnb's home page:

Thinking with your BEM hat on, you'll notice:

Each card can be considered a BEM block (e.g. .card)
A wrapper is required to position the 5 blocks horizontally

Here's how the HTML would be structured following the BEM convention:

<div class="..."> <!-- Wrapper class goes here -->
    <div class="card">
        <img class="card__img" src="..." alt="...">
        <h4 class="card__subtitle">...</h4>
        <p class="card__description">...</p>
        <div class="card__rating">...</div>
    </div>
    <div class="card">...</div>
    <div class="card">...</div>
    <div class="card">...</div>
    <div class="card">...</div>
</div>

<style>
    .card {}
    .card__img {}
    .card__subtitle {}
    .card__description {}
    .card__rating {}
</style>

In fact, other sections of the Airbnb home page follow a similar structure. For example, the 'Airbnb Plus' section uses 3 columns instead of 5:

So the question is:

What is the BEM best practice naming convention for the wrappers?

In this case, as there are repeated patterns of how the wrappers work, the best approach would be to use a generic wrapper name like .grid.

This allows you to use the wrapper in multiple places as it's not constrained with semantic meaning.

For example, here's how the HTML could look for the Airbnb Experiences section:

<div class="grid grid--experiences">
    <div class="card">...</div>
    <div class="card">...</div>
    <div class="card">...</div>
    <div class="card">...</div>
    <div class="card">...</div>
</div>

<style>
.grid {
    display: grid;
    grid-column-gap: 1rem;
}

.grid--experiences {
    grid-template-columns: repeat(5, 1fr);
}

.card {}
</style>

And here's the Airbnb Plus section:

<div class="grid grid--plus">
    <div class="card">...</div>
    <div class="card">...</div>
    <div class="card">...</div>
</div>

<style>
.grid {
    display: grid;
    grid-column-gap: 1rem;
}

.grid--plus {
    grid-template-columns: repeat(3, 1fr);
}

.card {}
</style>

Using modifiers to tweak the layout, like .grid--experiences and .grid--plus allows you to use a generic wrapper that can be applied at scale across the design.

Pretty cool, eh?

But you might be thinking...

How about in the example where the wrapper isn't a repeated pattern?

Like a 1-off design that requires a wrapper to style a collection of BEM blocks?

This will require a slightly different approach...

Unique Wrappers: Notion Example

Take a look at this design from the Notion.so home page:

Again, thinking with your BEM hat on, you'll notice:

Each quarter can be considered a BEM block (e.g. .feature)
A wrapper is required to position the 4 blocks

Here's how the HTML could be structured following the BEM convention:

<div class="..."> <!-- Wrapper class goes here -->
    <div class="feature">
        <img class="feature__img" src="..." alt="...">
        <h3 class="feature__title">...</h3>
        <p class="feature__description">...</p>
    </div>
    <div class="feature">...</div>
    <div class="feature">...</div>
    <div class="feature">...</div>
</div>

<style>
    .feature {}
    .feature__img {}
    .feature__title {}
    .feature__description {}
</style>

There's an important difference between this example and the previous Airbnb example:

Looking at the design of the entire Airbnb page, it's clear that the layout of each section uses a consistent format, with slight variations (like the number of columns).

The Notion feature section, however, is contextually unique. I.e. there are no other similar sections across the website.

Therefore, instead of using a generic naming convention for the wrapper as we did for Airbnb, a different naming convention approach is required for the wrapper in the Notion example.

The naming convention best approach would be to use a wrapper specific to the blocks, like features-wrapper.

For example, here's how the HTML could look for the Notion features section:

<div class="features-wrapper">
    <div class="feature">...</div>
    <div class="feature">...</div>
    <div class="feature">...</div>
    <div class="feature">...</div>
</div>

<style>
.features-wrapper {
    display: grid;
    grid-column-gap: 1rem;
}

.feature {}
</style>

Conclusion

So the key to naming wrapper and container classes within the BEM mental model is considering the context:

Is this layout a repeated pattern that can be leveraged in many areas?

If so, use a generic class name like .grid or .container.

Or is this layout unique to a collection of blocks?

In this case, use a class name related to the blocks you're positioning. So if you need a wrapper class for a bunch of .card blocks, then cards-wrapper would work well.

What do you think?

How do you handle containers and wrappers when following the BEM methodology?

Download Free BEM Cheat Sheet

Want to start practicing BEM and looking for a no-nonsense, quick start action guide?

Download a free cheat sheet covering BEM basics so you can dive in and start practicing today.

BEM Grandchildren: How To Handle Deeply Nested Elements

Tom Ray — Tue, 21 Jan 2020 09:07:23 +0000

Understanding the basic concept of BEM (block, element, and modifier) is a fairly simple concept to grasp.

However, things can start to easily go out of control when elements start to get 3 or 4 layers nested deep within a block.

Bonus: Download a free cheat sheet that will show you how to quickly get started with BEM.

These nested elements are typically known as 'grandchild' elements (as they're nested 2 levels deep).

In this article, I'll tackle how to solve these common issues and follow BEM best practices.

Ready? Let's dive in.

Chaining Elements Together - The Typical Grandchild Mistake

Here’s how many people solve for nesting elements within elements with BEM:

<div class=“nav”>
    <ul class=“nav__menu”>
        <li class=“nav__menu__item”>
            <a class=“nav__menu__item__link”>Home</a>
        </li> 
    </ul>
</div>

Following this method of chaining elements (like this: .nav__menu__item__link) gets out of control pretty quickly.

It makes your class names difficult to read, not to mention it'll unnecessarily bloat your HTML and CSS files.

This approach also follows the structure of the DOM, which limits your flexibility if the structure of your HTML changes.

Don't just take my word for it. Vladimir Grinenko is on the Yandex team (the creators of the BEM methodology) and said this:

"BEM methodology doesn't recommend to use elements within elements in class names. You don't need to resemble DOM structure in naming. Having one level structure makes refactoring much easier."
— Vladimir Grinenko, Yandex

For example, imagine that you realised that you needed to add a <div> inside the <nav>:

<div class=“nav”>
    <div class="nav__wrapper"> <!-- Here is my new div-->
        <!-- Now I need to refactor all the classes below
        because of the new div -->
        <ul class=“nav__wrapper__menu”>
            <li class=“nav__wrapper__menu__item”>
                <a class=“nav__wrapper____menu__item__link”>Home</a>
            </li> 
        </ul>
    <div>
</div>

All the classes within the <div> would need to be updated, as well as updating the class names in your CSS file.

So as you can see, taking the Block__Element__Element__Element is not a long term, sustainable choice.

Here's how to better solve it:

The Grandchild Solution

Instead of chaining elements like nav__menu__item__link, simply focus on the block name itself and use that as the main anchor:

<div class=“nav”>
    <ul class=“nav__menu”>
        <li class=“nav__item”>
            <a class=“nav__link”>Home</a>
        </li> 
    </ul>
</div>

Taking this approach also makes your code much more readable for other developers, as they can easily see all the elements that have a relationship with the block (in this case: .nav).

And if you need to add or remove HTML elements in the future, no refactoring is required:

<div class=“nav”>
    <!-- New div added without the need to refactor -->
    <div class="nav__wrapper"> 
        <ul class=“nav__menu”>
            <li class=“nav__item”>
                <a class=“nav__link”>Home</a>
            </li> 
        </ul>
    </div>
</div>

If you find yourself entering territory where your elements are more than 3 levels deep, you might need to reconsider the structure of the block, potentially even breaking the block into smaller chunks.

And that's it!

I hope this article has helped you solve the 'Grandchild' scenario moving forward.

Download Free BEM Cheat Sheet

Want to start practicing BEM and looking for a no-nonsense, quick start action guide?

Download a free cheat sheet covering BEM basics so you can dive in and start practicing today.

BEM Methodology In CSS: A Quick Start Guide

Tom Ray — Tue, 14 Jan 2020 09:23:13 +0000

This is a quick start guide to learning BEM, the component-driven CSS methodology.

If you want to start practicing and applying BEM to your projects, this guide will help you get started.

Bonus: Download a free cheat sheet that will show you how to quickly get started with BEM.

Ready? Let's dive in:

BEM overview
B - Blocks
E - Elements
M - Modifiers

BEM Overview

BEM (Block-Element-Modifier) is a CSS naming convention developed by the team at Yandex to improve scalability and maintainability in web development.

Put simply, the idea of BEM is to "divide the user interface into independent blocks" by naming CSS classes in the following methodology:

/* Block component */
.card {}

/* Elements are dependent on their parent block */ 
.card__img {}

/* Modifiers are for incremental style changes */
.card--dark {} 
.card__img--large {}

Block: an independent component that can be reused (e.g. with class name .nav)
Element: a child within a block that cannot be used separately from that block (e.g. with class name .nav__item)
Modifier: a variation in the style of either a block or modifier (e.g. with class name .nav--dark)

Let's dive into some real CSS examples to get a hang of this thing.

Blocks

Blocks are reusable components. Like buttons, cards or form fields.

When naming your blocks, focus on describing its purpose (i.e. what it is) rather than its state (i.e. what it looks like).

For example, .btn or .nav follows the correct naming convention for a block.

.big or .bright-pink describes how it looks, so doesn't scale well when you want to change the design later on.

<!-- INCORRECT -->

<div class="large-red-box">
 <img src="...">
 <h2>...</h2>
 <p>...</p>
 <a>...</a>
</div>

<style>
 .large-red-box {}
</style>

<!-- CORRECT -->

<div class="card">
 <img src="...">
 <h2>...</h2>
 <p>...</p>
 <a>...</a>
</div>

<style>
 .card {}
</style>

If you're wondering how to place blocks within blocks (for example, a button inside a nav), here's a short article to help you with that.

Elements

Inside blocks are where elements live. Elements are dependent on their parent block, and so cannot be used without them.

Elements also have a unique CSS class naming convention which works like this:

.block__element

For example, using the .card component, an element inside the card component (like an image) would have a class name like .card__img.

The element name always appends the block name, separated by a double underscore __.

<!-- INCORRECT -->

<div class="card">
 <img src="...">
 <h2>...</h2>
 <p>...</p>
 <a>...</a>
</div>

<style>
 .card {}
 .card img {}
 .card h2 {}
 .card p {}
 .card a {}
</style>

<!-- CORRECT -->

<div class="card">
 <img class="card__img" src="...">
 <h2 class="card__title" >...</h2>
 <p class="card__description" >...</p>
 <a class="card__button">...</a>
</div>

<style>
 .card {}
 .card__img {}
 .card__title {}
 .card__description {}
</style>

It's important to note that the second code snippet avoids using more than 1 selector to target the styles (e.g. like .card img {}).

It's considered best practice to use a BEM element class and use that directly instead (like .card__img {}).

Following this approach reduces the chance of cascade issues down the line.

Modifiers

When you have varying styles in blocks (or elements), that's where modifiers come in.

For example, your 'card' block might have a light and dark version. Or you might have primary and secondary buttons.

Modifiers have a unique CSS naming convention which works like this:

block--modifier or block__element--modifier.

That's right- BEM modifiers can be applied to both blocks and elements.

Let's dive into some bad and good practices:

<!-- INCORRECT -->

<div class="card--dark">
 <img src="...">
 <h2 class="card__title--large">...</h2>
 <p>...</p>
 <a>...</a>
</div>

<style>
 .card--dark {}
 .card__title--large {}
</style>

It's considered bad practice to use a modifier class in isolation (i.e. without the block or element class).

That's because the modifier is meant to add incremental style changes to the block.

Therefore, whenever using a modifier, ensure it's used with the base class:

<!-- CORRECT -->

<div class="card card--dark">
 <img src="...">
 <h2 class="card__title card__title--large">...</h2>
 <p>...</p>
 <a>...</a>
</div>

<style>
 .card {}
 .card--dark {}
 .card__title {}
 .card__title--large {}
</style>

And that's it!

Those are the fundamentals to get you off and running with BEM.

If you're interested to learn more about the 'why' behind BEM, I recommend checking out this CSS Tricks article.

Like learning anything new, practicing is key. Give BEM a shot in your next project and see where it takes you!

Download Free BEM Cheat Sheet

Want to start practicing BEM and looking for a no-nonsense, quick start action guide?

Download a free cheat sheet covering BEM basics so you can dive in and start practicing today.

Is Sass worth learning in 2020?

Tom Ray — Tue, 31 Dec 2019 11:24:38 +0000

Sass has been around for over 10 years now. It's worth asking:

Is Sass worth learning going into 2020?

Is it still a relevant way to keep your CSS organized and write efficient stylesheets?

Let's go through some valid objections to learning Sass to answer these questions:

"Isn't CSS catching up with Sass functionality?"
"Isn't PostCSS taking over Sass?"
"I only work on small websites. Do I need Sass?"
"I've avoided Sass because of the compiler"
"I'm not sure I know enough CSS to get started with Sass"

Ready? Let's dive in.

"Isn't CSS catching up with Sass functionality?"

It's true, CSS is evolving.

In fact, some developers are opting to leave preprocessors all together and get back to writing vanilla CSS.

"CSS has evolved over recent years and the problems that lead me to Sass in the first place seem to be less of an issue today" — Cathy Dutton in her blog post on Stepping away from Sass

An example of CSS catching up with Sass is the introduction of CSS Variables.

It's quite similar to the variables functionality in Sass, and is widely adopted across browsers:

Other functionality from Sass is also planned to move across to CSS in the coming months/years.

But the reality is that right now, many developers and plenty of organizations still rely on preprocessors like Sass.

Sass functionality like nesting (when used carefully), mixins & partials still provide value to frontend developers and are not (yet) supported in vanilla CSS.

That being said, can't PostCSS help with those things?...

"Isn't PostCSS taking over Sass?"

Over the past few years, PostCSS has grown quite a bit in popularity:

Some frontend developers have adopted PostCSS as a complete replacement to Sass (or other preprocessors).

So, what is PostCSS and how does it differ to Sass?

PostCSS is a tool that gives you access to a bunch of CSS related plugins to help improve your workflow and how you write CSS.

This means you start with a blank slate, and you can pick and choose the additional plugins you need.

That's the biggest difference between Sass and PostCSS:

Sass comes with a whole bunch of functionality out of the box, even if you don't need some of that functionality. PostCSS allows you to choose which functionality you'd like to add (and they have a pretty amazing choice of independently created plugins).

For example, let's say you enjoy using the nesting functionality from Sass, but you're not bothered about the other Sass functionality.

Well, once you've got PostCSS setup, you'd simply need to add the postcss-nested plugin and you're off!

Pretty cool, right?

The data from Ashley Nolan's recent CSS tooling survey paint an interesting picture on the usage of Sass vs PostCSS:

So clearly, Sass and PostCSS are both winners here.

That being said, their usage is not mutually exclusive.

In fact, many use both Sass and PostCSS in tandem, allowing them to keep using Sass and take advantage of PostCSS plugins to improve their workflow.

The barrier to entry for getting started and using Sass is lower than PostCSS, which is one of the reasons I imagine PostCSS hasn't skyrocketed in usage over Sass.

"I only work on small websites. Do I need Sass?"

For small websites, it can be hard to rationalize using Sass.

For example, one of the features of Sass is using variables to define repeating values, like this:

// Declare the variable
$danger-red: #fc4103;

.error {
 color: $danger-red; // Use the variable
}

Sure, it's easy to see how this can save you time.

But in reality, for a sub-20 page website, updating colors on a website would only take you a couple of minutes in CSS.

I.e. Sass seems a bit overkill.

That being said, don't forget that Sass (SCSS) uses the same syntax as CSS.

Meaning that you can write CSS in a .scss (Sass) file and it will work the same as CSS (once it's compiled. See more on the compilation setup below).

So think of Sass like a bolt-on to your CSS, giving you extra functionality.

That being said, you might STILL think this is overkill for a small website.

And you might be right.

But the barrier to trying Sass is much lower than you think. And once you've tried it, then you can make a judgment call.

To try Sass, you just need to know how to set up the compiler...

"I've avoided Sass because of the compiler"

Ahh, the compiler.

If you've not used npm before or a task runner like gulp or grunt, the compiler can be a reason to shy away from getting started with Sass.

The reality is that if you want to use Sass in a professional workflow, you will need to address that fear and learn how to use package managers.

But what if I told you about a simpler way? If you wanted to just start writing some Sass and dive in?

Well, my friend, you're in for a treat. Here's what you can do (assuming you're using Visual Studio Code):

Search for 'sass' inside the extensions tab of VS code and install the Live Sass Compiler extension:

Create a .scss file and, with your .scss file open, press the 'Watch Sass' button at the bottom of your screen inside the horizontal blue bar:

The compiler is now setup! Easy as that. You should see the compiled .css file within your files:

The final step is to link the compiled CSS file. So remember to link the .css file, not the .scss file:

"I'm not sure I know enough CSS to get started with Sass"

How do you know when your foundational CSS skills are strong enough to start learning Sass?

It's an interesting question.

Because if you can write CSS, then you can write Sassy Sass (SCSS) as we mentioned above.

For example, declaring a style like this in CSS:

/* CSS (.css) file */

html {
 font-family: Helvetica, Arial;
 color: green;
 font-size: 100%;
}

Is the same as declaring the style in SCSS:

/* Sassy Sass (.scss) file */

html {
 font-family: Helvetica, Arial;
 color: green;
 font-size: 100%;
}

The difference between Sassy Sass and CSS is that Sassy Sass requires a compiler and has additional syntax and functionality, like mixins and nesting.

So the question should be:

At what point should I learn Sass functionality like mixins & nesting?

Well, have you spent some time learning (and importantly practicing) fundamental concepts CSS like:

How the cascade & specificity works
The box model
Practiced different layout methods like flexbox & grid
Practiced using different selector types, properties & values
Using media queries for responsiveness

If you've got these topics covered, I think you should be brave and dive in.

Conclusion

The reality is that Sass is still being used commercially (and recreationally) by developers and organizations around the world.

How do I know this?

Well, the State of CSS 2019 survey results speak for itself:

So, if you're pondering whether or not to start learning Sass, I would encourage you to be brave and dive in.

I know. At first glance, Sass can look fairly overwhelming and complex.

But the barrier to entry is much lower than it seems.

Give it a go!

Is Sass worth learning in 2020?

Tom Ray — Mon, 30 Dec 2019 14:33:30 +0000

What do you think? Is learning Sass still a worthy investment going into 2020?

How To Stop Writing Messy & Unscalable CSS

Tom Ray — Tue, 24 Dec 2019 10:04:31 +0000

“I have 4 .css files and in total, they’re over 10,000 lines of code. How did things get so big?”

CSS files can get out of control, pretty quickly.

But it doesn't have to be this way.

Let's dive into some actionable CSS techniques to help you write more modular & flexible code:

Technique 1: Leverage inheritance in CSS
Technique 2: The power of the elements
Technique 3: Use a CSS methodology

Technique 1: Leverage inheritance in CSS

Do you ever find yourself in CSS repeating a declaration, even though you know that you've used that declaration before?

Understanding inheritance in CSS might help.

Inheritance in CSS allows us to define styles at a high level so that these styles can be trickled downstream and style descendant elements.

This is simple, entry-level CSS skills.

However, despite its well-understood nature, I believe the inheritance rule is often being underutilised.

When leveraged correctly, it can save you hundreds of lines of code in the long run.

Starting at the highest level, for the majority of websites, there will be styles that will be consistent across all of your HTML elements:

html {
 background-color: #fafafa; 
 color: #424242;
 font-family: 'Helvetica';
 font-size: 100%;
 font-weight: 300;
 line-height: 1.5;
 box-sizing: border-box;
}

Don't forget about `inherit`

Adding styles to the root as shown above is a great place to start.

There are, however, some HTML elements (like <input> or <textarea>) that by default will not inherit styles that you've defined.

This means if you set the font-family: Helvetica in the root as shown in the example above, the font in the <input> will not inherit this style, they will take the browser default font family.

You can override this by adding the following declaration: font-family: inherit to these elements that do not inherit properties by default.

A common technique to ensure all elements inherit the styles you've defined on the root element is to use the universal selector * {} and apply the inherit value to specific properties:

* { 
 font-family: inherit;
 line-height: inherit;
 color: inherit;
 box-sizing: inherit;
}

Important to note: Properties like font-size and font-style are not included in the universal selector snippet above, as applying these syles will override the user-agent styles.

For example, if you styled font-size: 20px within the universal selector, this will override the user-agent font-size for all the heading tags (h1, h2, h3...)

Putting it all together, here's an example of of some common declarations used to leverage the inheritance rule and save you some lines of CSS:

html {
 background-color: #fafafa; 
 color: #424242;
 font-family: Georgia, serif;
 font-size: 100%;
 font-weight: 300;
 line-height: 1.5;
}

* { 
 font-family: inherit;
 line-height: inherit;
 color: inherit;
}

Now, let's dive a little deeper and discuss styling elements.

Technique 2: The power of the elements

Getting more granular than styling the root, adding styles directly to element selectors is a great way to keep your CSS file lean and efficient.

For example, a content-heavy website like a blog, you can style the typographic selectors like this:

p {
 /* paragraph styles are not required 
 as they are inherited from the root */
}

h1, h2, h3, h4, h5, h6 {
 font-family: Helvetica, sans-serif;
 font-weight: 700;
 line-height: 1.3;
}

h1 {
 font-size: 2rem;
 max-width: 32rem;
}

h2 {
 font-size: 1.75rem;
 max-width: 24rem;
}

h3 {
 font-size: 1.5rem;
 max-width: 20rem;
}

h4 {
 font-size: 1.25rem;
 max-width: 16rem;
}

This has 2 benefits:

Your HTML will be much cleaner, as the styles are applied natively to the HTML element selectors (i.e. no need to add classes to your HTML tags)
In some cases, it can remove the need to add custom classes, simplifying your CSS stylesheet and making it more scalable

I like to view this as setting up the core foundation of the styling in a project to give yourself a good base to begin styling components and building out more complex parts of your website.

Technique 3: Use a CSS methodology

Leveraging CSS inheritance rules and styling element selectors will only get you so far.

Using classes to design various components and layouts on your website is inevitable (and where you'll spend most of your time).

Therefore, what we need is a "system" to write CSS in a modular, flexible way to keep our CSS efficient and organised.

That's where a CSS methodology comes in.

A CSS methodology is a consistent set of naming conventions that a team of developers will follow to ensure they write consistent, reusable CSS that is scalable over time.

Some of the most popular methodologies include BEM, SMACSS, OOCSS and Atomic CSS.

Out of these, it appears BEM has taken the pole position as the most adopted of the methodologies as noted from the State of CSS 2019.

So, let's zero in on BEM: what it is and how you can start to implement it in your projects.

BEM stands for Block-Element-Modifier, which are the 3 core pillars.

Each pillar has a different naming convention to use when creating components:

Block is the component itself, for example, a card component (e.g. .card)
Element is a child that lives within the Block and uses the naming convention [Block]__[Element] (e.g. .card__title)
Modifier is a variation in the design of a Block or Element and uses the naming convention [Block]--[Modifier](e.g. .card--dark)

Let's dive into a real example, sticking with a card component:

In this example, the .card is the Block.

You can see the children elements within the .card Block uses the naming convention [Block]__[Element].

For example, the class used for the image of the card is .card__image

Now, let's dive into an example with 'Modifier':

You can see the naming convention [Block]--[Modifier] is being used for the Modifier (.card--dark).

It's important to note here that when you used a Modifier, you use it with the Block (not instead of the Block).

You can see in the CodePen above that the Modifier class .card--dark does not replace the Block class .card.

For more code examples and a deeper dive into BEM, I recommend checking out Sparkbox's article.

Summary

Perhaps you've been authoring CSS stylesheets for a long time but often look back and say: "Damn. My CSS is an absolute mess!"

If implemented, the techniques covered in this article will help remedy that feeling and you will be well on your way to becoming a modular & scalable CSS master.

To summarise up, here are the 3 CSS techniques you can start using today:

Understand how inheritance works in CSS and use it to your advantage
Style element selectors directly to give your design a solid foundation
Use a CSS Methodology like BEM to design your components in a modular and flexible way.

What do you think? Any tips/strategies to write less messy CSS?

DEV Community: Tom Ray

How to build a NestJS Docker image for production

Writing the Dockerfile

Test the container locally

Optimize Dockerfile for production

Use Alpine node images

Use multistage builds

Troubleshooting

Error: Cannot find module 'webpack'

Conclusion

How to setup & deploy an Express GraphQL server

Contents

Prerequisites

Creating the project

Configuring TypeScript

Hot reloading and scripts

Setting up the server with Apollo

Deploy to Heroku

Set up Postgres locally with Docker

Build your database schema with Prisma

Connect database to Graphql API

Fetch a list of boards

Adding Postgres to Heroku

Styled Components: A Quick Start Guide

Contents:

Styled Components Overview

Installing styled-components

Building your first styled component

Using props to customize Styled Components

Using media-queries to make your styled-components responsive

Handling hover states and other pseudo-selectors with Styled Components

Creating global styles

Conclusion

Download Free Styled Components Cheat Sheet

How to Create Global Styles with Styled Components

Step 1: Create a global styles file

Step 2: Place GlobalStyle at the top of your React tree

Download The Free Styled Components Cheat Sheet

Quick Start Guide to Attrs in Styled Components

Use Case 1: Defining Default Attributes

Use Case 2: Defining Dynamic Props

Summary

Download The Free Styled Components Cheat Sheet

Launching BEM Basics: A Free Email Course on BEM

How To Name Containers And Wrappers In BEM

Repeated Wrappers: Airbnb Example

Unique Wrappers: Notion Example

Conclusion

Download Free BEM Cheat Sheet

BEM Grandchildren: How To Handle Deeply Nested Elements

Chaining Elements Together - The Typical Grandchild Mistake

The Grandchild Solution

Download Free BEM Cheat Sheet

BEM Methodology In CSS: A Quick Start Guide

BEM Overview

Blocks

Elements

Modifiers

Download Free BEM Cheat Sheet

Is Sass worth learning in 2020?

"Isn't CSS catching up with Sass functionality?"

"Isn't PostCSS taking over Sass?"

"I only work on small websites. Do I need Sass?"

"I've avoided Sass because of the compiler"

"I'm not sure I know enough CSS to get started with Sass"

Conclusion

Is Sass worth learning in 2020?

How To Stop Writing Messy & Unscalable CSS

Technique 1: Leverage inheritance in CSS

Don't forget about inherit

Technique 2: The power of the elements

Technique 3: Use a CSS methodology

Summary

Don't forget about `inherit`