DEV Community: Techhive.IO

How to Close a Software Project: The Pillars for Successful Project Delivery

Abdul Rahman Zantout — Sat, 12 Oct 2019 08:41:45 +0000

Software engineering is hard.

No matter what you hear or read, learning how to develop software might be easy at first. But developing an application or a product takes much more than writing code.

You need to communicate with the client, get the requirements straight, iterate, improve, and deliver.

You need to understand what the client needs. You will also need to question your assumptions and to make sure you address the real needs.

As with any engineering field, crafting proper software requires careful planning, careful execution, smart decision making, and feature prioritization.

You need the right combination of skills within your team. But most importantly, your team must have the correct mindset and common drive to bring an idea or a product to life.

A software engineer will face challenges and will be tasked to complete the project during the timeline agreed upon with the client, with high-quality standards by the release date.

To do so, a software engineer must carefully incorporate a particular methodology to navigate the waves ahead of him successfully.

Managing Expectations

Both you and your client should know the outcome and the purpose of the project beforehand.

What does the client need? What does he or she expect to receive?

Expectation management is when every detail of the project (the scope of work) is clear, precise, and concise for both you and the client.

When you define your scope of work, you set the expectations for both your team and the client. You must make sure that every detail related to project requirements is clear and precise.

Requirements do not change in the middle of the project unless the nature of the project allows it to, which you should be aware of beforehand.

Getting the requirements straight

You're in the middle of the project, and the client decides to redesign part of the website or application.

Depending on the size and complexity of the request, you could charge your client for the extended scope.

Whether you do charge them or not, make sure they show you an example of what they expect and what they have in mind. A visualization of what to expect helps your clients express their needs in as clear a manner as possible.

Designing, and God forbid, implementing the redesign without the client's input beforehand is a waste of resources.

Continuous Delivery

Progress bars are created to show you your progress, or the progress of something that you are waiting for its completion (think downloading)

The same applies to your client.

Showing progress to your client through continuous delivery and keeping him posted regularly about the status of the project will not only keep the client engaged throughout the project: it will also allow him to provide you feedback, iterate quickly over the features, improve on them, and test them.

Locking down the project's scope

The project's scope should be locked down and agreed upon beforehand, with minor room for change.

Leaving a small room for change might sound counter-intuitive to some clients and developers alike. But this is the surest way to deliver a successful project on the initial time and budget.

If there is a hard deadline, significant change requests can be left to a second iteration. If they were important, you should have included them in the first iteration.

Proper communication at the beginning of the project will eliminate ambiguity and surprises along the way.

Getting the requirements straight before jumping into development and design is the foremost step before kicking off any project. Identifying key stakeholders, doing a risk analysis, and planning your sprints comes second.

Final Words

Successfully delivering to a client is the surest way to grow your business and reputation. The client will recommend you to other prospects.

Successful projects will breed other projects and prospects.

Anyone can write code, regardless of seniority. But allowing the client to experience the entire software development lifecycle, and delivering smoothly and successfully is the surest way to more successes down the road.

Making your blog smarter - How to implement suggestions

Abdul Rahman Zantout — Tue, 08 Oct 2019 16:22:15 +0000

One of the most effective methods for promoting your business is content creation.

You can choose between various methods and mediums through which to publish your insights.

More often than not, you'll want to choose something simple that can get you going immediately, such as Medium.

However, there's one advantage to building the blog yourself, and that is it allows you to customize the user experience.

One of the critical elements that can define your readers' experience is how they discover your content.

To do that, you must be able to suggest relevant content for your readers.
You want your readers to be fully engaged and benefit to the maximum from what you are offering.

In our previous blog post, we have explored how we can build a powerful blog with NextJs and Contentful, as well as how to integrate Google analytics and to enhance your meta tags.

In this piece, we explore how we can drive the blog forward by maximizing the value and knowledge ingested by our readers. We also do not want our readers to drop-off after reading one insight or article only.

This is why, in addition to creating great content, we enhance the user experience. To do so, we make suggestions at the end of every blog post to keep the user engaged.

User Experience

When reading a blog post, the reader is usually researching information that would enrich his know-how and his knowledge.

