Vite6 +TypeScript+React18+Tailwind+ESlint+Prettier+Husky搭建企业级前端项目

1,303 阅读5分钟

前言

很多小伙伴苦于无法搭建一个规范的前端项目,导致后续开发不便,今天给大家带来一个基于Vite6+TypeScript+React18+Tailwind+ESlint+Prettier+Husky的搭建教程

本文使用pnpm 包管理工具,安装项目依赖

1. 初始化项目

  1. Node版本要求:教程的 node 版本为 V18.20.5,Vite需要的 Node.js 版本 18+或 20+ ;
  2. 创建项目
# npm 7+,需要添加额外的 --:
pnpm create vite@latest my-react-app -- --template react-swc-ts

注意: Vite 需要  Node.js  版本 18+ 或 20+。然而,有些模板需要依赖更高的 Node 版本才能正常运行,当你的包管理器发出警告时,请注意升级你的 Node 版本。

2.配置 TypeScript

  1. 修改package.json
"scripts": {
	"ts": "tsc -b",
 }
  1. 运行pnpm ts 即可检查文件中是否包含 ts 类型错误

    注意: 有时候遇到 ts 报是因为配置为生效,可以尝试重启 vscode 或 ts 服务(快捷键ctrl+shift+p调出命令行,输入Restart TS Server

3.配置路径别名

  1. 安装@types/node
pnpm add @types/node -D
  1. 修改vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path'; //引入path用到了上面安装的@types/node

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  //路径别名配置如下
  resolve: {
    alias: {
      '@': path.resolve('./src') // 用@代替src
    }
  }
});
  1. 修改tsconfig.app.json
{
	"compilerOptions":{
		...
		"baseUrl": ".", //设置基础路径
		"paths": { "@/*": ["src/*"] }, //路径映射
	}
}

4.配置 ESlint 和 Prettier

  1. 安装
//eslint import规则
pnpm add eslint-plugin-import@^2.29.1 -D
//eslint prettier插件安装
pnpm add eslint-plugin-prettier@^5.2.1 -D
//用来解决与eslint的冲突
pnpm add eslint-config-prettier@^9.1.0 -D
//安装prettier
pnpm add prettier@^3.3.3 -D
  1. 修改.eslintrc.cjs
module.exports = {
  root: true,
  env: { browser: true, es2020: true },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react-hooks/recommended',
    'plugin:prettier/recommended',
    'eslint-config-prettier'
  ],
  ignorePatterns: ['dist', '.eslintrc.cjs', 'commitlint.config.cjs'],
  parser: '@typescript-eslint/parser',
  plugins: ['react-refresh', 'import', 'prettier'],
  rules: {
    'react-refresh/only-export-components': [
      'warn',
      { allowConstantExport: true }
    ],
    //import导入顺序规则
    'import/order': [
      'error',
      {
        //按照分组顺序进行排序
        groups: [
          'builtin',
          'external',
          'parent',
          'sibling',
          'index',
          'internal',
          'object',
          'type'
        ],
        //通过路径自定义分组
        pathGroups: [
          {
            pattern: 'react*', //对含react的包进行匹配
            group: 'builtin', //将其定义为builtin模块
            position: 'before' //定义在builtin模块中的优先级
          },
          {
            pattern: '@/components/**',
            group: 'parent',
            position: 'before'
          },
          {
            pattern: '@/utils/**',
            group: 'parent',
            position: 'after'
          },
          {
            pattern: '@/apis/**',
            group: 'parent',
            position: 'after'
          }
        ],
        //将react包不进行排序,并放在前排,可以保证react包放在第一行
        pathGroupsExcludedImportTypes: ['react'],
        'newlines-between': 'always', //每个分组之间换行
        //根据字母顺序对每个组内的顺序进行排序
        alphabetize: {
          order: 'asc',
          caseInsensitive: true
        }
      }
    ],
    '@typescript-eslint/no-explicit-any': ['off'], //允许使用any
    '@typescript-eslint/no-this-alias': [
      'error',
      {
        allowedNames: ['that'] // this可用的局部变量名称
      }
    ],
    '@typescript-eslint/ban-ts-comment': 'off', //允许使用@ts-ignore
    '@typescript-eslint/no-non-null-assertion': 'off', //允许使用非空断言
    'no-console': [
      //提交时不允许有console.log
      'warn',
      {
        allow: ['warn', 'error']
      }
    ],
    'no-debugger': 'warn' //提交时不允许有debugger
  }
};
  1. 新建.prettierrc
{
	"endOfLine": "auto",
	"printWidth": 120,
	"semi": true,
	"singleQuote": true,
	"tabWidth": 2,
	"trailingComma": "all",
	"bracketSpacing": true
}
  1. 新建.prettierignore
