# Introduction
I decided to bundle my frontend experience and best practices into a modern frontend starter. The starter is an example of how, with my current knowledge and experience, I would build a frontend web app for a portfolio website like simonkarman.nl.

> Disclaimer: In no way am I trying to advocate that this is the only or the best solution for a frontend project. Nor am I claiming the solution is usable for every frontend app. This solution is simply what I currently think is well suited for a static generated web app. I based this on my own expertise and knowledge and I hope that this starter gives you some takeaways for your own frontend projects. If you have any feedback or suggestions, please [let me know](https://simonkarman.nl/contact), I am always willing to learn more!

# Trying it out yourself
You can try out this starter by copying the [source code](https://github.com/simonkarman/nextjs-frontend-app-starter), reading the Getting Started section in the README.md file, and then modifying the projects to suite your own needs. If you do, attribution is appreciated.

A live demo of the app can be found on [karman.dev/nextjs-frontend-app-starter](https://karman.dev/nextjs-frontend-app-starter/). It showcases the exported version (`yarn build`) on a static cdn.

# History
During the corona pandemic in 2020, I rebuilt my portfolio website using [VueJS, Nuxt, and Contentful](https://simonkarman.nl/projects/simonkarman-nuxt). After that, during my work at Tikkie I worked with React and React Native using Typescript. I have been pondering lately about what I have learned and which improvements I can make to my personal portfolio website. That is why I decided that, instead of rebuilding my website again, I would write a minimalistic showcase of all the features I would use if I were to rebuild my website right now.

# Features
I build this starter with a few different features that I want to highlight.

The starter was built using React with Next.js and TypeScript and can be used to generate a static portfolio website by using the Next.js export functionality.

The content is created in Contentful, which is a CMS, and the type definitions for Contentful are auto-generated.

The project defines some commonly used custom written React Hooks, it employs styling using the Styled Components library, achieves linting of the source code using ESLint, runs Unit Tests using Jest, and adds precommit hooks using Husky.

That's quite a lot of features, so let's go through each feature one by one.

## React with Next.js and TypeScript
The starter is written using React, Next.js and Typescript. With technologies such as [React Native](https://reactnative.dev/) and my current professional experience it felt like the logical choice to use React over Vue.

The React framework I decided to work with is [Next.js](https://nextjs.org/), which is very similar to the Vue framework [Nuxt](https://nuxtjs.org), which I for my portfolio website. In short, Next.js ensures that common things like creating multiple pages, links between those pages, prerendering pages, and more are ready to use right out the box.

TypeScript. While a few years ago TypeScript support for libraries was sometimes lacking, nowadays TypeScript has been fully adopted. TypeScript provides benefits that are a necessity in a modern way of working. It ensures type safety, code completion, integrated documentation, and improved refactoring.

Below is an example of a Page component in Next.js written in TypeScript:
```ts
const HomePage: NextPage = () => (
  <>
    <h1>Welcome!</h1>
    <p>
      This starter is built using React, Next.js, and Typescript.
    </p>
    <p>
      <LinkTo href="/projects">
        Projects can be found here
      </LinkTo>
    </p>
  </>
);

export default HomePage;
```

## Contentful and TypeScript
The projects that are on my website are stored in a Content Management System (CMS). The CMS I'm using is [Contentful](https://www.contentful.com/). In contentful you can create your own entity types and give these entity types properties. I created an entity type 'project', with properties such as a name, a title, an image, and so forth.

The website can fetch the defatils of projects from contentful to display on the pages. But how does your IDE now what properties to expect on a 'project' entity that is returned from Contentful? We can use a TypeScript interface for this. A tool exists to extract the TypeScript interface from a contentful entity type. This tool can be found on [contentful-typescript-codegen](https://github.com/intercom/contentful-typescript-codegen).

An example of the interface that generated by the project is shown below.
```ts
// part of '@types/generated/contentful.d.ts'
export interface IProjectFields {
  /** name */
  name: string;

  /** title */
  title: string;

  /** description */
  description: string;

  /** tags */
  tags?: string[] | undefined;

  /** image */
  image: Asset;

  /** and more ... */
}
```

In the starter you can run `yarn contentful-typescript-codegen` to generate these TypeScript interfaces. You can find the resulting types in [@types/generated/contentful.d.ts](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/%40types/generated/contentful.d.ts). You can look at the `contentful-typescript-codegen.sh` file to see more details. Make sure you create a `.env.local` property specifying the values as explained in the README.md of the project to ensure you app can successfully connect to Contentful.

## Next Export
The [`next export` feature](https://nextjs.org/docs/advanced-features/static-html-export) allows you to export you app to static files (HTML, CSS, and JavaScript). An exported Next.js app run standalone, without the need of a Node.js server. This is useful when you want to deploy your website to a static file hosting environment.

To create a static export, Next.js needs to know all the pages that it needs to generate. Next.js looks at the pages you defined in the `/pages` directory and generates a HTML file for each of them.

However when pages use dynamic routes, such as `simonkarman.nl/projects/karmannet`, where `karmannet` is the dynamic part of the route. Next.js needs to know about all the different dynamic routes before it can generate the websites. To let Next.js know which dynamics routes it should use you can export a method called `getStaticPaths`. This method should generate an array of all the different dynamic parameters you want to generate that page with.

This starter uses this structure in the [`pages/projects/[name].tsx`](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/pages/projects/%5Bname%5D.tsx) file to generate a page for each project it can find at contentful.

```ts
// part of 'pages/projects/[name].tsx'
export const getStaticPaths: GetStaticPaths = async () => {
  // First get all the projects from contentful
  const projects = (await contentful().getEntries<IProjectFields>('project')).items
    .map((project) => project.fields);

  // Then create a path for each project based on the project name
  return {
    paths: projects.map((project) => ({ params: { name: project.name } })),
    fallback: false,
  };
};
```

## React Hooks
React Hooks is the new way of writing React components that use state without having to write a class. This means that reusing and structuring you components becomes easier.

If you have used React before you have probably written some custom React hooks. Within the starter I have provided some hooks that I commonly use. You can find them in the `hooks/common` directory.

- [useArray](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/hooks/common/useArray.ts) - This hook makes it easy to work with arrays in your state.
- [useAsync](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/hooks/common/useAsync.ts) - This hook takes an async function, invokes it, and returns an array with information about the progress and execution of the function. This first element in the returning array is a boolean that indicates whether the async function is still in progress, the second element is the response of the async function when it is resolved, and the third and last element is the error for when the async function was rejected. 
- [usePrevious](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/hooks/common/usePrevious.ts) - This hook makes it possible to keep track of the a previous value of some state.
- [useStateWithHistory](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/hooks/common/useStateWithHistory.ts) - This hook keeps track of the changes that are made to a variable and makes it possible to go back and forward in this history.
- [useStorage](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/hooks/common/useStorage.ts) - The hooks `useSessionStorage` and `useLocalStorages` allow you to store variables in either the session or local storage in the browser. Note that this can have some issues when used with Server Side Rendering.
- [useTimeout](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/hooks/common/useTimeout.ts) - This hook lets you execute a method after a certain amount of time.

> These hooks are inspired by [Web Dev Simplified](https://www.youtube.com/watch?v=vrIxu-kfAUo&ab_channel=WebDevSimplified) and have been rewritten in TypeScript by me.

An usage example can be found in the [`hooks/projects/useProjects`](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/hooks/projects/useProjects.ts)-file. There the `useAsync` hook is extended and used to fetch all the projects from Contenful. Usage of this hook can be found in the [`pages/projects.tsx`](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/ages/projects.tsx) file.

## Pregeneration vs Dynamic Loading
The contect of pages can be pre-generated during the `next export` or data can be fetched by the browser while a user loads the page. Both approaches have pros and cons. The [projects page](https://karman.dev/nextjs-frontend-app-starter/projects/) demonstrates the difference between the two.

> The `getStaticPaths` method can be used to pre-generate pages during export, while with the `useProjects` hook shows how you can dynamically load new data at run time in the browser of the client.

The upside of pregenerating the list is that the page loads very fast and that the data is also part of Search Engine Optimization (SEO). A downside however is that you need to create a new export of your website any time you make changes to it. If your content changes often, this might be a problem.

The upside of loading content dynamically is that the website will always fetch the lastest information from your source. A downside is that the client side code also needs to be able to access the contentful data directly, meaning your (read-only) api key will ship to your clients and that clients have to wait precious milliseconds before the content is loaded.

A combination of both works best in most cases: Pre-generate the pages, but dynamically update them whenever new projects are available.

## Styled Components
For styling I used [Styled Components](https://styled-components.com/). What's great about styled components is that it really fits well into the component based approach of React, which makes it easy to create your own custom style library. Styled components comes out of the box with a great color scheme and a grid layout system.

An example of a styled component can be seen below:
```ts
// Define a Box with shadow, which is a div
const Box = styled.div`
  box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, 0.2);;
  border: 1px solid gray;
  margin: 0.5em;
  padding: 0.5em;
`;

// Then you can use the Box in your Page just like it is a component
const Page = () => (
  <>
    <Box>
      <h1>Title</h1>
      <p>Text</p>
    </Box>
  </>
);
```

Next.js has to understand that styled-components are being used. You can do this by adding the `styled-components` plugin the the `.babelrc` file.

```json5
# in '.babelrc'
{
  ...
  "plugins": [
    ...
    [
      "styled-components",
      {
        "ssr": true,
        "displayName": true,
        "preprocess": false
      }
    ],
    ...
  ]
}
```

There is also a downside to using styled components. Since your styles are generated during runtime they are relatively slow to load. Luckily when using a pre-generation styles are part of the static files, so this is less of an issue.

## Git Hooks with Husky
As a developer you don't want to push code to your git repository that breaks. This means you'll first need to fix your issues before commiting your code, which ensures all code pushed to the origin repository is valid.

I use Git hooks to achieve this. Everytime I try to commit new code the code will be build, tested, and linted. Whenever one of these steps detects an issue, the commit will not go through and fail. To easily setup Git hooks in an npm managed project you can use [Husky](https://www.npmjs.com/package/husky/v/4.3.8)

For the linting step I use [ESLint](https://eslint.org/). ESLint statically analyzes your code to quickly find problems. Many problems ESLint finds can be automatically fixed. Only problems that cannot be automatically fixed have to be manually looked at. The rules and configuration of ESLint I use can be found in the [`.eslintrc.js`](https://github.com/simonkarman/nextjs-frontend-app-starter/blob/main/.eslintrc.js) file.

For the unit testing step I use [Jest](https://jestjs.io/). Jest runs all tests it can find in files that match the `*.test.ts` expression. Please note that this starter does not contain proper unit tests.

# Visual Studio Code
When working on React project I generally use Visual Studio Code. Within VS Code I use some extension to make my life easier:
- [Auto Rename Tag](https://marketplace.visualstudio.com/items?itemName=formulahendry.auto-rename-tag)
- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
- [Jest](https://marketplace.visualstudio.com/items?itemName=Orta.vscode-jest)
- [vscode-styled-components](https://marketplace.visualstudio.com/items?itemName=jpoissonnier.vscode-styled-components)

You can also enable fixing linting errors everytime you save a file in VSCode by adding the following to your VSCode settings file (`.vscode/settings.json`):
```
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
}
```

# Trying it out
That's all! I hope that this starter gives you some takeaways for your own frontend projects. If you have any feedback or suggestions, please [let me know](https://simonkarman.nl/contact), I am always willing to learn more!

You can try out this starter by copying the [source code](https://github.com/simonkarman/nextjs-frontend-app-starter), reading the Getting Started section in the README.md file, and then modifying the projects to suite your own needs. If you do, attribution is appreciated.

A live demo of the app can be found on [karman.dev/nextjs-frontend-app-starter](https://karman.dev/nextjs-frontend-app-starter/) and showcases the exported version (`yarn build`) on a static cdn.

Starter for a modern frontend using Next.js with TypeScript, Contentful, and more.

Next.js

nextjs-frontend-app-starter

Next.js Frontend App Starter

The v1.1.0 release of [b11-party](https://www.simonkarman.nl/projects/b11-party) 🚀, a multiplayer game based on Mario Party with minigames themed around the 11th board of Study Association Sticky.

This release includes the following mini games:

- 📦 Red Cup
- 📦 Ketel Vangen
- 📦 Batavieren
- ✏️ B11 Balloon (reworked)
- ✔️ Bussen (new)
- ✔️ Kamerdienst (new)
- ✔️ Consti (new)
- ✔️ Kelder Borrel (new)

More information on [b11-party](https://www.simonkarman.nl/projects/b11-party) can be found here: [b11-party](https://www.simonkarman.nl/projects/b11-party).

The v1.1.0 release of b11-party 🚀, a multiplayer game based on Mario Party with minigames themed around the 11th board of Study Association Sticky.

B11 Party Windows v1.1.0

Bussen MiniGame B11 Party

b11-party-mar2021

B11 Party v1.1.0

## Introduction
It is a lot of fun to build your own website. Unfortunately part of building a website is hosting it and publishing it every time you make a change to it. In this article I would like to show you that hosting, publishing, and even setting up an automated deployment pipeline is a piece of cake!

[lisapruijn.nl](https://www.lisapruijn.nl) is a great example of this.

Are you still spamming F5 on your machine while developing your website to see you changes, are you still uploading files manually via ftp to publish your website, or are you still write plain html and css, then this is the perfect read for you. In one evening, without much programming experience, you'll be able to setup an development and production environment for your personal website.

## The Architecture
The diagram below describes the architecture. This structure can be setup in one evening. It contains four different components: your development machine, the code repository, a hosting platform (including the cicd pipeline), and a domain registration.

![lisapruijn.nl setup](//images.ctfassets.net/r26fkm24j6bh/5iJHx0kAdAYzb8QcpIkfG9/89695b25e857e70ef06533ecd2fe280d/lisapruijn.nl-setup.png)

## Your Development Machine
Our goal is to show a webpage that is accassible through the internet from your mobile phone or computer. Let's start by creating this page. To do this we'll first need a tool to write our code in. There are many options here such as Intellij IDEA, Webstorm, Sublime Text, and many more. We have decided to use Visual Studio Code (VS Code).  Once you have installed VS Code you also need to install Git (for our source code management) and Node (for building our website).

You can download **VS Code** here: [https://code.visualstudio.com/](https://code.visualstudio.com/)
You can download **git** here: [https://git-scm.com/](https://git-scm.com/)
You can download **Node** here: [https://nodejs.org/en/](https://nodejs.org/en/)

> Note: A restart of your computer might be required.

After downloading and installing these programs you should be able to open VS Code. In the top bar you can click on `Terminal` -> `New Terminal` to open a new terminal (Ctrl + Shift + `). In this terminal you should be able to use both git and Node. You can verify this by running the following two commands.

```
$ git --version
$ node --version
```

If they are installed correctly you should see the version information of both tools.

Now its team to install the framework that we'll be using to develop the webpage, React. React is a library for building user interfaces. More information on React can be found here: [https://reactjs.org/](https://reactjs.org/). To install React run the following command from the terminal.

```
$ npx create-react-app my-website --template typescript
```

In the above command you can replace `my-website` with the name of your website. For example: `lisapruijn.nl`. This will create a new directory in which it will setup a git repository, node project, and install the required typescript and react dependencies you need. You can read more about the TypeScript language here: [https://www.typescriptlang.org/](https://www.typescriptlang.org/)

First open the directory you just created with the npx command in VS Code. You can do this by going to `File` -> `Open Folder` and there selecting the folder you just created.

You should now be able to start your local development server on your local machine by running the following command.

```
$ npm start
# then visit http://localhost:3000 to view your website
```

If you now change the `src/index.tsx` by replacing the placeholder text with some information about you. Notice that when you save your changes in VS Code, the website automatically refreshes in your browser for you to preview your changes. You can read more on hot reloading here: [https://blog.logrocket.com/setup-react-hotloader-in-10-minutes-3175dfdbf38a/](https://blog.logrocket.com/setup-react-hotloader-in-10-minutes-3175dfdbf38a/)

If you're happy with your changes you can either use the Source Control manager in VS Code (under Ctrl + Shift + G) or use Git from the commandline. To use git from the commandline run the following commands to add, commit, and push your code.

```
$ git add --all
$ git commit -m "My first changes"
$ git push
```

When pushing the code to git you'll notice that an error will pop up. This is because we havent setup a repository to push or code to yet. This is what we'll do in the next section.

## Code Repository
We need to host the code of our website somewhere. For this we'll use a version control system called Git. Git is a free, open source, and is designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. More information on git can be found here: [https://git-scm.com/](https://git-scm.com/)

You can use BitBucket, GitLab, and other provides for this. We decided to use GitHub. You can create your own GitHub account for free here: [https://github.com/](https://github.com/).

Once you have created your account and logged into the website you can create a new repository. Give it a clear name such as `lisapruijn.nl`, add a description, set it to either public or private, and please choose NOT to initialize the repository with any files.

Once you have created your repository you should see a command that looks like the command below. Please replace the `your name` and `your repository name` (including `<>`) with the actual values and run the command in your terminal. This adds the just created repository as one of the remotes of your local repository.

```
$ git remote add origin https://github.com/<your name>/<your repository name>.git
```

After doing this, you should be able to push your changes to you repository. You can do this by running the following command.

```
$ git push -u origin main
```

If you now visit your GitHub account in the browser you should be able to find your code and changes there. Now every time you make changes locally and have verified they look good on your local machine (with `npm start`). You can use the following three commands to push your changes to your git repository.

```
$ git add --all
$ git commit -m "An explanation of the changes that were made"
$ git push
```

## Hosting
You want visitors of you side to see the actual website you build, and not the code you have written. To do this we'll to build our code into an artifact and publish this artifact to a hosting provider. There are many websites and services that provides this, but the provider we're using today is Netlify. More information on Netlify can be found here: [https://www.netlify.com/](https://www.netlify.com/). For small use it is free to use Netlify, but please check the pricing page if Netlify is suited for your needs.

At Netlify you also have to create an account. After you created your account you can click the green `Create a new site from Git` button. There you can add your GitHub account and select the repository you just created for you website.

Make sure that you set the build command to `npm run build` and the publishing directory to `dist`. This ensure that the package is build correctly, and the dist directory is used as the artifact for the hosting of the website.

Once you have setup your project in Netlify you should be able to visit your website on `http://<your netlify project name>.netlify.app` by replacing `your netlify project name` (including `<>`) with the name of your project that you just created in Netlify.

## Domain Registration
Instead of the `netlify.app` url, you'll ofcourse want to use your own domain name. To achieve this you'll have to buy and register you own domain name. If you don't want to pay any money you can skip this section.

Domains names are labels (such as your street adress) to navigate the internet. When you buy a domain name you can configure where this domain name navigates to. This is the domain name system, DNS. Once your have registered you domain name you can change the DNS settings of your domain name. In our case we want to point the root domain name (@lisapruijn.nl) and the www subdomain (www.lisapruijn.nl) to our netlify app.

The domain name registration company I use and trust for all my domain names is NeoStrada. You can buy your own domain name via NeoStrada here: [https://partner.neostrada.com/idevaffiliate.php?id=385](https://partner.neostrada.com/idevaffiliate.php?id=385) (please note that this is my affiliate link).

Once you have bought and registered your domain you can go to `Dashboard` -> `Domainnames`. Here you should be able to find the domain name you just bought. You can click on the gear icon and chose `Change DNS settings`. If you scroll down you can see the individual records for your domain name. There should be quite a few that are automatically created by NeoStrada.

To configure the DNS in such a way to point to our Netlify app you'll have to add the following two DNS records:

```
@ A 104.198.14.52 0 3600
www A 104.198.14.52 0 3600
```

> Note: that changing DNS records can take up to 24 hours to propegate through the domain name system.

More information on how to setup your DNS records for Netlify can be found here: [https://docs.netlify.com/domains-https/custom-domains/configure-external-dns/](https://docs.netlify.com/domains-https/custom-domains/configure-external-dns/). This also shows an example of how to setup branch subdomains to automaticly turn your feature branches in to their own subdomains.

After you have setup your DNS records in NeoStrada you can go back to Netlify to add you domain name as the primary domain of your projects. Once you have done that you can scroll to the bottom of the page to enable TLS (Transport Layer Security) for your websites, which ensure your visitors will visit your website securly using an HTTPS connection. It can take a bit of time before the generation of the certificate succeeds, please try again after 1 and 24 hours.

## Final Remarks
Now every time that you make changes on your local machine, commit those changes, and then push that to your repository your website should update within a few minutes.

The next steps! For those new to HTML you can read this excellent article on how to get started [websiteplanet.com/blog/html-guide-beginners](https://www.websiteplanet.com/blog/html-guide-beginners/)

Please keep in mind that Netlify has pricing plans based on your usage: [netlify.com](https://www.netlify.com/)
Read more on how to use Git: [git-scm.com/doc](https://git-scm.com/doc)
Follow a tutorial on how to develop your website in React: [reactjs.org/tutorial](https://reactjs.org/tutorial/tutorial.html)

I hope to have given you a nice starting point for you personal website. Happy coding!

Example development setup of a portfolio or personal website.

Portfolio starter

Last 3 Projects (static)

Last 4 Projects (dynamic)