The user also, more often than that, is interested in knowing more about the topic he is researching and is directly related in content and essence to the article he is currently reading.

So the logical and straightforward way to suggest related content is by filtering our blog posts by tags and then displaying them.

Prerequisite

In this post, we are not walking through the basics of building the blog. This post will, however, expand on the logic that we have already implemented in our previous article.

So if you didn't go through our previous blog post, you should do so before moving to this one.

Let's get started!

The blog we've built utilizes the power of tags fully. We have already labelled every blog post with a set of tags that we define in our headless CMS.

If you haven't already, I highly encourage you to do so before resuming this article.

Fetching the Suggestions

To fetch the suggestions, let's modify our contentful.ts file to include our newest function:

For our use case, we want to fetch three suggestions per post and display them at the end of the article.

Contentful provides us with many efficient ways to query our posts; in our case, by tags.

As an important note, you want to make sure to exclude from your suggestions the current post you are reading.

In theory

Let's explore how our algorithm works:

1- User is reading blog post 1
2- We defined an empty suggestions set
3- Fetch blog post 1 tags on load
4- Find 3 blog posts with at least one matching tag
5- Append your result to the suggestions set
6- If you found less than 3 blog posts
7- Then, fetch (3 - result.length) random blog posts
8- Append to suggestions set
9- Return suggestions

Step number 7 is essential, as we do not want more than 3 suggestions per post.

In implementation

To fetch each post's suggestions:

Many things are happening above.

Remember that in our previous article, we've already included filtering by tags.

Our current goal is to find at least one matching tag across all our articles and display those.

'fields.tags.sys.id[in]': tags.length ? tags.join(',') : undefined

The [in] allows us to do so, but since Contentful allows us to query by reference in our case, we need to include the ids of the tags that Contentful generates. Those can be found until the fields.tags.sys field.

What happens if we have less than 3 posts to display in the suggestions?

In other words, if the blog post is not related to any other subject you have previously published, or you do not have enough content to display, then it is initially safe to suggest a random set of posts that the user could browse.

In this case, we query our entire posts collection randomly and append them to the original array.

Let's start off by excluding the current article (the one we want to fetch the suggestions for), from being fetched again:

'fields.slug[ne]': currentArticleSlug, // exclude current article

You also want to exclude fetching suggestions that you already fetched by tag.

'fields.slug[nin]': slugsToExclude, // exclude slugs already fetched

Finally, we append the random posts with the posts that we fetched by suggestions:

entries = [...entries, ...randomSuggestions.items];

Bonus

We include a helper function to map the data to fit out BlogPost interface

/**
 * Maps the items fetched by contentful
 * @param entries
 */
private mapData(entries): BlogPost[] {
    return entries.map(({sys, fields}: { sys: any; fields: any }) => ({
        id: sys.id,
        title: fields.title,
        description: fields.description,
        heroImage: fields.heroImage.fields.file.url,
        slug: fields.slug,
        tags: fields.tags,
        publishedAt: fields.publishDate
            ? new Date(fields.publishDate)
            : new Date(sys.createdAt),
    }));
}

Displaying the suggestions

Let's modify our pages/post/index.tsx to fetch and display the suggestions.

Let's start first by fetching the data before the view is initialized, i.e: getInitialProps:

PostPage.getInitialProps = async ({ query }) => {
  const contentfulService = new ContentfulService();

  const { post } = query;
  const article = await contentfulService.getPostBySlug(post);
  // map the tags that we have fetched from Contentful
  const tags = article.tags ? article.tags.map(tag => tag.sys.id) : [];
  // pass the tags to the function we have built
  const suggestedArticles = await contentfulService.fetchSuggestions(
    tags,
    article.slug
  );

  return { article, suggestedArticles };
};

Now that the component is receiving the suggestions, we can now display them:

// helper function to display the cards
const renderCards = suggestions =>
  suggestions.map((suggestion, index) => (
    <Card key={index} info={suggestion} />
  ));
const PostPage: NextPage = (props: Props) => {
...
   return (
...
<div className="suggestions">{renderCards(props.suggestedArticles)}</div>
...
   );
};

The final step is to fix how the cards are displayed. Under pages/post/styles.css, add the following:

