nextjs-tailwind-storybook-with-ci-cd

This repository is built to provide a ready-to-go template for the projects that are using the following tech stacks:

1. NextJS
2. Tailwind
3. Storybook
4. Jest
5. React Testing Library
6. Eslint
7. Prettier

This template will provide the full setup under the hood and will save a big portion of your time. You have to just create your new repo using this template.

Table of Contents

• nextjs-tailwind-storybook-with-ci-cd
  • Table of Contents
  • How to Create Repository Using This Template?
  • Package Versions
  • Available Commands
  • Folder Structure
  • Change NextJS Config
  • Change Tailwind Config
  • Change Unit Test Config
  • Change Eslint Config
  • Change Eslint Config
  • Change Storybook Config
  • CI/CD in This App
  • Storybook doesn't Support Some NextJS Features
  • License
  • Deployment Guideline
    • How to Deploy NextJS App on Vercel

How to Create Repository Using This Template?

1. Click on this link to generate a new repo using this template.
2. Give a name to your repo.
3. Provide a meaningfull description.
4. You can keep the Include all branches options unchecked.
5. Click on Create repository from template button and boom :boom:. Your repository is ready.
6. Now if you clone the repo in your PC and run yarn, all the dependency will be installed.
7. Then running yarn dev will start the app at http://localhost:3000.
8. running yarn storybook will start the storybook of your app at http://localhost:6006.

Package Versions

Following versions were installed when this template was built.

Available Commands

There are some commands preadded to this template. These commands will help to execute basic tasks.

1. Following command will start the dev server at port 3000 and we can visit the site at http://localhost:3000.

   yarn dev
   

2. Following command will create a production build of the site.

   yarn build
   

3. Following command will start a server at port 3000 with the production build (created using yarn build) and we can visit the site at http://localhost:3000.

   yarn start
   

4. Following command will check any linting issue according to the eslint rules set in the .eslintrc.json file.

   yarn lint
   

5. Following command will execute all the unit tests (file with *.test.jsx, *.test.tsx, *.test.js or *.test.ts extention) and check whether all the tests pass or not.

   yarn test
   

6. Following command will execute unit tests (file with *.test.jsx, *.test.tsx, *.test.js or *.test.ts extention) and check whether all the tests pass or not in the real-time.

   yarn test:watch
   

7. Following command will start the storybook server at port 6006 and we can visit the story at http://localhost:6006.

   yarn storybook
   

8. Following command will create a static web application capable of being served by any web server. For more info please visit Publish Storybook.

   yarn build-storybook
   

Folder Structure

Before working on a project, we should know about its folder structure. This helps a lot to understand where to find which components or portion of codes. In this template, the folder structure was tried to be kept as simple as possible.

1. .github/workflows: This folder is used to keep all the files related to github actions. We've already setup a basic CI/CD in the template and named the file tests.yml. We can create more yml files for different actions.

2. .storybook: All the storybook related config files like theme, seo, preview, manager etc live inside this folder.

3. components: In our web app, we'll have to build many reusable components like button, input, modal etc. This is the place where we can keep all our reusable components. While creating a component we have tto ensure the following rules have been followed in order to maintain the consistency.

   1. Each component must have a folder and index.js file inside the folder. For example: if we are creating a button component, the structure should be:

      components
      | - Buttton
          | - Button.jsx
          | - index.js
      

      Then we can access the component from outside using ./componets/Button.

   2. If a component has some sub-components, then we can keep them in a folder named subComponents inside that component.

      components
      | - Buttton
          | - subComponents
              | - ButtonOverlay
                  | - ButtonOverlay.jsx
                  | - index.js
          | - Button.jsx
          | - index.js
      

   3. Each component must have a story file (for storybook). Story file names should be in <Component Name>.stories.jsx this format.

      components
      | - Buttton
          | - subComponents
              | - ButtonOverlay
                  | - ButtonOverlay.jsx
                  | - index.js
          | - Button.jsx
          | - Button.stories.jsx
          | - index.js
      

   4. Each component and sub-components must have a test file (for unit testing). Test file names should be in <Component Name>.test.jsx this format.

      components
      | - Buttton
          | - subComponents
              | - ButtonOverlay
                  | - ButtonOverlay.jsx
                  | - ButtonOverlay.test.jsx
                  | - index.js
          | - Button.jsx
          | - Button.stories.jsx
          | - Button.test.jsx
          | - index.js
      

   That's a general set of rules for the components folder. But of course, you can set your own rules and structure. In that case, you might have to change storybook, jest, and other configs.

