Prerequisites: Node 14 or 15

---

👇 Start Here

Please make sure to use Node 14 or 15 before starting the setup process.

🔨 Start Dev Mode

1. run npm i to install dependencies
2. run npm start to start a local development server

🚧 First Time Setup

• Website Info

  1. open gulpfile.mjs and update config = {...} object with your new website info (siteName, siteURL, androidColor, cacheId...)

• Icons + Manifest

  1. place a copy of your logo (should be in SVG + named logo.svg) inside the config folder
  2. run npm run favicon to generate all icons/favicon/manifest/...

• Fonts

  1. change config/font.json to specify which fonts you want to use from Google Fonts
     • specify any font family (Roboto...) & styles (400,300italic...) in json file
     • specify a web safe font as a fallback for each custom font. Customize fallback font properties to minimize CLS using this tool: https://meowni.ca/font-style-matcher/
  2. run npm run font to automatically download/generate all fonts extensions/styles...

🚀 Build For Production

1. run npm run image to minify/resize images
   note: run this only once, but you have to rerun it if you add any new images to the img folder
2. run npm run build to build for production
3. run npm run netlify or npm run firebase to deploy to your provider of choice (or just push to Github if you are using Cloudflare Pages / Netlify CD)

---

---

👇 Important

📷 Images

• You should wrap every img tag with a picture tag. Also you should use data-src instead of the normal src attribute to lazy load images

  Example:

    <picture>
    <img data-src="./img/example.png" alt="example" height="50" width="50" />
    </picture>
  

  note: All images are lazy loaded by default, but you can customize this in util/shared.js

• Faster Build Tip

  • To avoid long build times in CI when deploying for example to Netlify commit your dist/img folder to your Github repo so you don't have to run the npm run image command on every deploy.

🚧 Failure of npm i fix

Sometimes npm i fails, this has nothing to do with the TurboKit script.

It's an issue related to the image processing library sharp.

in CD/CI

To fix this issue simply set the following environment variables in your CD/CI config (netlify, cloudflare pages...)

NODE_VERSION: 14.17.5

PYTHON_VERSION: 3.7

in Window / MacOS / Ubuntu

use nvm to switch to node version 14 or 15 and then run npm install.

Note: using node 16 or 17 or later might make sharp installation fail and then thus stop the npm i task

---

---

📜Learn More

☕ All package.json Scripts

Development

• npm start
  • start local development server

First Time Setup

• npm run favicon

  • generates PWA favicons, manifests and injects them into HTML files

• npm run font

  • downloads fonts from 'Google Font' as specified in config/fonts.json
  • injects them into shared/css/shared.css

Production

• npm run image

  • This script should be run only if you have added new images to your src/img folder. All the images that the script generates will go to img folder

• npm run build

  • minify, bundle and build for production files will output everything to dist folder. check build task in gulpfile.mjs to understand everything that this command does. (you should run it before every deploy)

• npm run full

  • run a full build: will run both commands npm run image and 'npm run build'

Deploy

• npm run netlify

  • deploy website to netlify (this is manual deployment. Of course, you can use netlify auto deploy on Github push)

• npm run firebase

  • deploy website to firebase

Maintenance

• npm run format

  • format all src folder files

• npm run test

  • run a local lighthouse test of the dist folder

• npm run test-live

  • run a lighthouse test of a live website in production (change siteUrl property in gulpfile.mjs config object before running this )

• npm run update

  • update all package.json dependencies and install them

📂 folder structure

├── config         # fonts/favicon/eslint/prettier... configuration files
├── dist           # all build production files
├── img            # all production images generated by `npm run image`
├── src            # all source files
│   ├── audio             # all your audio files
│   ├── font              # generated fonts by `npm run font` command
│   ├── img               # all your source images
│   ├── json              # all your source json (lottie files...)
│   ├── meta              # all icons + web manifest
│   ├── pages             # all your website pages (html,css,js)
│   │   ├── css               # all libraires CSS files
│   │   └── js                # all libraires JS files
│   ├── util              # utility files shared between all pages
│   │   ├── shared.css        # shared CSS file
│   │   └── shared.js         # shared JS file
│   ├── video             # all video files
├── .prettierrc     # Configure prettier formatting rules
├── netlify.toml    # Configure netlify hosting
├── firebase.json   # Configure firebase hosting
└── ...