...
.suggestions {
  display: flex;
  flex-flow: row;
  padding: 1.5rem 0;
  margin: 1rem auto 1rem 4rem;
  justify-content: flex-start;
}

.suggestions .card {
  margin: 0 1rem;
  height: 450px;
  width: 320px;
}

.suggestions .card:first-of-type {
  margin-left: 0;
}

Final words

Congratulations! You have successfully integrated suggestions into your NextJs Blog and powered by Contentful while utilizing the power of static websites!

Ready-made Starter Kit

To make things easier for you, we have created a starter kit that includes a template and can get you bootstrapped in no time. We even created a script to create your Contentful Content Data automatically and includes everything you have learned so far in building a great Blog.

Feel free to submit your PRs, issues and don't forget to star our repo ⭐.

How to use CSS variables with Sass Mixins

Ali Al-Obaji — Fri, 27 Sep 2019 07:55:54 +0000

CSS Variables and Sass mixins are each potent on their own. With some creativity, we can make them work together towards more flexible and robust solutions.

On several occasions, the designer I've worked with had used the same colour but with varying opacity. Many of his components were using varying shades of different colours.

The typical and tedious implementation involves declaring all colour variants as separate variables. We would usually end up with something similar to this:

/* Color palette */
:root {
  --color-primary: #16498a;
  --color-primary-a90: rgba(22, 73, 138, 0.9);
  --color-primary-a80: rgba(22, 73, 138, 0.8);
  --color-primary-a70: rgba(22, 73, 138, 0.7);
  --color-primary-a60: rgba(22, 73, 138, 0.6);
  --color-primary-a50: rgba(22, 73, 138, 0.5);
  --color-primary-a40: rgba(22, 73, 138, 0.4);
  --color-primary-a30: rgba(22, 73, 138, 0.3);
  --color-primary-a20: rgba(22, 73, 138, 0.2);
  --color-primary-a10: rgba(22, 73, 138, 0.1);

  --color-secondary: #12284c;
  --color-secondary-a90: rgba(18, 40, 76, 0.9);

  --color-tertiary: #27add5;
  --color-black: #000;
  --color-gray: #ececec;
  --color-light-gray: #f9f9f9;
  --color-danger: #d63939;
  --color-success: #4fc0b0;
  --color-white: #fff;
}

Note that I prefer to use CSS Variables instead of standard SASS variables for their dynamic nature. Additionally, they help me write clean, readable, and modular code without having to import sass colour maps every time I want to reference a variable.

Our typical style guide comes with around 9 different colours and their variants. Our previous approach had several apparent issues. It produced large CSS files and made any slight change to our primary or secondary colours a considerable pain.

So how can we solve these problems?

The optimal solution would allow us to:

Maintain a single source of truth for my colour definitions. Which, in my case, means that I should only have 9 variables for colours.
Use any opacity variant of any of the brand colours without adding complexity.
Apply changes to any brand colour by editing just one line of code.
Fully utilize the power of dynamic CSS Variables.

Sass’s rgba mixin

First, I tried using the sass built-in 'RGBA' mixin. It seemed like a pretty straightforward solution.


