Setting up an application is something that we repeat over and over again. Even when using a good third party tool they are either quickly outdated or are so complex, so much extra time is required learning about them. This can cancel out the time saving benefits of using a third party fully featured boilerplate.
A strategy that I want to adopt is to create my own starter template and update annually or when there is a feature I desperately want.
The reason I am going with this approach is:
- It is tailored to my own preferences.
- I have a greater awareness of what is going into the template and what the shortcomings are.
In the world of web and with so many third-party libraries, getting them all to work together may seem like a stack of cards.
Over time the libraries may change but there will be a core checklist of items that will remain mostly consistent over time.
What I have done is made a checklist of key things to include when setting up a project. I have also included opinions and examples of what libraries to use in 2020. While the checklist should remain similar over the next few years the libraries will very likely change.
I do tend to stick with libraries that are well supported as they are more likely to integrate well with other third parties.
I have included examples of what I have used in my starter but it is up to you what libraries you use.
My starter template is visible on GitHub. I won’t be maintaining it for public use but feel free to use it for reference.
Below is my personal checklist of key things to consider when setting up a project. Read on for a detailed description of each of these.
- Development framework
- Server-side rendering
- Starter project
- Component Libraries
- Type Checking
- Unit Tests
- Code Analysis and Formatting
- Git Hooks
- Source Control
- Component Isolation
- Progressive Web Apps
- Authentication and Authorisation
Decide on what framework or library you want to use.
As of now, there are many viable options. React, Vue and Angular are the three most popular right now, are well supported, stable and have a great community. Preact (a lightweight version of React) is also worth having a look.
For the rest of this article, I will be basing my examples on React as that is what I have the most recent experience with, but the principles should be similar if you are using something else.
To increase the performance of your web application, rendering pages on the server rather than the browser is a fantastic method.
The next thing is to decide on a starter project. Yes, I know this means I am building a starter on top of a starter, but many will not come with the features I desire out of the box. Create React App provides the basics. Gatsby is a fully featured site generator with a large variety of options.
Since I am using the Next for server-side rendering, then I am using the Next starter project.
Example: Create a Next React project.
Nowadays there are a lot of options regarding managing CSS.
Here are some tips:
- Have one stylesheet per component. Inherited styles can be extremely difficult to debug and control
- For shared styles go for global stylesheets or variables. Have a separate stylesheet for colours, padding and margin sizes and text styles.
- If you do use a CSS file, rather than CSS-in-JS, it is worth looking at CSS methodologies. BEM is the most popular.
I will be using the CSS-in-JS solution, styled-jsx, which is bundled in NextJS
Example: Next CSS Support
While this is optional and you can style everything from scratch, this can be a very quick way of producing a product quickly.
I won’t list them here since there are many articles listing the best component libraries, but the one I have decided to use for now is Semantic UI (the React version) as I like the look and feel of it and the library is fairly extensive. I have come across issues when incorporating my own styles, therefore I might consider not using a component library if custom styling is important.
Example: Add TypeScript to a Next project.
There are quite a few testing frameworks out there. Mocha with Chai, is very popular. However, I am going with Jest, which is built by Facebook, responsible for React and contains the runner and assertion library as a complete solution. ts-jest is a great library to install Jest with TypeScript support.
Example: Installing ts-jest
Example: Installing React Testing Library
N.B. I did come across a few issues when setting up jest, with Next, with TypeScript.
- When running
npx ts-jest config:initchoose jsdom for the test environment.
- In addition in the tsconfig.json file make sure the settings here are set.
- Also, make sure
import React from 'react'is imported at the top of each component, even if it is not required for Next.
Code Analysis and Formatting
It’s a good idea to include code analysis and formatting. Not only does is help you stick to good practises but it would also end debates about tabs and spaces. No more pedantic code reviews.
Right now Eslint has good TypeScript support, therefore, the formerly popular TS Lint library is being used less and less.
Example: Integrating Prettier with ESLint
If there is even a slight chance that your product will be in multiple locations, it is best to introduce internationalisation sooner rather than later. It can be a pain looking for strings in a large codebase.
While the next-i18next library, which is an integration between Next.js and i18Next (no relation), is an option, you would need to create a custom NextJS server for the rendering meaning some out of the box functionality like serverless and error pages, may be lost.
I found next-translate to work well, although it does involve code generation which may not be for everyone.
Most websites are not going to stick to one page. In a lot of cases, you are going to want to have some sort of routing mechanism. With Next.js routing is at the heart of the system in order to manage Server Side Rendering, meaning that no external dependencies are required.
However, if you are not using Next.js, options like React Router are available.
Ensure that you have a README.md file at the root of your project to instruct users how to run your project.
Especially if your code is public, you might want to add a LICENSE file, detailing the usage of your application. choosealicesnse.com is a great resource to determine which license is right for your project.
It is a good idea to add hooks, to run tests, analysis code and format before committing code.
Husky is a great way of adding hooks easily in a node environment.
Git is the most popular solution for source control.
It is often a good idea to host your code remotely, even if working alone. GitHub, Bitbucket and GitLab are all popular options that have fantastic free tier options.
Most web starters do not need to be hosted, but if I have an idea and want to demo something quickly, it is good to have a plan for that. As I am using NextJS, Vercel which was built by the same company is a good choice to start off with.
CI/CD has come a long way in only a few years. Most online repos now come with this feature. CI is being handled in GitHub with CD is being handled in Vercel.
Component isolation libraries are a fantastic library used to view and develop components without worrying about other code. The most popular one is Storybook, while React Styleguidist is another alternative.
Example: Install Storybook for React
Example: Add Typescript support to Storybook
Progressive Web Apps
Progressive Web Apps are web applications that have been designed so they are capable, reliable, and installable. These three pillars transform them into an experience that feels like a native application.
It is important to remember that a progressive web app isn’t a library or a framework, but rather a set of guidelines in order to make an app have many of the benefits found in a native application, in both performance and features.
There is a checklist for how an application can be a good Progressive Web App.
The best way of analysing your current site against those guidelines is to use Lighthouse. Lighthouse would generate a report after performing an analysis on your site. You can either use it within Chrome Dev Tools or use the CLI to generate a report on your codebase for regression purposes.
Example: I am using next-pwa to help manage files needed to make a site a better PWA.
Example: Based on my setup. I’m using GitHub actions to run the report.
Authentication and Authorisation
In a lot of cases, you are going to want to have user accounts and roles.
There is a multitude of ways of doing this, and this is really going to be dependent on the requirements of your application. Do you need to integrate with an existing system? Are you happy using a third-party for your authentication? What are the requirements of the API?
For my starter, I am using Firebase with Google sign up.
To generate Favicons and App Icons, I used this site: https://www.favicon-generator.org/. However, there are many alternatives out there.
Images in my starter are currently served statically directly from the NextJS site, although I can opt to use a CDN.
It is important to make your site follow accessibility standards to allow as many people as possible to enjoy your site as possible.
I have installed the Deque Axe Chrome extension, which informs me if my page is not conforming accessibility standards. It is not exhaustive but it definitely goes a long way.