# 忽略格式化文件 (根据项目需要自行添加)
node_modules
dist
  1. 重启 vscode 使得配置生效
  2. 配置package.json
"scripts": {
    "lint": "eslint src --fix --ext ts,tsx,js,jsx --report-unused-disable-directives --max-warnings 0",
  },

可通过pnpm lint命令,修复出现的问题。

5.配置 Tailwind

  1. 安装
pnpm install -D tailwindcss postcss autoprefixer
npx tailwindcss init
  1. 修改postcss.config.cjs内容
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {}
  }
};
  1. 修改tailwind.config.cjs内容
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,tsx}'],
  theme: {
    extend: {}
  },
  plugins: []
};
  1. 重命名index.cssmain.css,修改其内容为:
@tailwind base;
@tailwind components;
@tailwind utilities;
  1. 配置插件prettier-plugin-organize-importsprettier-plugin-tailwindcss
    • 安装
    pnpm add -D prettier-plugin-organize-imports prettier-plugin-tailwindcss
    
    • 修改.prettierrc
    module.exports = {
      endOfLine: 'auto',
      printWidth: 120,
      semi: true,
      singleQuote: true,
      tabWidth: 2,
      trailingComma: 'all',
      bracketSpacing: true,
      plugins: [
        'prettier-plugin-organize-imports',
        'prettier-plugin-tailwindcss'
      ]
    };
    

    注意:

    1. 安装插件后,需要重启 vscode 才能生效
    2. 两个插件分别针对importtailwindcss进行了优化,所以需要同时安装
    3. prettier-plugin-organize-imports项目地址: github.com/simonhaenis…
    4. prettier-plugin-tailwindcss项目地址:github.com/tailwindlab…

6.配置 Husky & lint-staged & commitlint

  1. 安装
pnpm add husky lint-staged -D
  1. 启用husky
npx husky install
  1. 修改package.json
// 设置husky prepare 命令
{
  "scripts": {
    "prepare": "husky install"
  }
}

{
	"husky": {
	    "hooks": {
	      "pre-commit": "lint-staged",
	    }
  },
  "lint-staged": {
	"src/**/*.{js,jsx,ts,tsx}": [
      "pnpm run lint",
      "prettier --write"
    ]
  },
}

  1. 修改.husky/pre-commit脚本内容
#!/usr/bin/env sh
npx --no-install lint-staged
  1. 安装commitlint
pnpm add @commitlint/cli@19.2.0 @commitlint/config-conventional@19.1.0 -D
  1. 新增配置文件.commitlintrc.js
module.exports = {
	extends: ['@commitlint/config-conventional'],
	rules: {
		'type-enum': [
			2,
			'always',
			[
				'build',
				'ci',
				'chore',
				'docs',
				'feat',
				'fix',
				'perf',
				'refactor',
				'revert',
				'style',
				'test',
				'addLog',
			],
		],
	},
};
  1. 更改commit-msg钩子
#!/usr/bin/env sh
npx --no-install commitlint --edit $1
  1. 修改package.json
"husky": {
		"hooks": {
			"pre-commit": "lint-staged",
			"commit-msg": "commitlint --config .commitlintrc.js -E HUSKY_GIT_PARAMS"
		}
	},
  1. 配置可视化提交提示
// 安装
pnpm add commitizen cz-conventional-changelog -D
// 配置 package.json
"config":{
    "commitizen":{
        "path":"node_modules/cz-conventional-changelog"
    }
}

"scripts":{
    commit:"git-cz"
}

7.配置环境变量

  1. 新建文件 新建.env文件,配置环境变量,在所有环境中生效; 新建.env.development文件,配置开发环境变量,仅在开发环境中生效; 新建.env.production文件,配置生产环境变量,仅在生产环境中生效;
  2. 定义变量
// 注: 定义的变量必须以VITE_开头
VITE_BASE_URL = //接口地址
  1. 使用变量
const baseUrl = import.meta.env.VITE_BASE_URL;
  1. vite.config.ts中使用环境变量
// 使用loadEnv方法加载环境变量
import { defineConfig, loadEnv } from 'vite';
//...

export default ({ mode }) => {
  console.log('加载的环境变量', loadEnv(mode, process.cwd()).VITE_BASE_URL);
  return defineConfig({
    //...
  });
};
  1. 修改package.json启动命令
  "scripts": {
    "dev": "vite --mode development",
    "build": "vite build --mode production",
  },

8.最后

学习总结了一下:
# 【前端工程化】项目搭建篇-项目初始化&prettier、eslint、stylelint、lint-staged、husky
# Vite5.3+Typescript+React18+Zustand 最新搭建企业级前端项目

文章如有不对或者优化的地方,欢迎大家在评论区留言!