border-top: rgba(#16498a, .4); // works.

border-top: rgba(22, 73, 138, 0.4); // works.

border-top: rgba(var(--color-primary), 0.4); // does not work.

Sass's RGBA function accepts 4 comma-separated parameters. However, it accepts two parameters if we wish to use hex values. Under the hood, Sass uses RGB/HSL functions to convert the hex colour value into RGB or HSL. Here is, in CSS, what the three examples above compile to:


// border-top: rgba(#16498a, .4); compiles to:
border-top: rgba(22, 73, 138, 0.4);

//border-top: (22, 73, 138, 0.4); compiles to:
border-top: (22, 73, 138, 0.4);

//border-top: rgba(var(--color-primary), 0.4); compiles to: 
border-top: rgba(var(--color-primary), 0.4);

The example which used a CSS variable failed. Using SASS's rgba function with CSS variables fails to be rendered correctly.

According to the official CSS spec, "the values of custom properties are substituted as is when replacing var() references in a property's value".

However, these values are only interpreted at execution time. Which means that when SASS was being compiled to CSS, var(--color-primary) was not interpreted as a colour value. Instead, the compiler saw a random string and SASS's rgba function failed to be correctly compiled.

Moreover, this string can be anything as long as it is grammatically correct.


// For example, this is valid.
--foo: if(x > 5) this.width = 10; 
// This code is obviously useless as a CSS variable. But can be used by javascript at run time.

So at compilation time, var(-- color-primary) is not a colour value at all; and it naturally fails to compile. However, lucky for me, it fails gracefully into the native rgba function.


/* Sass will fail to compile this line of code. But it fails gracefully and outputs the exact same line of code.
Now, when the browser interprets this code, it will try to use the native rgba function.
*/
Border-top: rgba(var(--color-primary), 0.4);

The native rgba function

According to the spec, the native rgba function only accepts 4 comma-separated values as parameters, which means that we cannot use hex colour values. Maybe we could try to declare our variables as comma-separated RGB values from the get-go.


:root {
  --color-primary: 22, 73, 138;
}

div {
  border-top: 1px solid rgba(var(--color-primary), 0.4) ;
}

This new method worked! We can now use opacity variants of any colour very quickly.

However, with this method, two new problems arose:

A value such as '22, 73, 138' is not very readable: this method would require us to convert all my colour values into this format.
We can no longer edit these values in a colour picker to test them out. Neither my IDE nor chrome dev tools can recognize these values as colours.

This method is time-consuming and is not expressive at all. However, we are getting closer to a cleaner solution

The solution

We want to be able to use CSS variables and not have to declare 10 opacity variants for each colour. It seems I have to use comma-separated RGB values, but I also need my code to be expressive and easy to edit.

:root {
  --color-primary: #16498a;
  --color-primary-rgb: 22, 73, 138;
}

h1 {
  color: var(--color-primary);
}

h2 {
  color: rgba(var(--color-primary-rgb), 0.4);
}

By declaring two versions of the same colour, one HEX and one RGB, we compromised on simplicity to make our solution work This approach increases the number of variables I initially aimed for, but it's a pretty good compromise.

So, we’ve managed to use CSS variables to create different shades of our colours. However, there is still some room for improvement. With this solution have two issues:

We still need to convert all our colours from hex to RGB format manually.

We have to edit multiple variable whenever we need to make a change to any of our colours.

Here is a function which converts hex colour values to RGB. The function extracts the red, green, and blue levels from any colour and returns them in a comma-separated format.

@function hexToRGB($hex) {
  @return red($hex), green($hex), blue($hex);
}
:root {
    --color-primary: #16498a;
    --color-primary-rgb: #{hexToRGB(#16498a)};
}

With this function, we will no longer need to do the colour conversions manually.

The solution is now very close to what we set out to achieve. We still want to create a single source of truth for each of my variables.


@function hexToRGB($hex) {
  @return red($hex), green($hex), blue($hex);
}

$color-primary: #16498a;

:root {
    --color-primary: #{$color-primary};
    --color-primary--rgb: #{hexToRGB($color-primary)};
}

Sass functions, mixins, variables, and native CSS variables are all powerful features. However, none of them provides a complete solution on its own. They need to work together to create robust solutions.

I initially set out to solve the problem of using CSS variables, or custom properties, in sass functions and mixins. With some compromise and much testing, I was able to create a satisfactory solution, which I hope you find useful.

Bonus

To further understand this concept and see an example of how it can be applied, I created this sample project on Stackblitz.

https://stackblitz.com/edit/react-jyogzp?file=index.js

I built a heatmap to show how a project's repo is progressing. Every box represents a calendar day, and its colour shows whether the codebase grew or shrunk in size.

The darker a blue tile is, the more code was added to the repo on that day.
Similarly, the darker a red tile is, the more code was removed from the repo on that day.

Gray tiles represent days when no work was done.

How to build a powerful blog with NextJS and Contentful

Abdul Rahman Zantout — Tue, 24 Sep 2019 11:05:52 +0000

Building a blog that scales can be quite easy if you know where to start.
In this article, we show you how you can build, in a few steps a robust blog, powered by our CMS of choice: Contentful.

However, if you prefer another CMS, with a couple of short steps, you could integrate with your favourite headless CMS.

We also explore how to add Google Analytics and generate sitemaps automatically.

So grab a cup of coffee, and let's get started!

To build our new blog, we chose a few tools that may or may not be familiar to you:

Next.JS (V9+) as our main framework,
React Markdown to parse and display the blog post's content,
Contentful as our Headless CMS,
Netlify for cloud hosting and deployment

User Experience

To build a blog that appeals to your users, we need to define the user experience.

We define our requirements first. The blog has the following primary purposes:

A user can see all the blog posts,
A user can navigate a large number of blog posts using pagination,
A user can filter by a topic that he is interested in,
A user should be able to read a blog post

Navigation on your blog should be user-friendly. First-time readers can scan the topics and tags at a glance. Once they find a blog post that they are willing to read, they can directly navigate to it.

Users should also have the ability to filter by relevant topics.

You can add other requirements, but this should get you started in thinking about the design.

Prerequisite

Make sure you have the latest stable node version and npm or yarn installed.

For this article, we use npm to install the packages. However, feel free to use yarn or any other packaging manager you are comfortable with.

Laying the foundation

Setting up Next.Js

Getting started is easy. Enter one of the following commands to create your application:

npx create-next-app

npm install -g create-next-app
create-next-app my-next-blog && cd my-next-blog

Follow the instructions in your terminal, and you should be good to go.

Integrating Typescript

The latest version of Next.Js has Typescript directly baked in.

To enable it, we first install the relevant packages. Navigate to your project, and run:

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

If you haven't already, rename the files within pages from index.js to index.tsx and then run the application:

npm run dev

Next.Js automatically creates a tsconfig.json and sets up your project into Typescript. If you have a components folder, you can delete the folder for now.

We also want to include the CSS plugin for styling purposes.

npm install --save @zeit/next-css

Create a next.config.js at the root of your project, including the following:

Application Architecture

Building a robust blog application requires us to think more about our application's architecture.

In the previous sections, we defined the user experience and formed a rough idea of what the blog will be.

We should now think about implementation and architecture.

Next.Js already has a particular default setup when it comes to structuring your pages. All pages to be rendered exist under the pages folder.

We also consider SEO, data integration, and routing.

Let's define our folder structure in the following manner:

- core // contains everything related to fetching the data from our CMS, Google Analytics logic, and any data sharing service/logic, and is shared across the entire application
- shared // contains common components, helper functions
- public // static folder where we can store assets to be directly compiled by Next, this is mainly used to inject the robot.txt file
- assets // contain website specific assets such as images
- interfaces// contain different models
- pages // contains the pages

Setting up Contentful

Contentful is a powerful headless CMS that is easy to use and integrate.

While you can set up the content models needed using their dashboard, we will opt to build a script that does this process for us.

Install the needed packages

Make sure you install the contentful-cli and contentful-migration before moving to the next step:

npm install contentful-cli contentful-migration --save-dev

Building your Content Models

Content models allow us to better structure our entries (whether it is a blog, author or tag) by allowing us to specify the structure of the entries. Think of it as an interface for your different entries.

Create a folder called utils in your project folder and paste the following:

To run the script, add the following to your scripts in package.json:

"scripts": {
...
"populate:contentful": "contentful space migration --space-id <YOUR_SPACE_KEY> utils/contentful.js --yes"
}

Navigate to your Contentful dashboard to find your space key and token.

Replace YOUR_SPACE_KEY with your actual space key, and then run the command:

npm run populate:contentful

The above command should populate your CMS will all the content models we need, without you having to enter them manually.

Feel free to navigate through your contentful dashboard and add a few posts; it will come in handy as we move on.

Finally, we need a way to access our space key and token without hardcoding their values.

To do so, create a .env file, add your space key and token.

CONTENTFUL_SPACE=<your space key>
CONTENTFUL_TOKEN=<your token>

We need to do is allow our Next.Js application to read our .env file. To do so, modify your next.config.js file to the following:

Make sure you install dotenv-webpack by running:

npm install dotenv-webpack --save

Great! Now you can safely access your env variables using process.env.VARIABLE.

Next, make sure you install contentful by running:

npm install contentful

We are now ready to start building our new application!

Data Models

Let's define our first two models.

Within the interfaces folder, create two files:

author.ts

// interfaces/author.ts
export type Author = {
  name: string;
  title: string;
  company: string;
  shortBio: string;
  email: string;
  twitter?: string;
};

blog-post.ts

// interfaces/blog-post.ts
export type BlogPost = {
 title: string;
 slug: string;
 heroImage: any;
 description: string;
 body: any;
 author: Author;
 publishDate: Date;
};

Notice that in both cases, we are mapping the same data models we created in the Contentful CMS.

Integrating Contentful API

Under your core folder, create contentful.ts containing the following:

What we've done here is creating a ContentfulService that connects to Contentful API, built the appropriate handlers to fetch the data and map it, so it is ready to be consumed.

Implementing the shared components

To make our blog appealing, we need to implement and design a couple of elements that distinguish it from the rest.

Let's organize every component of our application its folder. For example, the card component and style sheet will be available under the card folder.

- shared
  - components
    - card
      - index.tsx
      - styles.css
    - meta
      - index.tsx
      - styles.css
...

I prefer this approach because it allows us to modularize our application into a more precise structure further.

Moreover, it gives us more flexibility in the future when we want to split a more significant component into a small, more compact one.

Meta Tags

Let's start with our most important component, the meta tag component.

The meta tag component includes a Next.Js Head, which is a built-in component that allows you to update the <head> of your HTML page.

Let's first define the tags we want to include in our blog.

We want to utilize the Open Graph tags (for facebook sharing), as well as the twitter tags, the description of the page and most importantly, the title. Including the page type is also important: we want to differentiate between a page and a blog post.

We also want to define whether the search engines should index the page or not.

All of the tags can be dynamic, depending on the page you are it. Having dynamic tags that change according to the page the user is on is excellent for SEO purposes.

Let's define our Tag model. Under the interfaces folder, create a tag.ts containing the following:

Notice I also added two enums: the PageType and RobotsContent.

This approach will allow us to easily add the page type and the robots tag into our meta tags while minimizing duplication and human error.

Under the shared/components folder, create the index.tsx file and include the following:

To avoid duplicate tags in your <head>, you can use the key property, which guarantees that the tag is rendered only once.

Layout

The layout component serves as a container across all pages of the application.

Card

The card in our case displays the hero image of the blog, the title, description and the call to action. The call to action redirects the user to the blog post.

First, let's add some functions that help us to pass the dynamic URLs automatically.

Under the core folder, create a folder called helper, and include a helper.ts file:

Next, under the shared/components folder, create a card folder and an index.tsx:

As a bonus, let's give it some extra style:

Don't forget to import the styles within your card's index.tsx file.

import './styles.css'

Paginator

The paginator component helps the user to navigate across a large number of blog posts.

The paginator has a state that we need to maintain. We need to be able to tell the user on which page he or she is on, as well as display the page they are on in a visually pleasing way.

The paginator contains a two-way data binding: the user can navigate across pages, and if directly accessed the page through the URL, the paginator should display which page we are on.

Let's style it. Create a file called styles.css under the paginator folder:

Our code structure so far

- core
  - contentful
- pages
  - index.tsx
- interfaces
  - author.ts
  - blog.ts
  - tag.ts
- shared
  - components
     - card
       - index.tsx
       - styles.css
     - layout
       - index.tsx
     - meta
       - index.tsx
     - paginator
       - index.tsx
       - styles.css
   - helpers
     - helper.ts

Integrating the blog

The main page of the blog will include the cards, pagination, and filer components. There are a few things we need to load at the homepage.

We need to fetch all the tags, the total number of posts, skip number (for pagination purposes), the limit (number of posts to fetch per page), the page number, and the actual posts on that page.

All this can be done using the Contentful API we just created.

Under pages/index.tsx, let's update our index page:

Integrating the blog post

Under the pages folder, create a folder post , and two files: index.tsx and styles.css.

Let's add the appropriate functions to render the blog post under post/index.tsx:

Also, the styles:

Adding the meta tags

Integrating the meta tags deserve a section on their own.

Remember that we want the meta tags to be dynamic across different posts, but set to a default mode on the main page.

Our meta-tag component is flexible enough to handle all the meta-tags we throw in it.

There's one tag in particular that we need to take extra care for, the robots tag.

The robots tag helps Search Engines to "know" if a particular page should be indexed or not.

To include multiple values in robots tag, let's build a helper function concatenateStrings that concatenates them in a way that is easy for Search Engines Crawlers to parse.

/*
 * turns an array of strings into a single string separated by a           
 * comma
export function concatenateStrings(...args: string[]) {
  return args.join(',');
}

Default Tags

Next, let's include the default meta tags in a constants.ts file core folder:

We can include here any tags we need, export them and consume them on the right page.

Let's update our Layout component to accommodate for the new tags.

And include the tags input under pages/index.tsx:

import {defaultMetaTags} from '../core/constants';
...
<Layout meta={defaultMetaTags}> // <-- added
...
</Layout>
...

Post Specific Tags

The meta tags on the post are set dynamically.

In order to do so, navigate to your pages/post/index.tsx and add the following to your ComponentFunction:

const postMetaTags: MetaTags = {
    // you can set this dynamically later with proces.env
    canonical: `<your domain name>`, 
    description: `${props.article.description}`,
    image: `https:${props.article.heroImage.url}`,
    robots: `${RobotsContent.follow},${RobotsContent.index}`,
    title: `${props.article.title}`,
    type: PageType.article,
};

...
<Layout metaTags={postMetaTags}> // <- add this
...
</Layout>
...

Don't forget to include the right imports.

Integrating Google Analytics

We want to integrate Google Analytics to gather some useful data from our blog.

For convenience, we want to track only in a production environment.

Within the core folder, create a gtag.ts file that includes the following:

The above functions allow us to communicate with Google Analytics and use it to track different user interactions with our blog.

First, let's inject the Google Analytics tag on every page of the application. To do so, create a document.tsx file in the pages folder containing the following:

Here, we've injected the google-analytics tag in the head of every page, and override the default Document Component of Next.Js.

Create an __app.tsx_ in the pages folder. We need to override the default App component provided by Next.Js.

By listening to the router events, we can record them in Google Analytics so we can analyze them in the future.

Automatically generating a sitemap

Every website and blog needs a sitemap to help optimize their SEOs.

What we need is an automatic post-export process that generates the sitemap and injects it into the production build.

We need to detect every new blog post that we publish and update the sitemap.

Let's update our next.config.js to include the right paths to export:

Under the utils folder, add the following script:

Add another file post-export.js that imports the functionality from sitemap.js and use it in the post-build.

Add DOMAIN_NAME=<your domain name> to your.env file.

The script automatically reads all the posts fetched by Next.Js, build the sitemap, and injects it into the build folder (the out folder in our case).

The last step is to run the script after every build and export automatically.

Let us add the following command to package.json:

"postexport": "node utils/post-export.js"

We are ready to set up the website deployment.

Deploying to Netlify

Deploying a Next.Js project is very easy. You can deploy the project to Now, Netlify or any provider that you prefer.

However, for our case, we will deploy the blog to Netlify.

Go to your Netlify dashboard, create a site and connect it to your Github repo (or upload the code using their upload form).

Set the deployment command to:

npm run export

Set the directory to "out".

Also, make sure you connect your Contentful account to Netlify and choose your space. Netlify takes care of the rest. This approach has many advantages, mainly because we are building a static website, so every change in the CMS needs to be reflected on the website. You also do not need to set your environment variables.

You are done!

Final words

Congratulations! You have successfully created a neat blog, with markdown support, integrated Continous Integration and Continous Delivery, and you are ready to launch it to the world!

Ready-made Starter Kit

To make things easier for you, we have created a starter kit that includes a template and can get you bootstrapped in no time. We even created a script to create your Contentful Content Data automatically. Feel free to submit your PRs, issues and don't forget to star our repo.

How to Finish What They Started?

Abdul Rahman Zantout — Tue, 27 Aug 2019 06:33:41 +0000

So you're a new hire at your new company, you feel excited, and you want to jump right in.

Your manager briefed you about the project you're about to handle, wished you good luck, and went their way.

You sit down behind your computer. You launch your editor only to be perplexed by the complexity of the project.

You find monoliths, unstructured code and no documentation.

To make things worse, you have a strict deadline to make quick progress and complete the rest of the requirements.

You sit down for hours. You wrap your head around how the original author thought and coded.

You try to implement a simple feature, but another break.

You feel overwhelmed, your manager is understanding, tries to support you in the best way they can, but there's not much else they can do to help you.

The deadline is approaching.

What do you do?

Draw a high-level diagram of how the software currently is.

It shouldn't matter if it's a UML diagram or a simple graph.

Visualizing the software you are working on should take you a few hours to complete, but will save you much more time when making decisions in the future.

Checking the design and the folder structures might give you a head-start (folder structure is not always a good indicator, however).

Visualizing what you're working on forces you to think hard about how everything fits together, and most importantly, how everything should fit together.

Try to figure out where do the new features fit in.

Try to add the new features in your new diagram. Worry about improving it later. This is critical, especially if you're on a strict deadline.

Properly segment the parts of the applications you're working on in a clear and concise matter. You can, for example, segment by modules or by business features.

You are most probably dealing with a lot of legacy code: don't let that scare you. You should only care about the I/O of a function, class or module for now. Refactor later.

Document.

Think of it as your log.

Your predecessors probably did not document their code. Start by documenting the parts you are working on.

Keep your notes brief and straight to the point.

That way, you engage your mind and realize how everything connects.

Remember, you are doing this for future you too. So make sure you don't write anything that needs some forethought to figure out later.

First impressions last.

The days go by, and you still need time to work on some core functionalities, but you also need to demo your progress.

Start with the smallest features that make a significant impact.

You would be surprised how fixing a layout, a dropdown, or even a button can have a positive impact on your client's expectation.

Remember that you are likely building a product that non-technical people will use, not other developers.

Some features or fixes might seem trivial for you, especially when you compare it to the complexity of another module or component.

Such a small fix can go a long way for you, and make a lasting impression on the client.

Manage expectations.

Expectations matter. Your manager wants to see progress.

Telling the truth, even if it might cost you your job (9 out of 10 it won't, so don't worry), is the surest way to manage expectations.

Most people over-estimate what they can accomplish, give unrealistic deadlines, and often end up facing increasingly stressful situations.

They end up explaining to their clients and their managers why things went wrong, stress too much to fix the problems without strategizing their next steps and end up being overwhelmed and unproductive.

Don't be like those people.

Stay true, trust your abilities, give yourself time.

If you got stuck on a problem, take a break and solve another.

Make sure you set a schedule and stick to it.

Make sure to schedule the requirements you want to tackle.

Deadlines work.

Try to give yourself internal deadlines and set personal goals for the project.

When adding such deadlines and segmenting your requirements into smaller chunks, you feel more confident in delivering progress.

Update your schedule daily.

Some days a requirement you are implementing might take you less time to implement than anticipated. Sometimes more.

With trial and error, you learn how to assess better.

Make sure you keep your schedule up to date. Updating your schedule forces you to think ahead and plan your steps.

Deliver fast, deliver often.

Remember: 1% improvement every day is much better than none at all.

You want to make sure you deliver fast and often.

Divide your work into small digestible chunks. This way, you can release bug fixes, features, or even both much more frequently.

Small, incremental improvements are better than 50 improvements released at once in a longer time frame.

You also decrease the risk of breaking a working prototype: by working in chunks, you know exactly where to find the problem if the prototype crashes.

Ask for an extension if you had to

You did everything laid out here, but the project's scope was too big to handle.

Ask for a time extension and explain your reasons. You will most probably get it.

Don't be afraid of your client or your manager. They're as human as you are. As long as you stay true, everything should be fine.

Final Words

Getting a new job or promotion is an exciting and potentially pivotal moment in one's career.

Every new project comes with its own set of challenges and difficulties.

You have to hit the ground running to prove your value, especially in the face of those difficulties.

To do so, you need to be organized, efficient, and to manage expectations around yourself.

All the steps and examples we have explored in this article were adapted for more technical people. However, the main principles of organization and expectations management do apply for the challenges you face in any career or industry.