4. pages: This folder keeps all the page and api related files of our app. It's a basic feature provided by NextJS. To learn more about them, you can read the following docs from NextJS.

   1. NextJS Pages
   2. NextJS API Routes

5. public: This folder is also provided by NextJS. It keeps all the static assets like images, icons, audios, pdfs etc. To learn more about this folder, visit Static File Serving in NextJs.

6. styles: All the global css or scss files will be kept in this folder. You can keep the local files too with an appropiate folder structure in it.

Change NextJS Config

If you need to change settings of nextjs, then next.config.js and jsconfig.json is the place where you'll have to work. Currently, we've done a bare minimum setup in both files.

But in the jsconfig.json file, we've setup a path alias for the root directory. You can access the root directory using @/ this alias. To learn more about it, read Absolute Imports and Module path aliases in NextJS. Also, you can learn more about next.config.js file from next.config.js Doc.

Change Tailwind Config

If you need to change settings of tailwind, then postcss.config.js and tailwind.config.js is the place where you'll have to work. You can modify or extend the tailwind theme in tailwind.config.js file. For more info, you can read Tailwind Configuration doc.

Change Unit Test Config

Basically, we can modify jest unit testing setup using jest.config.js and jest.setup.js file. To learn more about it, you can go through Jest and React Testing Library in NextJS.

Change Eslint Config

We can use .eslintrc.json file in order to add or remove any eslint rule. For more details, you can read ESLint Configuration Files Doc.

Change Eslint Config

.prettierrc.json file is there to change prettier config of the app. We've added some configs in this file. To remove or add any config, you can go through Prettier Configuration File Doc.

Change Storybook Config

All the config files of storybook are kept in the .storybook folder.

All the project related configs for storybook are in main.js file. If you need to change anything in the storybook preview section, then preview.js file is the appropiate one. Learn more from Configure Storybook Doc.

To modify the theme, we may have to work in appTheme.js and manager.js files. To learn more about theming, visit Storybook Theming Doc.

If we want to do any SEO related changes, then we may have to modify manager-head.html or main.js files. To read more about it, visit Search engine optimization (SEO) Doc.

If we want to access any assets in the public folder, then we don't have to mention public in the src url. You can emit that. For example, we have an image xyz.png in public folder. Then we can access this image from any story using ./xyz.png. Learn more about it from Serving static files via Storybook Configuration Doc.

If we want to write detailed descriptions about our components, props and stories we can use JSDoc comments. To learn more please, visit the following docs from Storybook.

1. Writing descriptions in Storybook
2. Writing descriptions of Props in Storybook

CI/CD in This App

A github action has been setup in tests.yml file inside .github folder. This action runs js linting and unit test every time a new commit has been pushed to origin. You can write more github actions here as per your need.

Storybook doesn't Support Some NextJS Features

Currently, storybook doesn't support some features (TurboPack, Server Component, SWC etc) of NextJS v13. But if you are not using these features, then there shouldn't be any problem with storybook. [Source]

License

Being an open source repository, this repo has a MIT License in it. But when you are using this template, you should have to use your own license here :rotating_light::rotating_light::rotating_light:. You can easily generate this. You can read Licensing a repository Doc.

Deployment Guideline

How to Deploy NextJS App on Vercel

1. Visit Vercel's Dashboard.
2. Under Import Git Repository section, click Continue with Github button.
3. Install Vercel in your GitHub account when prompted.
4. Select your NextJs app repository and click Import.
5. Add environment variables (if present) from your NextJs app's .env file under Environment Variables tab in Configure Project section.
6. Click Deploy.
7. On successful deployment, you will be directed to a new url with a preview image of your deployed NextJs app.
8. Click on the preview image.
9. You will be directed to a url that looks like [DOMAIN-NAME].vercel.app.