【前端工程化】Nextjs项目工程化最佳实践总结（献给2023-1024的礼物）

时间已经是2023年了，马上也2024年了，自己去Web3世界闯荡已经一年多了。记得两年前在写文章的时候，发现自己对新领域的狂热在减弱，但是经过在新领域的锤炼，仿佛换起来自己的新狂热程度。时过境迁，React十周年了，Nextjs v13发布也一年了，App Dir（App router）模式的出现，对于自己的吸引力非常大，刚出没多久就在研究和完善相关的工程化，而今经过在企业化项目的实践里，已经锤炼出了一套自认为可以使用的Starter和经验积累。正值1024节，特为大家献上一片总结！

可以配合我总结并且近期也更新的一个starter项目进行理解哟：nextjs-web3-starter

Nextjs介绍和它自v13版本的技术的改进

Nextjs是一个React的元框架

Nextjs在我的印象里是SSR框架，最初使用v12时，了解其SSG概念。之后深入了解，是一个很不错的全干元框架。2022年v13版本发布，beta版本出来的App Dir，当时是这样叫它的，后来定义为APP Router。这种结合React Server Components范式和React Suspense，让人着迷。当时beta版就开始研究并且引入到正式项目里。后来Turbopack的出现，更让人兴奋，但初时由于Turbopack不够完善，许多包都没法兼容，后来提Issue，改包引用或者自己手撸代码造轮子替代，最后剩下的老大难aws的sdk无法兼容也被手撸代码替代了，最后Nextjsv13+Turbopack，开发体验非常爽！如果遇见不兼容Turbopack的包，建议沉下心手撸替代或者是提交PR。

React Server Components

React Server Components（简称RSC）是一种全新范例的名称，我们可以创建专门在服务器上运行的组件。这使我们能够在 React 组件中执行诸如编写数据库查询之类的操作。传统的react组件被叫做client组件，在RSC上，默认情况下所有组件都被假定为服务器组件。当然服务器组件更多需要结合编译工具才能发挥它的特性，所以Nextjs天生适合做这一块东西。可以结合这两篇文章去了解RSC和Nextjs是如何做的：Making Sense of React Server Components / Nextjs Server Components。

在处理RSC的时候，最让人困惑的应该就是它的边界状态问题了，应该不少小伙伴第一次来看这个RSC的时候，都会产生疑惑，Server和Client组件嵌套后的是否会重新渲染问题，状态变量如何保存和变更等等。当然请注意，React有这些规则：客户端组件无法渲染服务器组件，服务器组件永远不会重新渲染。所以有状态的hooks是在client组件里进使用的。在server组件里，无法使用useEffect和useStae等。Server组件传递的props也是不变的。

但是当涉及到这种边界时，父子组件的关系就不那么重要了，可以通过父子组件来进行拆分和处理状态量。我们来看看Nextjs是怎么做的：Nextjs结合Suspense，服务器组件呈现为一种特殊的数据格式，叫做React 服务器组件有效负载（简称RSC Payload），然后结合Client JavaScript指令在服务器组合成Html。

self.__next['$1024'] = {
  type: 'p',
  props: null,
  children: "Hello world!",
};

然后在客户端：HTML用于初始页面加载，然后RSC Payload协调客户端和服务器组件树，并更新 DOM，JavaScript指令用于水合客户端组件并使应用程序具有交互性。结合Streaming流式传输，性能优化明显，服务器组件不包含在我们的JS包中，这减少了需要下载的JavaScript数量以及需要水合的组件数量，大大提升了性能和加载速度！

Nextjs工程化技术栈和架构

了解了Nextjs v13+的新特性，我们来聊聊Nextjs工程化的一些事吧。

Nextjs工程化技术栈

大致可以根据传统的工程化领域划分为如下：

• 编程语言：TypeScript 5.x
• 构建工具：Nextjs Turbpack + Webpack
• 前端框架：Nextjs
• 路由工具：Nextjs文件路由
• 状态管理：React Context
• CSS：Tailwindcss+ Postcss
• HTTP 工具：Fetch
• 国际化：Nextjs Middleware + intl-localematcher + negotiator
• 多环境：ENV Config
• 数据库ORM：Prisma
• Git Hook 工具：Husky + Lint-staged
• 代码规范：EditorConfig + Prettier + ESLint
• 提交规范：Commitlint

Nextjs工程化目录结构

Nextjs 工程化的一些其他细节

关于API请求

这里使用了fetch进行请求，服务端请求和客户端请求保持了一致性。

// server端
import { cookies } from 'next/headers';

export const nextFetchGet = async (api: string) => {
  const nextCookies = cookies();
  const token = nextCookies.get('token') || '';
  const role = nextCookies.get('role');
  const roleId = nextCookies.get('roleId');
  const url =
    `${process.env.BASE_FETCH_URL}/api/be${api}`;
  const res = await fetch(url, {
    headers: token ? { Authorization: 'Bearer ' + token } : {}
  });
  if (!res.ok) {
    throw new Error('Failed to fetch data');
  }
  return res.json();
};

// client端参考
import { getCookie } from './cookie';
import { getApiUrl } from './helpers';

interface RequestOptions extends RequestInit {
  responseType?:
    | 'TEXT'
    | 'JSON'
    | 'BLOB'
    | 'ARRAYBUFFER'
    | 'text'
    | 'json'
    | 'blob'
    | 'arraybuffer';
  body?: any;
}

// 发送数据请求
const request = async (url: string, config?: RequestOptions) => {
  const finalUrl: string = getApiUrl(url);

  const inital: RequestOptions = {
    method: 'GET',
    body: null,
    headers: {
      'Content-Type': 'application/json',
      Authorization: getCookie('token') ? 'Bearer ' + getCookie('token') : ''
    },
    credentials: 'include',
    cache: 'no-cache',
    mode: 'cors',
    responseType: 'JSON'
  };

  const configs: RequestOptions = {
    ...inital,
    ...config
  };
  if (config && config.headers)
    configs.headers = {
      ...inital.headers,
      Authorization: getCookie('token') ? 'Bearer ' + getCookie('token') : '',
      ...config.headers
    };

  // 基于fetch请求数据
  const finalConfig: RequestInit = {
    method: configs.method?.toUpperCase(),
    credentials: configs.credentials,
    mode: configs.mode,
    cache: configs.cache,
    headers: configs.headers,
    body: configs.body
  };

  return fetch(`${finalUrl}`, finalConfig)
    .then((response: Response) => {
      // 走到这边不一定是成功的：
      // Fetch的特点的是，只要服务器有返回结果，不论状态码是多少，它都认为是成功
      const { status } = response;

      if (status >= 200 && status < 400) {
        // 真正成功获取数据
        let result: any;
        switch (configs.responseType && configs.responseType.toUpperCase()) {
          case 'TEXT':
            result = response.text();
            break;
          case 'JSON':
            result = response.json();
            break;
          case 'BLOB':
            result = response.blob();
            break;
          case 'ARRAYBUFFER':
            result = response.arrayBuffer();
            break;
          default:
            result = response.json();
        }
        return result;
      }
      // 失败的处理
      return Promise.reject(response);
    })
    .catch((reason: any) => {
      // @2:断网
      if (typeof window !== 'undefined' && navigator && !navigator.onLine) {
        console.log('Your network is break!');
      }
      // @1:状态码失败
      if (reason && reason.status) {
        switch (reason.status) {
          case 400:
            console.log('Please verify your info!');
            break;
          case 401:
            console.log('Please Login!');
            break;
          case 403:
            console.log('You have no access to this');
            break;
          case 500:
            console.log("Oops, there's something wrong!");
            break;
          case 504:
            console.log("Oops, there's something wrong!");
            break;
          default:
        }
      } else {
        // @3:处理返回数据格式失败
        console.log("Oops, there's something wrong!");
      }

      return Promise.reject(reason);
    });
};

export default request;

关于代理API问题

这里看自己需要，如果Nextjs的资源不及后端接口，还是不建议直接代理所有接口，只需要编写服务器组件所需要的接口代理就行了。如果需要全局代理后端接口，可以使用rewrites的方式，不建议使用以前proxy包的方式了：

const nextConfig = {
  rewrites: () => {
    return [
      {
        // 注意，加了一个be/，为什么？为了区分我们项目写的接口，避免被代理进去了。我们只需要代理外部的接口
        // Note that a be/ is added, why? In order to distinguish the interface written by our project, avoid being proxied. We only need to proxy the external interface
        source: '/api/be/:slug*',
        destination: `${process.env.BACKEND_URL}/api/:slug*`
      }
    ];
  }
};

Nextjs 国际化

使用了Nextjs中间件模式和intl-localematcher + negotiator进行国际化处理的，由于nextjs版本的更新导致输出的结构变化，所以中间件随着版本更新需要进行维护，如果在生产上版本更新需要注意，最新版中间件如下：

pnpm add @formatjs/intl-localematcher negotiator

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

import { i18n } from '@/i18n/config';

import { match as matchLocale } from '@formatjs/intl-localematcher';
import Negotiator from 'negotiator';

function getLocale(request: NextRequest): string | undefined {
  // Negotiator expects plain object so we need to transform headers
  const negotiatorHeaders: Record<string, string> = {};
  request.headers.forEach((value, key) => (negotiatorHeaders[key] = value));

  // Use negotiator and intl-localematcher to get best locale
  const languages = new Negotiator({ headers: negotiatorHeaders }).languages();
  const locales: string[] = i18n.locales as unknown as string[];
  return matchLocale(languages, locales, i18n.defaultLocale);
}

export function middleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname;

  // Check if there is any supported locale in the pathname
  const pathnameIsMissingLocale = i18n.locales.every(
    (locale) => !pathname.startsWith(`/${locale}/`) && pathname !== `/${locale}`
  );

  // Redirect if there is no locale
  if (pathnameIsMissingLocale) {
    const locale = getLocale(request);

    // e.g. incoming request is /products
    // The new URL is now /en-US/products
    return NextResponse.redirect(
      new URL(`/${locale}${pathname === '' ? '/' : pathname}`, request.url)
    );
  }
}

export const config = {
  // 2023-8-28 update
  matcher: '/((?!api|static|.*\\..*|_next).*)'
};

我们配置获取语言和数据，目前由于Turbopack的一些bug，导致需要使用如下方式引用json：

// getDictionary.ts
import 'server-only';
import type { Locale } from './config';
import enJson from '@/i18n/locales/en.json' assert { type: 'json' };
import zhCNJson from '@/i18n/locales/zh-CN.json' assert { type: 'json' };

// We enumerate all dictionaries here for better linting and typescript support
// We also get the default import for cleaner types
const dictionaries = {
  en: () => enJson,
  'zh-CN': () => zhCNJson
  // https://github.com/vercel/next.js/issues/47595
  // en: () =>
  // import('@/i18n/locales/en.json', { assert: { type: 'json' } }).then(
  //   (module) => module.default
  // ),
  // 'zh-CN': () =>
  //   import('@/i18n/locales/zh-CN.json', { assert: { type: 'json' } }).then(
  //     (module) => module.default
  //   )
};

export const getDictionary = async (locale: Locale) => dictionaries[locale]();

// config.ts
export const i18n = {
  defaultLocale: 'en',
  locales: ['en', 'zh-CN']
} as const;

export type Locale = (typeof i18n)['locales'][number];

Nextjs PWA

参考目前市面上的Nextjs PWA插件，目前采取了@ducanh2912/next-pwa，需要修改next.config.js，参考如下，具体细节和定义可以看包文档：

// next.config.js
// eslint-disable-next-line @typescript-eslint/no-var-requires
const withPWA = require('@ducanh2912/next-pwa').default({
  dest: 'public',
  cacheOnFrontEndNav: true,
  aggressiveFrontEndNavCaching: true
});

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};

module.exports = withPWA(nextConfig);

请注意，需要在public目录配置mainfest.json

同时layout.tsx记得引入mainfest.json

import { Metadata } from 'next';

export async function generateMetadata(): Promise<Metadata> {
  return {
    ...DefaultMetadata,
    title: 'Create Next App',
    description: 'Generated by create next app',
    applicationName: 'vadxq',
    manifest: '/mainfest.json',
    themeColor: '#FFFFFF',
    appleWebApp: {
      capable: true,
      statusBarStyle: 'default',
      title: 'vadxq'
    },
    formatDetection: {
      telephone: false
    },
    icons: {
      shortcut: '/favicon.ico',
      apple: [{ url: '/favicon.ico', sizes: '180x180' }]
    }
  };
}

对了，会自动生成一堆文件在public目录下，本地开发的话建议将这些添加到gitignore下：

public/sw.js
public/swe-worker-*
public/workbox-*

关于Nextjs环境区分变量

这里建立使用env环境变量来控制，同时增加本地.env.local配置，进行gitignore忽略，这样大家可以愉快的修改配置文件调试。

关于Nextjs包引入优化

近期Nextjs v13.5+版本更新了，更新了一部分Nextjs配置，在experimental配置项中，增加了optimizePackageImports配置，可以进行包优化！同时更新优化了性能，可以查看此文阅读最新信息Next.js 13.5

关于Nextjs的全局变量

可以使用React的createContext提供，然后通过父子组件嵌套，使其在Client端水合产生作用。这里提供一份代码，用于触发路由进行loading加载进度条的demo，供参考：

// state.ts
'use client';

import { createContext } from 'react';

const StartRouterChangeContext = createContext<() => void>(() => {});

export default StartRouterChangeContext;

// link.tsx
'use client';

import Link from 'next/link';
import { useContext } from 'react';
import StartRouterChange from './state';

export default function LayoutLink({
  href,
  style,
  children,
  className
}: React.ComponentProps<'a'>) {
  const startChange = useContext(StartRouterChange);
  const useLink = href && href.startsWith('/');
  if (useLink)
    return (
      <Link
        href={href}
        className={className}
        onClick={() => {
          const { pathname, search, hash } = window.location;
          if (href !== pathname + search + hash) startChange();
        }}
        style={style}
      >
        {children}
      </Link>
    );
  return (
    <a href={href} style={style} className={className}>
      {children}
    </a>
  );
}

// index.tsx
'use client';

import { useCallback, useEffect, useState } from 'react';
import { usePathname, useSearchParams } from 'next/navigation';
import NProgress from 'nprogress';
import StartRouterChangeContext from './state';

function RouterEventWrapper({
  onStart = () => null,
  onComplete = () => null,
  children
}: React.PropsWithChildren<{ onStart?: () => void; onComplete?: () => void }>) {
  const [isChanging, setIsChanging] = useState(false);
  const pathname = usePathname();
  const searchParams = useSearchParams();
  useEffect(() => setIsChanging(false), [pathname, searchParams]);

  useEffect(() => {
    if (isChanging) onStart();
    else onComplete();
  }, [isChanging]);

  return (
    <StartRouterChangeContext.Provider value={() => setIsChanging(true)}>
      {children}
    </StartRouterChangeContext.Provider>
  );
}

export default function RootLayout({ children }: React.PropsWithChildren) {
  const onStart = useCallback(() => NProgress.start(), []);
  const onComplete = useCallback(() => NProgress.done(), []);
  return (
    <RouterEventWrapper onStart={onStart} onComplete={onComplete}>
      {children}
    </RouterEventWrapper>
  );
}

关于日志收集

目前有vercel的日志收集和第三方的Sentry。

Sentry直接使用Sentry提供的插件即可。

关于Nextjs操作数据库

我的starter提供了Prisma的调用案例，当然注释了，需要进行以下操作：

• 安装依赖

pnpm add @prisma/client
pnpm add -D prisma

"script": {
  "prisma:push": "npx prisma db push",
  "prisma:generate": "npx prisma generate",
}

• next.config.js

experimental: {
  serverComponentsExternalPackages: ['@prisma/client'] // prisma support
},

• prisma文件目录

// prisma/index.ts
import { PrismaClient } from '@prisma/client';

// PrismaClient is attached to the `global` object in development to prevent
// exhausting your database connection limit.
//
// Learn more:
// https://pris.ly/d/help/next-js-best-practices

const globalForPrisma = global as unknown as { prisma: PrismaClient };

export const prisma = globalForPrisma.prisma || new PrismaClient();

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

export default prisma;

// prisma/schema.prisma
// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

model Post {
  id        String      @id @default(cuid())
  title     String
  content   String?     @db.LongText
  published Boolean     @default(false)
  comments  Comment[]
  @@map(name: "posts")
}

model Comment {
  id        String      @id @default(cuid())
  content   String?
  post      Post?       @relation(fields: [postId], references: [id])
  postId    String?
  published Boolean     @default(false)
}

然后就可以愉快的使用了Prisma orm进行操作数据库啦！其他细节可以查看Prisma文档！

关于 Nextjs持续集成和部署

Nextjs部署最佳方式也许就是Vercel了。但是各大云服务平台也可以，包括AWS在内对于Nextjs进行了优化，访问速度非常不错。

如果是个人项目或者是付费团队项目可以直接使用vercel进行部署。如果是想使用自己的Action或者是自己的部署平台进行部署上传到vercel，以下提供一个action yaml仅供参考：

# VERCEL_ORG_ID就是vercel的组织ID，VERCEL_PROJECT_ID就是vercel的这个项目的ID，VERCEL_TOKEN就是Vercel的api token
name: Production Deployment

env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Install Vercel CLI
        run: npm install --global vercel@canary
      - uses: pnpm/action-setup@v2
        with:
          version: latest
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'
      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

限制pnpm工具

// pacakge.json
"scripts": {
  "preinstall": "npx only-allow pnpm",
}

关于Husky/lint-staged

配置在提交代码前进行代码检测是非常重要的！

# 安装husky和lint-staged
pnpm add -D husky lint-staged pretty-quick

配置检测，在根目录下的.husky下需要配置命令，可以参考demo

// pacakge.json
"scripts": {
  "prepare": "husky install",
  "lint:lint-staged": "lint-staged -c ./.husky/lintstagedrc.js",
  "lint:pretty": "pretty-quick --staged",
  "lint": "pnpm lint:lint-staged && pnpm lint:pretty",
}

.husky目录下文件

• lintstagedrc.js

module.exports = {
  '*.{js,jsx,ts,tsx}': ['eslint --fix', 'prettier --write'],
  '{!(package)*.json}': ['prettier --write--parser json'],
  'package.json': ['prettier --write'],
  '*.vue': ['eslint --fix', 'prettier --write', 'stylelint --fix'],
  '*.{vue,css,scss,postcss,less}': ['stylelint --fix', 'prettier --write'],
  '*.md': ['prettier --write']
};

• pre-commit

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
. "$(dirname "$0")/common.sh"

[ -n "$CI" ] && exit 0

# Format and submit code according to lintstagedrc.js configuration
npm run lint:lint-staged

npm run lint:pretty

• common.sh

#!/bin/sh
command_exists () {
  command -v "$1" >/dev/null 2>&1
}

# Workaround for Windows 10, Git Bash and Pnpm
if command_exists winpty && test -t 1; then
  exec < /dev/tty
fi

关于配置commitlint检测

使用了@commitlint/cli和@commitlint/config-conventional，配置文件为：commitlint.config.js，

# 添加包以来
pnpm add -D @commitlint/cli @commitlint/config-conventional

module.exports = {
  ignores: [(commit) => commit.includes('init')],
  extends: ['@commitlint/config-conventional'],
  rules: {
    'body-leading-blank': [2, 'always'],
    'footer-leading-blank': [1, 'always'],
    'header-max-length': [2, 'always', 108],
    'subject-empty': [2, 'never'],
    'type-empty': [2, 'never'],
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'perf',
        'style',
        'docs',
        'test',
        'refactor',
        'build',
        'ci',
        'chore',
        'revert',
        'wip',
        'workflow',
        'types',
        'release'
      ]
    ]
  }
};

然后结合husky配置进行检测，配置文件为commit-msg：

#!/bin/sh

# shellcheck source=./_/husky.sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install commitlint --edit "$1"

生成commit log文件

使用了conventional-changelog和@commitlint/cli然后使用生成log文件

// pacakge.json
"scripts": {
  "log": "npx conventional-changelog --config ./node_modules/@commitlint/cli -i CHANGELOG.md -s -r 0"
}

总结

好了，这次的总结就到此结束了。Nextjs在正式项目上，几乎毫无压力，工程化的沉淀也差不多就这样啦，具体的业务表现就自由发挥啦。

今天是2023年的1024～在此祝所有程序员节日快乐～我们的狂欢🎉！献给2023-1024的礼物！

by: vadxq

2023.10.24 shanghai

参考文章：
[1] https://www.joshwcomeau.com/react/server-components
[2] https://nextjs.org/docs/app/building-your-application/rendering/server-components