├── .gitignore
├── site
    ├── articles
    │   ├── explore
    │   │   ├── README.md
    │   │   ├── javascript-toolchain-rome.md
    │   │   └── create-react-app-intro.md
    │   └── blitzjs
    │   │   ├── README.md
    │   │   ├── blitz-introduction-2.md
    │   │   └── blitz-introduction-1.md
    ├── TIMELINE.md
    ├── README.md
    └── index.tsx
├── mod.ts
├── deps.ts
├── README.md
├── .github
    └── workflows
    │   └── gh-pages.yml
├── pagic.config.tsx
└── LICENSE


/.gitignore:
--------------------------------------------------------------------------------
1 | dist/*


--------------------------------------------------------------------------------
/site/articles/explore/README.md:
--------------------------------------------------------------------------------
1 | # 探索篇
2 | 


--------------------------------------------------------------------------------
/mod.ts:
--------------------------------------------------------------------------------
1 | export { React } from './deps.ts'
2 | 


--------------------------------------------------------------------------------
/site/articles/blitzjs/README.md:
--------------------------------------------------------------------------------
1 | # Blitz.js 篇
2 | 


--------------------------------------------------------------------------------
/deps.ts:
--------------------------------------------------------------------------------
1 | import * as React from 'https://esm.sh/react@18.2.0'
2 | 
3 | export { React }
4 | 


--------------------------------------------------------------------------------
/site/TIMELINE.md:
--------------------------------------------------------------------------------
 1 | # 开发日志
 2 | 
 3 | ## 2024-01-01
 4 | 
 5 | * 正式以 nextjs-tutorial 为中心开启 2024 博文分享和探索
 6 | 
 7 | ## 2021-03-23
 8 | 
 9 | * 初始化仓库，使用 Pagic v1.2.0 和 Deno v1.8.0 构建
10 | * 从《Deno 钻研之术》仓库中迁移之前的 React 相关文章到这里
11 | * 发布第一篇 Blitz.js 文章
12 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Next.js 全栈开发手册
 2 | 
 3 | > 前身命名曾为 fullstack-react & blitzjs-tutorial.js
 4 | > 目前 Next.js 已经非常成熟，Blitz 也全力拥抱 Next.js
 5 | > 因此集中到 Next.js tutorial 中即可
 6 | 
 7 | 2024 年再启动。
 8 | 
 9 | ## 历史博文
10 | 
11 | |序号|文章名|发布时间|备注|
12 | |2021-03-23|[Blitz.js 入门教程：基于 Next.js 的下一代 React 全栈框架](https://blitzjs-tutorial.js.org/articles/blitz/blitzjs-introduction.html)||
13 | |2020-04-10|[欲取代绝大多 JavaScript 工具链？Rome 尝鲜](https://deno-tutorial.js.org/articles/explore/javascript-toolchain-rome.html)||
14 | |2020-01-10|[深入浅出 Create React App](https://deno-tutorial.js.org/articles/explore/create-react-app-intro.html)||
15 | |...|...|...|...|
16 | 
17 | ## 订阅
18 | 
19 | 本项目文档内容均采用 [CC-BY-SA-4.0] 协议进行共享，欢迎 Star, Watch 本仓库。
20 | 


--------------------------------------------------------------------------------
/site/README.md:
--------------------------------------------------------------------------------
 1 | # Next.js 全栈开发手册
 2 | 
 3 | > 前身命名曾为 fullstack-react & blitzjs-tutorial.js
 4 | > 目前 Next.js 已经非常成熟，Blitz 也全力拥抱 Next.js
 5 | > 因此集中到 Next.js tutorial 中即可
 6 | 
 7 | 2024 年再启动。
 8 | 
 9 | ## 历史博文
10 | 
11 | |序号|文章名|发布时间|备注|
12 | |2021-03-23|[Blitz.js 入门教程：基于 Next.js 的下一代 React 全栈框架](https://blitzjs-tutorial.js.org/articles/blitz/blitzjs-introduction.html)||
13 | |2020-04-10|[欲取代绝大多 JavaScript 工具链？Rome 尝鲜](https://deno-tutorial.js.org/articles/explore/javascript-toolchain-rome.html)||
14 | |2020-01-10|[深入浅出 Create React App](https://deno-tutorial.js.org/articles/explore/create-react-app-intro.html)||
15 | |...|...|...|...|
16 | 
17 | ## 订阅
18 | 
19 | 本项目文档内容均采用 [CC-BY-SA-4.0] 协议进行共享，欢迎 Star, Watch 本仓库。
20 | 


--------------------------------------------------------------------------------
/.github/workflows/gh-pages.yml:
--------------------------------------------------------------------------------
 1 | name: gh-pages
 2 | 
 3 | on: [push, pull_request]
 4 | 
 5 | jobs:
 6 |   build-and-deploy:
 7 |     runs-on: ubuntu-18.04
 8 |     steps:
 9 |       - uses: actions/checkout@v2
10 | 
11 |       - name: Build
12 |         env:
13 |           DENO_INSTALL: /home/runner/.deno
14 |         run: |
15 |           curl -fsSL https://deno.land/x/install/install.sh | sh
16 |           export PATH="$DENO_INSTALL/bin:$PATH"
17 |           deno --version
18 |           deno upgrade --version 1.8.0
19 |           deno install --unstable --allow-env --allow-read --allow-write --allow-net --allow-run -n pagic https://deno.land/x/pagic@v1.2.0/mod.ts
20 |           pagic build
21 | 
22 |       - name: Deploy
23 |         if: github.ref == 'refs/heads/main' && github.event_name == 'push'
24 |         env:
25 |           GA_ID: UA-169223577-1
26 |         uses: peaceiris/actions-gh-pages@v3
27 |         with:
28 |           github_token: ${{ secrets.GITHUB_TOKEN }}
29 |           publish_dir: ./dist
30 |           cname: blitzjs-tutorial.js.org
31 | 


--------------------------------------------------------------------------------
/pagic.config.tsx:
--------------------------------------------------------------------------------
 1 | import * as React from 'https://esm.sh/react@18.2.0'
 2 | 
 3 | export default {
 4 |   srcDir: 'site',
 5 |   theme: 'docs',
 6 |   plugins: ['sidebar', 'prev_next'],
 7 |   title: 'Blitz.js + React 全栈开发手册',
 8 |   description: 'Blitz + React 全栈开发手册，构建下一代 React 全栈应用',
 9 |   github: 'https://github.com/hylerrix/blitzjs-tutorial',
10 |   head: (<link rel="icon" type="image/png" href="/favicon.png" />),
11 |   nav: [
12 |     { text: '文章', link: '/articles/' },
13 |     {
14 |       text: '打赏一下!!',
15 |       link: 'http://qiniu.ningo.cloud/hylerrix/reward-alipay.png',
16 |       target: '_blank',
17 |       popover: (
18 |         <>
19 |           <img src="http://qiniu.ningo.cloud/hylerrix/reward-alipay.png" width="256" style={{ marginRight: '1rem', verticalAlign: 'top' }} />
20 |           <img src="http://qiniu.ningo.cloud/hylerrix/reward-wechat.png" width="256" style={{ verticalAlign: 'top' }} />
21 |         </>
22 |       )
23 |     },
24 |     { text: 'Deno 钻研之术', target: '_blank', link: 'https://github.com/hylerrix/deno-tutorial' },
25 |     { text: 'Deno 算法之旅', target: '_blank', link: 'https://github.com/hylerrix/deno-algorithm' },
26 |     { text: 'Blitz.js', target: '_blank', link: 'https://blitzjs.com/' },
27 |     { text: '持续添加中...', target: '_blank', link: 'https://github.com/hylerrix' },
28 |     {
29 |       text: '凝果屋',
30 |       link: 'https://github.com/ningowood',
31 |       target: '_blank',
32 |       popover: (
33 |         <img src="http://qiniu.ningo.cloud/ningo/official-qrcode.png" width="256" style={{ verticalAlign: 'top' }} />
34 |       )
35 |     },
36 |     { text: '关于', target: '_blank', link: 'https://github.com/hylerrix' },
37 |   ],
38 |   sidebar: {
39 |     '/articles/': [
40 |       'articles/README.md',
41 |       {
42 |         link: 'articles/blitz/README.md',
43 |         title: 'Blitz.js 篇',
44 |         children: [
45 |           'articles/blitz/blitz-introduction-1.md',
46 |           'articles/blitz/blitz-introduction-2.md',
47 |         ],
48 |       },
49 |       {
50 |         link: 'articles/blitz/README.md',
51 |         title: '探索篇',
52 |         children: [
53 |           'articles/explore/create-react-app-intro.md',
54 |           'articles/explore/javascript-toolchain-rome.md',
55 |         ],
56 |       },
57 |       // 'articles/THANKS.md',
58 |     ],
59 |   },
60 |   tools: {
61 |     editOnGithub: true,
62 |     backToTop: true
63 |   },
64 |   port: 8011
65 | }
66 | 


--------------------------------------------------------------------------------
/site/index.tsx:
--------------------------------------------------------------------------------
  1 | import { React } from '../mod.ts'
  2 | 
  3 | const style = `
  4 | h2 {
  5 |   font-weight: normal;
  6 | }
  7 | .main_article {
  8 |   width: 960px;
  9 |   max-width: 960px;
 10 |   padding-bottom: 0;
 11 | }
 12 | .cards {
 13 |   display: flex;
 14 |   justify-content: center;
 15 |   margin: 3rem -1rem 0 -1rem;
 16 |   padding-top: 1rem;
 17 |   border-top: 1px solid var(--color-border);
 18 | }
 19 | .cards > div {
 20 |   width: 20rem;
 21 |   padding: 0 1rem;
 22 | }
 23 | .cards ul {
 24 |   color: var(--color-text-muted);
 25 | }
 26 | .btn {
 27 |   padding: 0.5rem 1rem;
 28 |   margin: 0 1rem;
 29 |   border: 0;
 30 |   cursor: pointer;
 31 |   opacity: 0.9;
 32 |   font-size: 14px;
 33 |   text-decoration: none;
 34 |   background-color: var(--color-border);
 35 |   color: var(--color-text);
 36 | }
 37 | .btn:hover {
 38 |   text-decoration: none;
 39 | }
 40 | .btn-primary {
 41 |   background-color: var(--color-primary);
 42 |   color: var(--color-background);
 43 | }
 44 | .btn:hover {
 45 |   opacity: 1;
 46 | }
 47 | @media screen and (max-width: 44rem) {
 48 |   h2 {
 49 |     text-align: center;
 50 |   }
 51 |   .cards {
 52 |     flex-direction: column;
 53 |   }
 54 |   .cards > div {
 55 |     width: 100vw;
 56 |   }
 57 |   .cards ul {
 58 |     text-align: center;
 59 |     padding-left: 0;
 60 |     list-style: none;
 61 |   }
 62 |   pre {
 63 |     margin-left: -1rem;
 64 |     margin-right: -1rem;
 65 |   }
 66 | }
 67 | `
 68 | 
 69 | const IndexPage = () => (
 70 |   <>
 71 |     <div>
 72 |       <style dangerouslySetInnerHTML={{ __html: style }} />
 73 |       <h1
 74 |         style={{
 75 |           marginTop: '3.5rem',
 76 |           textAlign: 'center',
 77 |           fontSize: '64px',
 78 |           color: 'hsl(210, 70%, 50%)'
 79 |         }}
 80 |       >
 81 |         Blitz.js + React 全栈开发手册
 82 |       </h1>
 83 |       <p
 84 |         style={{
 85 |           fontSize: '28px',
 86 |           marginTop: '2rem',
 87 |           textAlign: 'center',
 88 |           color: 'var(--color-text-muted)'
 89 |         }}
 90 |       >
 91 |         Blitz + React 全栈开发手册，构建下一代 React 全栈应用
 92 |       </p>
 93 |       <div
 94 |         style={{
 95 |           display: 'flex',
 96 |           justifyContent: 'center',
 97 |           marginTop: '2rem'
 98 |         }}
 99 |       >
100 |         <a className="btn btn-primary" href="/articles/">
101 |           开始阅读
102 |         </a>
103 |         <a className="btn" target="_blank" href="https://github.com/hylerrix/blitzjs-tutorial">
104 |           源码仓库
105 |         </a>
106 |       </div>
107 |     </div>
108 |     <div className="cards">
109 |       <div>
110 |         <h2>原创文章</h2>
111 |         <ul>
112 |           <li>融合了笔者的大量思考。</li>
113 |           <li>本书、笔者和读者一起成长。</li>
114 |           <li>友好的交流环境。</li>
115 |         </ul>
116 |       </div>
117 |       <div>
118 |         <h2>内容丰富</h2>
119 |         <ul>
120 |           <li>从多方位建设 <code>Blitz.js</code> 生态。</li>
121 |           <li>
122 |             内容包括但不局限于 <code>Blitz.js</code> <code>React</code> <code>FullStack</code> 等众多技术要点。
123 |           </li>
124 |           <li>收录各种翻译文章、授权转载文章。</li>
125 |         </ul>
126 |       </div>
127 |       <div>
128 |         <h2>长期维护</h2>
129 |         <ul>
130 |           <li>来源于一份对持续深入地掌握前沿技术的渴望。</li>
131 |           <li>基于 <code>Pagic</code> 静态网站生成器，构建长期的网站技术支持。</li>
132 |           <li>野心，不止于此。</li>
133 |         </ul>
134 |       </div>
135 |     </div>
136 |     <h2>推荐你的 Blitz.js 文章？快来一起建设吧</h2>
137 |     <pre
138 |       style={{
139 |         fontSize: '1rem'
140 |       }}
141 |     >
142 |       <code
143 |         dangerouslySetInnerHTML={{
144 |           __html: `# 直接在 issues 区里推荐
145 | https://github.com/hylerrix/blitzjs-tutorial/issues
146 | 
147 | # 或克隆项目，本地编辑并 PR
148 | git clone https://github.com/\${YOUR_NAME}/blitzjs-tutorial
149 | git add . && git commit -s -m "feat(docs): add a new article"
150 | git push origin main`
151 |         }}
152 |       />
153 |     </pre>
154 |   </>
155 | )
156 | 
157 | export default IndexPage
158 | 


--------------------------------------------------------------------------------
/site/articles/blitzjs/blitz-introduction-2.md:
--------------------------------------------------------------------------------
  1 | # Blitz.js 一体化开发 (1.2)：与 Next.js 进行权衡
  2 | 
  3 | ## Next.js 是什么？
  4 | 
  5 | Blitz 是基于 Next.js 的，因此几乎支持 Next.js 的所有功能。有关差异的更多信息，请参见此处：[为什么是 Blitz 而非 Next.js](https://blitzjs.com/docs/why-blitz)。
  6 | 
  7 | [**Next.js**](https://nextjs.org/) 是一个流行的 React 框架，其中有很多内置功能，例如：
  8 | 
  9 | - 预渲染，每页支持静态生成 (SSG) 和服务端渲染 (SSR)。
 10 | - 自动代码拆分，可更快地加载页面。
 11 | - 客户端路由具有优化的预加载功能。
 12 | - 开发环境支持热更新。
 13 | - 完全可拓展。
 14 | 
 15 | ## 为什么是 Blitz 而非 Next.js？
 16 | 
 17 | ### 1. 全栈而非前端
 18 | 
 19 | Next.js 主要是一个前端框架。它是为构建连接到其它 API 的前端而设计的。Nex.js 并不是一个真正的、开箱即用的全栈框架。
 20 | 
 21 | Blitz 中添加了所有缺少的功能，这些功能使 Next 变成了真正的全栈框架。这些关键功能包括直接访问数据库，中间件和身份验证。
 22 | 
 23 | ### 2. 数据层
 24 | 
 25 | Blitz 的数据层是一种新颖的技术，可以再保留客户端渲染的同时消除 API。在 Blitz 应用中，你可以将服务器代码直接导入前端，因此无需构建 API 并从前端进行数据提取工作。在构建时，Blitz 自动插入一个 API 调用，该 API 调用在服务器上运行服务端代码。本质上，Blitz 将你的 API 抽象为一个编译步骤。
 26 | 
 27 | 这是 React 应用程序开发的游戏规则改变者，因为它消除了传统 React 应用程序体系结构的整个部分。这意味着更容易学习、更快开发，并且构建事务更有趣！
 28 | 
 29 | 也就是说，你可以像往常一样继续通过 REST 或 GraphQL 进行数据获取。Blitz 对此没有任何限制。
 30 | 
 31 | ### 3. 内置身份验证
 32 | 
 33 | Blitz 具有可与任何身份验证商一起使用的内置会话管理服务，包括自托管的电子邮件/密码和第三方服务。身份验证是一项复杂且难以正确实施的事情。将其内置到 Blitz 中可以为你节省大量时间和潜在的安全漏洞。
 34 | 
 35 | 在 Next.js 中使用 auth 构建令人敬畏的 UX 会非常地棘手和乏味，但是 Blitz 免费为你提供了一流的 DX。
 36 | 
 37 | ### 4. 约定
 38 | 
 39 | 除了基于文件系统的路由外，Next.js 没有任何约定。此时，每个开发人员都可以为每个项目重新发明轮子。
 40 | 
 41 | Blitz 带来了许多约定，例如如何组织文件以及如何构造路由。这意味着你不会浪费任何时间为每个项目弄清楚这一点。这也极大地造福了社区。通用的项目结构和架构模式可让你从 Blitz 应用程序迁移到 Blitz 应用程序，并立即感到宾至如归。
 42 | 
 43 | ### 5. 代码脚手架
 44 | 
 45 | 有两种主要方法可以减少你必须手工编写的代码量：
 46 | 
 47 | 1. 代码生成
 48 | 1. 代码脚手架
 49 | 
 50 | **Code 生成** 意味着让库来为你生成代码。例如，可以通过 GraphQL 查询生成代码的 graphql-code-generator 和可以从你的数据库架构中生成整个 GraphQL API 的 Hasura。通常，codegen 无法完全自定义生成的代码。你需要通过库来支持。同时你也会常遇到 codegen 无法解决的极端情况。而且你无法修复它，因为你不拥有该代码。
 51 | 
 52 | **Code 脚手架** 意味着初始代码将注入到你的项目之中。从那时起，你对所有代码拥有着完全的所有权，并可以根据需要进行自定义。代码脚手架的缺点是你不会像从第三方库生成的代码那也获得自动更新。但巨大的好处在于其可以确保你永远不会受到别人无法改变的设计选择的限制。
 53 | 
 54 | Blitz 是代码脚手架的忠实拥护者。我们有大量的 [`blitz generate`](https://www.yuque.com/ningo/blitzjs/cli-generate) 命令，可将代码脚手架插入你的项目中。我们的代码脚手架还处于初期阶段——我们仍然需要添加许多强大的功能，包括添加自己的自定义脚手架模板的功能。
 55 | 
 56 | ### 6. 配方
 57 | 
 58 | Recipes 是用于将代码从 npm 或 git 存储库上的 MDX 配方放入你的项目中的单行命令。
 59 | 
 60 | 例如：
 61 | 
 62 | - `blitz install tailwind`——一行命令安装和配置 tailwind
 63 | - `blitz install chakra-ui`——一行命令安装和配置 chakra
 64 | - `blitz install material-ui`——一行命令安装和配置 material-ui
 65 | 
 66 | Recipes 超级强大，它们几乎可以更改项目中的任何内容，包括添加依赖项、更改代码、添加代码等。它们是通过 MDX 编写的，可以像 React 一样组成。
 67 | 
 68 | ### 7. 全新的开发环境
 69 | 
 70 | 一个新的 Next.js 应用是完全恐怖的。因此，每次你启动 Next.js 项目，你必须花费数小时来建立 eslint、petterier、husky git hooks 等的所有基础知识。
 71 | 
 72 | 一个新的 Blitz 应用可以为你节省大量时间，因为所有这些都是为你预先配置的！当然，你以后始终可以对其进行自定义，但是拥有一个可行的起点真的很棒。
 73 | 
 74 | ### 8. 放宽限制
 75 | 
 76 | Next.js 要求你所有的 React 页面都放在一个 `pages/` 文件夹中。Blitz 通过允许你拥有无限数量的 `pages/`文件夹来放宽此限制。
 77 | 
 78 | 对于大型项目，这是一个巨大的好处，因为你可以按任意方式分离和组织页面。
 79 | 
 80 | 例如：
 81 | 
 82 | - `app/pages/` 可以包含“首页”和“关于”之类的页面
 83 | - `app/products/pages/` 可以包含于产品相关的所有页面
 84 | - `app/admin/pages/` 可以包含与后端 admin 部分相关的所有页面
 85 | 
 86 | ## 权衡
 87 | 
 88 | 你应该会知道，一切都需要被权衡。那么 Blitz 需要权衡的是什么？
 89 | 
 90 | ### 框架限制
 91 | 
 92 | 每个框架都有一定程度的限制。如果你使用 React 构建应用，那么就很容易被 React 限制。
 93 | 
 94 | Blitz 的限制级别比 Next.js 高一个级别。Blitz 代码库与 Next.js 代码库没有 _太多_ 不同。但这已经够不同了，以至于“弹出”到普通的 Next.js 并不简单。例如，你可能将使用 Blitz 所特有的 Blitz 身份验证。但切换到 Next AUth 将为你提供与 Next.js 相当的体验。
 95 | 
 96 | Blitz 零 API 数据层是 Blitz 独有的。因此，如果此时切换到 Next.js，则必须管理自己的 API 代码（而如果从 Next.js 开始，则必须这么做，因此不会丢失任何内容）。但是，你所有的后端 query 和 mutation 逻辑都可以直接移植。
 97 | 
 98 | ### 升级 Next.js
 99 | 
100 | 如果你想站在 Next.js 版本的最前沿，请知道 Blitz 会稍微落后但不会太远。通常，我们会在新的 Next.js 版本发布后不到一周的时间内更新 Blitz。
101 | 
102 | 但如果你使用 yarn，则可以先使用 package.json 中的 `resolutions` 字段来升级 next.js。
103 | 
104 | ### 多客户端 API
105 | 
106 | 有人会说，“迟早你会需要 GraphQL，所以你应该从它开始”。虽然我们认为绝大多数应用程序的增长不会足够大以至于不能保证 GraphQL，但是提供多个客户端的 API 的问题是一个很好的要点。
107 | 
108 | 我们完全承认，许多 Web 应用程序迟早都需要移动应用程序。我们希望这种集成尽可能的简单！
109 | 
110 | 也就是说，你可以为其他客户端将 GraphQL 服务器添加到 Blitz 应用中，这可能是一个很好的选择，有些人已经开始这样做了。
111 | 
112 | **目前，截至 2021 年 2 月 17 日：**
113 | 
114 | - 你可以直接访问自动生成的 API 接口，并且可以在任何移动应用中使用它们（我们目前有几个人在建设中）；
115 | - 你可以通过 [`blitz routes`](https://www.yuque.com/ningo/blitzjs/cli-routes) 来查看应用程序中生成的 API；
116 | - 你可以在此处查看 API 接口的 RPC 规范：[RPC Specification](https://www.yuque.com/ningo/blitzjs/rpc-specification)。
117 | 
118 | **我们计划今后要做的事：**
119 | 
120 | 1. 第一步，添加文档和工具，以使手动使用生成的 API 接口变得更加容易，访问：[https://github.com/blitz-js/blitz/discussions/1907](https://github.com/blitz-js/blitz/discussions/1907) 和 [https://github.com/blitz-js/blitz/issues/745](https://github.com/blitz-js/blitz/issues/745)；
121 | 1. 接下来，添加生成一个 JS/TS 客户端库的功能，作为使用从应用生成接口的好方
122 | 法；
123 | 1. 还有，添加某种一流的 react-native 支持，你可以再其中将 Blitz queries/mutations 直接导入到你的 react-native 代码中，并使它神奇地工作，就像今天在你的 Web 应用程序中一样。在 1.0 版本后，这将是 Brandon 在这一年中的主要工作重点。
124 | 
125 | ### 高阶后端架构
126 | 
127 | 目前，Blitz 在后端架构上的功能还很少，尤其是与 Nest.js 或 AdonisJS 之类的
128 | 东西相比。但是，这并不意味着你不能在 Blitz 中使用这些模式，但你需要自己进
129 | 行设置。实际上，如果需要，你可以在 Blitz 应用中直接使用 Nest.js。
130 | 
131 | 但是我们非常有兴趣通过默认支持或简单的植入来加入更先进的后端体系架构到
132 | Blitz 中。我们有一个[正在进行的讨论](https://github.com/blitz-js/blitz/discussions/1841)，如果你有想法，我们希望你能加入。
133 | 
134 | ### 当不部署到 Serverless 时的单线程
135 | 
136 | 具体来说，这是 Next.js 的折衷方案。Next.js 是单线程的，这意味着如果你在进行繁重的后端处理时，你可能会发现所有的 Web 请求都开始受到影响。解决方案是让后端处理来生成其他进程。
137 | 
138 | 运行多个后台进程并不是很困难，但是我们希望添加文档和 API，以使其尽可能简单。
139 | 
140 | ## 译者结语
141 | 
142 | 本文内容属于 [Blitz.js 官方文档](https://blitzjs.com/docs) - 简介章节的后半部分。总共十四个章节（简介、社区、基础、页面、路由、权限、数据库、Queries 和 Mutations、后端架构、部署、配方、配置、CLI 和模板）。未来不定期翻译其余章节，也可能会原创一些文章。
143 | 
144 | 《[React 全栈开发手册](https://github.com/hylerrix/blitzjs-tutorial)》系列专注探索 Blitz.js + React 全栈应用开发，原文翻译内容会同步更新到 [Blitz.js 中文仓库](https://github.com/blitz-js/zh-hans.blitzjs.com) 上。欢迎 Star、Watch 或关注公众号 (@ningowood) 来及时接收消息。
145 | 
146 | > 2021 © [https://github.com/hylerrix/blitzjs-tutorial](https://github.com/hylerrix/blitzjs-tutorial)
147 | 


--------------------------------------------------------------------------------
/site/articles/explore/javascript-toolchain-rome.md:
--------------------------------------------------------------------------------
  1 | # 欲取代绝大多 JavaScript 工具链？Rome 尝鲜
  2 | 
  3 | 文章缩略图：一个包含希腊斯巴达头盔的罗马项目 Logo
  4 | 
  5 | > 条条大路通 Rome。在 Rome 还没有发布 NPM 正式版之际。我们围绕 JavaScript 工具链为核心点，来看看前往 Rome 的路上都有什么；以及 Rome 本身，意味着什么？
  6 | 
  7 | 二月的最后一天，我在为“[开源爱好者月刊](https://github.com/ningowood/open-source-magazine)”搜寻本月最新的开源项目时，偶遇一个名叫 Rome 的仓库霸榜，眼前着实一亮。“一个实验性的 JavaScript 工具链”、“包括编译器、lint、格式化程序、捆绑器、测试框架等”以及“旨在成为与 JavaScript 源码处理相关的所有功能的综合工具”短短几句话展现了一个宏大的目标。现在，是时候入坑了解一波并在个人能力范围内作一个浅要的分享。
  8 | 
  9 | Rome 由就职于 Facebook 同时是 Babel 和 Yarn 作者的 Sebastian McKenzie 主导开源，开源之前，Rome 基本是他的个人项目，现在 Facebook 愿意付薪水让他潜心开发。截止现在（2020 年 04 月初），Rome 的提交记录已经从 70+ 到 600+，贡献者拓展到了 40+ 位，产生了 30+ issues 和 170+ Pull Request。
 10 | 
 11 | Rome 的 Star 趋势图，发布之初便 3k+ star：
 12 | 
 13 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1586250919893-28d3dc40-57d9-4a99-9023-50e8c259ffbd.png#align=left&display=inline&height=323&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1176&originWidth=1678&size=111441&status=done&style=none&width=461)
 14 | 
 15 | 此外，或许也能从侧面呼应我曾在月刊第三期中收录的一句关于“创业公司和大公司开源出发点有何不同”的话：大公司可能在一个项目的早期便开源，凭借其号召力希望更多人一起“贡献”迭代，初创团队则会在产品相对成熟的时候再开放，希望尽快吸引用户深度“使用”，注重完善产品在工业环境下的综合表现。
 16 | 
 17 | 正文 & 背景 & 干货开始。
 18 | 
 19 | ## Rome：从个人项目到 Facebook 新开源
 20 | 
 21 | 从官网不难看出，Rome 旨在成为与 JavaScript 源代码处理相关的所有功能的综合工具，其中包括“编译器、Linter、格式化程序、捆绑器、依赖管理器和测试框架”等。Rome 源于对整个项目的扩展范围一致性的渴望。
 22 | 
 23 | 同时，Rome 也来源于 Babel 作者本身对 Babel 的一些不满足而新创，就像 Deno 之于 Node 一样。
 24 | 
 25 | Rome 作者 Sebastian 关于 Rome 的推文集：
 26 | 
 27 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1586507768694-82e44955-f16d-4102-9f12-a7e347583ac0.png#align=left&display=inline&height=336&margin=%5Bobject%20Object%5D&name=image.png&originHeight=846&originWidth=1180&size=135209&status=done&style=none&width=469)
 28 | 
 29 | 本节根据 README.md 和官网首页的介绍，来以问答形式展示 Rome 的背景和想要达到具体目标。
 30 | 
 31 | ### 01、Rome 的一些来源？
 32 | 
 33 | > 在计算机科学中只有两件难事：缓存失效和命名。 ——Phil Karlton
 34 | 
 35 | - 立项来源：由 Babel and Yarn 的作者 Sebastian McKenzie 发起，是 React Native 团队的一个项目。
 36 | - 名称来源：因“通向罗马的所有道路”，“罗马不是一天建成”和“在罗马时要像罗马人一样”这样的谚语而得名。 这是指整个项目的扩展范围和对一致性的渴望，它始于一个办公室玩笑。
 37 | - Logo 来源：一个古希腊斯巴达头盔。虽然它不是罗马字母，也不太相关，但看起来比 Galea （罗马士兵的头盔）酷。
 38 | 
 39 | ### 02、Rome 的编码架构？
 40 | 
 41 | > 在版本控制系统中，monorepo（单声道存储库的音节缩写）是一种软件开发策略，其中许多项目的代码存储在同一存储库中。 截至 2017 年，这种软件工程实践已有十多年的历史，但直到最近才被命名。——Monorepo，维基百科
 42 | 
 43 | - 完全使用 TypeScript 编写，很少使用松散类型。
 44 | - 支持处理 JSX 以及 Flow 和 TypeScript 代码。
 45 | - self-hosted，可以自己编译自己。
 46 | - 不是现有工具的集合，所有组件都是自定义的，不使用第三方依赖项（对 JavaScript 生态系统进行了重新思考，对整个工具链采用了不依赖第三方库的大胆实现）。
 47 | - 是带有内部软件包的 monorepo 架构以便划定代码边界。
 48 | 
 49 | ### 03、Rome 的工作展望？
 50 | 
 51 | - 旨在成为与 JavaScript 源代码处理相关的所有功能的综合工具。
 52 | - 目标是替代许多现有的 JavaScript 工具，但也将提供为其他工具提供自身的集成方案，以根据需要随意使用——例如使用 Rome 编译器作为另一个捆绑程序的插件。
 53 | - 目前关注的领域是 Linter（用于分析源代码以标记编程错误，bug，样式错误和可疑结构的工具），这是将 Rome 变成最容易使用的工具链的目标里阻力最小的一个环节。
 54 | 
 55 | ## 微栏：回看 JavaScript 工具链
 56 | 
 57 | > 在学习一个工具之前，往往我们应该先去了解这个工具可以用来解决什么样的问题；同样的，当我们遇到一个问题的时候，我们也应该带着这个问题去找工具解决。
 58 | > **——**阿里巴巴集团 高级前端工程师 叶俊星
 59 | 
 60 | 成熟的软件项目必然遵循的良好的开发规范，也拥有属于自身独特的软件开发生命周期，编程实践只占整个开发周期的很小一部分。当一个 JavaScript 软件被建立时通常还会遇到哪些需要解决的问题？这便涉及到了 JavaScript 项目的技术选型，而 JavaScript 生态圈的明星项目数不胜数，以下作一个纵览，不涉及各个工具的具体使用方式。
 61 | 
 62 | JavaScript 工具链示意图：
 63 | 
 64 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1586513611176-e3066f3f-4113-43ed-a45c-94c5307217e1.png#align=left&display=inline&height=180&margin=%5Bobject%20Object%5D&name=image.png&originHeight=360&originWidth=708&size=117163&status=done&style=none&width=354)
 65 | 
 66 | - **JS 开发环境**？有 V8、Node 甚至是 Deno 等；
 67 | - **JS 前端框架**？有 Angular、React、Vue、React Native、jQuery 等；
 68 | - **JS 后端框架**？有 Nest、Express、Koa 等；
 69 | - **JS 脚手架**？有 Vue CLI、Angular CLI、Create React App、Yeoman 等；
 70 | - **JS 转译工具**？有 Babel  等；
 71 | - **JS 测试工具**？围绕单元测试、集成测试，有 Mocha、Jasmine、Jest、Karma 等；
 72 | - **JS 调试工具**？有 Chrome DevTools/Firebug/Webkit inspector 等各大主流浏览器、VS Code/WebStorm 等各大编辑器/IDE 等；
 73 | - **JS 格式规范工具**？有 JSLint、JSHint、ESLint、TSLint 等；
 74 | - **JS 接口联调工具**？有 Axios、Fetch 等；
 75 | - **JS 包管理器**？有 NPM、Yarn、Bower、PNPM 等；
 76 | - **JS 模块加载器**？有 RequireJS、SystemJS、StealJS、ES Module Loader 等；
 77 | - **JS 任务管理工具**？Grunt、Gulp、Webpack 监听文件变化，自动执行任务；
 78 | - **JS 静态化支持**？有 TypeScript、CoffeeScript、Flow、LiveScript 等；
 79 | - **JS 代码后处理工具**？围绕混淆器、缩小器、优化器诸多领域有各种各样的 loader 等；
 80 | - **JS 打包工具**？Webpack、Rollup、Parcel、Browserify 等；
 81 | - **JS 模板引擎**？有 handlebarsjs、etpl、templatejs 甚至各大前端框架内置的模板语法等；
 82 | - **JS 非 Web 框架**？在物联网、区块链、大数据等领域均有相关库支持，本文不涉及。
 83 | - **JS 进程管理**？有 Forever、PM2、StrongLoop Process Manager 等；
 84 | - **......**？甚至编辑器、IDE、CSS 预处理器、代码托管平台、团队开发模式(纯前端、重后端、前后分离)、WebAssembly、Serverless、JS DevOps 等都可以加到项目的技术选型范围内。
 85 | 
 86 | 因此可以看出，技术选型便是针对能让项目成功运转各个环节寻找相应的解决方案；工作流（Workflow）是所有解决方案融合后的落实流程；而工具链（Toolchain）便是工作流下所有实现方式的汇总，同时一个工具也能代表一个解决方案。
 87 | 
 88 | 简而言之，JavaScript 工具链便是 JavaScript 工程师在开发过程中会用到的一系列工具。
 89 | 
 90 | ## 浅尝初试 Rome (v0.0.52)
 91 | 
 92 | 现在 Rome 并没有直接在 Github 上发布任何版本，但编译后生成的 rome.json 可以看出有一个 v0.0.52 的版本号，处于一个很早期的状态，项目简介也是“一个实验性的 JavaScript 工具链”。
 93 | 
 94 | 想要尝试 Rome，就得从以下步骤逐步展开（由于 Rome 没有发布正式版本，这里无需过多涉及如何整合在 package.json 的脚本中使用等工程化过程）。
 95 | 
 96 | 帝国时代里的罗马大军：
 97 | 
 98 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1582968932888-16752733-9ed4-49ff-a135-4b2f1d37b55a.png#align=left&display=inline&height=282&margin=%5Bobject%20Object%5D&name=image.png&originHeight=695&originWidth=1236&size=2575437&status=done&style=none&width=502)
 99 | 
100 | 本章所有 Demo 均在 [@hylerrix/demos](https://github.com/hylerrix/demos) 的 Rome 文件夹中。
101 | 
102 | ### 01、git clone rome
103 | 
104 | 既然 Rome 没有正式发布版本，我们也无法直接从 NPM 上直接安装 Rome。现阶段，Rome 提供了本地安装的方式，只需要克隆到本地并本地编译和本地 NPM 安装即可使用。
105 | 
106 | > 注：安装 Rome 前请确保本地已正常安装 Node 和 NPM
107 | 
108 | ```bash
109 | # 克隆 Rome 项目到本地
110 | $ git clone https://github.com/facebookexperimental/rome
111 | # 命令行进入 Rome 项目
112 | $ cd rome
113 | # 方式一：编译 Rome
114 | $ ./scripts/build-release dist
115 | # 方式二：编译 Rome（Windows 10 的情况下，使用 PowerShell 7）
116 | $ cd rome && node scripts/build-release dist
117 | # 安装编译后的 Rome 到本地全局环境中
118 | $ npm install -g ./dist/
119 | # 现在便可以使用 Rome 了
120 | $ rome # No command specified. Run --help to see available commands.
121 | ```
122 | 
123 | ### 02、rome init
124 | 
125 | rome init 命令会在当前目录生成一个 rome.json 文件，使用推荐配置会初始化以下内容：
126 | 
127 | ```json
128 | {
129 |   "version": "^0.0.52",
130 |   "lint": {
131 |     "enabled": true
132 |   }
133 | }
134 | ```
135 | 
136 | 该文件告诉 Rome 至少应为 0.0.52 版本，以便与当前项目一起使用。具体使用文档还在开发中。
137 | 
138 | ### 03、rome run index.ts
139 | 
140 | rome run 命令将运行传递给它的任何文件，通常与项目的主文件一起使用。目前仍在开发中，可能无法正确处理所有源文件。此时我们为测试 rome run 成功运行，建立一个 index.ts 和 api.ts 文件，如下。
141 | 
142 | ```javascript
143 | // index.ts
144 | import { getData } from './api'
145 | 
146 | async function setData () {
147 |   const { success, data } = await getData()
148 |   console.log('success:', success)
149 |   console.log('data:', data)
150 | }
151 | 
152 | await setData()
153 | 
154 | // api.ts
155 | export const getData = () => Promise.resolve({
156 |   success: true,
157 |   data: 'Hello World!'
158 | })
159 | ```
160 | 
161 | 此时，运行如下命令便可以成功使用：
162 | 
163 | ```bash
164 | $ rome run index.ts
165 | # ℹ Bundling index.ts
166 | # success: true
167 | # data: 'Hello World!'
168 | ```
169 | 
170 | ### 04、rome lint index.ts
171 | 
172 | 由于我真的不喜欢在 JavaScript 应用里面写分号，这与主流规范有些不同，所以 rome lint 命令刚好派上了用场：rome 默认需要在 JavaScript 语句结尾写分号。同时在 api.ts 中故意不导出一个 interface 且在 index.ts 中故意将其错误导入，重构后的有错误 index.ts 和 api.ts 以及 rome lint 后执行过程如下：
173 | 
174 | ```javascript
175 | // 故意错误编写的 index.ts
176 | import { getData } from './api'
177 | 
178 | async function setData() {
179 |   const {success, data} = await getData()
180 |   console.log('success:', success)
181 |   console.log('data:', data)
182 | }
183 | 
184 | await setData()
185 | 
186 | // 故意错误不导出的 api.ts
187 | interface Params {
188 |   username: string
189 |   token: string
190 | }
191 | 
192 | export const getData = (params: Params) => Promise.resolve({
193 |   success: true,
194 |   data: 'Hello World!'
195 | })
196 | ```
197 | 
198 | 
199 | ```bash
200 | $ rome lint index.ts
201 | #  index.ts lint/pendingFixes ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
202 | # 
203 | #   ✖ Pending fixes
204 | # 
205 | #      1 │ + import {getData, Params} from './api.ts';
206 | #        │ - import {·getData, Params·} from './api.ts'
207 | #      2 │   
208 | #     .. │ 
209 | #      4 │     const param: Params = {
210 | #      5 │       username: 'hylerrix',
211 | #      6 │ +     token: 'ningowood',
212 | #      7 │ +   };
213 | #      8 │ +   const {success, data} = await getData(param);
214 | #      9 │ +   console.log('success:', success);
215 | #     10 │ +   console.log('data:', data);
216 | #     11 │   }
217 | #     12 │   
218 | #     13 │ + await setData();
219 | #     14 │   
220 | # 
221 | #  index.ts:1:18 resolver/unknownExport ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
222 | # 
223 | #   ✖ Couldn't find export Params in api.ts
224 | # 
225 | #   > 1 │ import { getData, Params } from './api.ts'
226 | #       │                   ^^^^^^ 
227 | #     2 │ 
228 | #     3 │ async function setData() {
229 | # 
230 | #   ℹ However we found a matching local variable in api.ts. Did you forget to export it?
231 | # 
232 | #   > 1 │ interface Params {
233 | #       │           ^^^^^^ 
234 | #     2 │   username: string
235 | #     3 │   token: string
236 | # 
237 | # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
238 | # 
239 | # ℹ Fixes available. Run `rome lint --fix` to apply.
240 | # ✖ Found 2 problems
241 | $ rome lint index.ts --fix
242 | # ......
243 | # ✔ 1 file fixed
244 | # ✖ Found 2 problems
245 | ```
246 | 
247 | rome lint 命令在这里提示我们需要加分号并需要在 api.ts 中成功导出 interface。前者可以使用 rome lint index.ts --fix 直接来修理（不会在 api.ts 中添加分号）；后者需要手动修理，但是提供了十分完善的友好提示。
248 | 
249 | ### 05、rome compile index.ts
250 | 
251 | rome compile 命令将使用一组默认转换来编译文件。由于在开发中，当前此命令没有用于指定转换子集的选项。使用这条命令后，输出的结果已经没有了 interface 的存在。
252 | 
253 | ```bash
254 | $ rome compile index.ts
255 | # import {getData, Params} from './api';
256 | # 
257 | # async function setData() {
258 | #   const param = {
259 | #     username: 'hylerrix',
260 | #     token: 'ningowood',
261 | #   };
262 | #   const {success, data} = await getData(param);
263 | #   console.log('success:', success);
264 | #   console.log('data:', data);
265 | # }
266 | # 
267 | # await setData();
268 | ```
269 | 
270 | ### 06、rome parse index.ts
271 | 
272 | rome parse 命令将解析文件并输出格式精美的 AST。
273 | 
274 | ```bash
275 | $ rome parse index.ts
276 | # Program {
277 | #   comments: Array []
278 | #   corrupt: false
279 | #   diagnostics: Array []
280 | #   directives: Array []
281 | #   filename: 'project-rome/index.ts'
282 | #   hasHoistedVars: false
283 | #   mtime: 1_586_498_633_476.8486
284 | #   sourceType: 'module'
285 | #   syntax: Array ['ts']
286 | #   body: Array [
287 | #     ImportDeclaration {
288 | #       source: StringLiteral {value: './api'}
289 | #       namedSpecifiers: Array [
290 | #       	......
291 | ```
292 | 
293 | ### 07、Rome 的更多命令
294 | 
295 | 除了官网展示的几个命令外，从源码可以看出还有很多内置的命令正在开发，可以从 rome --help 中寻找答案。
296 | 
297 | ```bash
298 | # 分析并输出文件的依赖
299 | $ rome analyzeDependencies index.ts
300 | # 把 JavaScript 打包为一个文件
301 | $ rome bundle index.ts dist
302 | # 启动 Web 服务器
303 | $ rome develop
304 | # 计算文件路径
305 | $ rome resolve index.ts
306 | # 安全依赖，运行 Linter 和测试
307 | $ rome ci
308 | # 运行测试
309 | $ rome test
310 | # ...restart/start/status/stop/web
311 | # ...config/publish/run/evict/logs/rage
312 | ```
313 | 
314 | ## 参考资料
315 | 
316 | - [English] [Rome Github Project](https://github.com/facebookexperimental/rome)
317 | - [English] [Rome, a new JavaScript Toolchain](https://jasonformat.com/rome-javascript-toolchain/)
318 | - [English] [Rome Official Announcement](https://twitter.com/sebmck/status/1232885861135421441)
319 | - [English] [Rome Timeline](https://twitter.com/sebmck/status/1108407803545214977)
320 | - [English] [Facebook Introduces Rome Experimental JavaScript Toolchain](https://www.infoq.com/news/2020/03/rome-experimental-js-toolchain/)
321 | - [English] [01: Sebastian McKenzie on Babel and the Road to Rome - The Babel Podcast](https://podcast.babeljs.io/rome/)
322 | - [前端工具链课（一）—— 包管理工具](https://zhuanlan.zhihu.com/p/23928404)
323 | - [Rome：Facebook 最新 JS 工具上手](https://blog.csdn.net/qiwoo_weekly/article/details/104624223)
324 | 
325 | ## 总结 & 订阅
326 | 
327 | 经过近几年的蓬勃发展，JavaScript 早已不再局限于“前端开发”的领域中。因此本篇写作的角度并不是仅仅以前端开发为主体探索，而是将 JavaScript 本身抽离出来，这也是自己逐步理清职业发展的一个重要改变。
328 | 
329 | 本文通过学习和写作分享对 Rome 进行了简要的了解，但这还仅仅是入门。自己对 Babel 本身并不熟，还有很多学习过程中产生的疑惑都无法现在进行合适的解答，比如“Rome 和 Babel 的具体异同”、“如何看待 Rome 仓库使用 Git 跟踪 Node Modules”、“Rome 替代现有工具或进行集成方案的具体原理”以及“Rome 的打包流程有何特点”等，挖个坑可以一起交流。
330 | 
331 | 无论最终是否使用 Rome，能引发对 JavaScript 工具链的重新思考也会很有收获。
332 | 
333 | 最后，感谢你的阅读，公众号(@ningowood) 及配套群聊欢迎加入，同时欢迎给如期更新了三期，即将支持线上 UI 界面浏览并提供更多拓展功能的“开源爱好者月刊（[@ningowood/open-source-magazine](https://github.com/ningowood/open-source-magazine)）”仓库点个 Star 吧！（Github 好久没涨粉丝了，也欢迎关注我~）
334 | 
335 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1586513640616-7cc6456c-66cd-441d-aa44-09c7567d2960.png#align=left&display=inline&height=258&margin=%5Bobject%20Object%5D&name=image.png&originHeight=258&originWidth=258&size=46759&status=done&style=none&width=258)
336 | 


--------------------------------------------------------------------------------
/site/articles/explore/create-react-app-intro.md:
--------------------------------------------------------------------------------
  1 | # 深入浅出 Create React App
  2 | 
  3 | 本文差点难产而死。因为总结的过程中，多次怀疑本文是对官方文档的直接翻译和简单罗列；同时官方文档很全面，全范围的介绍无疑加深了写作的心智负担。但在最终的梳理中，发现走出了一条与众不同的路，于是坚持分享出来。
  4 | 
  5 | 希望本文除了能带领我们再次了解 Create React App(后文简称 CRA) 外，还能提供一种不同的知识组织结构和技术视角，加深我们对整个 React 技术生态的理解。
  6 | 
  7 | > 本文可能是多篇博客的综合体，整理和写作时间 15h+，仔细阅读时间 30min+，请慢用。
  8 | 
  9 | 本文面向的读者是：
 10 | 
 11 | - 前端开发初学者或 React 初学者；
 12 | - 使用过 CRA 搭建 React 项目但想拓展相关知识面的人；
 13 | - 希望通过一篇文章快速复习 CRA 的人；
 14 | - 英文初学者，想要通过一篇中文技术文章来让自己接下来读英文文档不再困难的人；
 15 | - 以及就想点进来支持一下的人。
 16 | 
 17 | 其次，本文在对官方文档进行一定的重新编排下，加上了如下创新点以完善整体的阅读学习体验：
 18 | 
 19 | - [x] 添加了实战 1：使用单个 HTML 文件构建 React App；
 20 | - [x] 添加了实战 2：使用 Webpack 手动构建 React App；
 21 | - [x] 添加了实战 3：使用 CRA 一站式构建 React App；
 22 | - [x] 添加了实战 4：使用 Source Map Explorer 分析打包文件；
 23 | - [x] 添加了实战 5：在已有的 React 项目中引入/升级 CRA；
 24 | - [x] 添加了实战 6：使用 React App Rewired 注入新配置；
 25 | - [x] 添加了：对 CRA 未来版本的简单展望；
 26 | - [x] 添加了：一个 Dan 十年回顾文章的导读。
 27 | 
 28 | 最终，本文不涉及源码的解读，想要阅读源码的同学可以移步官方源码仓库，整体设计思路并不是很难，具体实现原理可以细细品嚼；且本文对与 CRA 不直接相关的技术点会略略而过，欢迎从点到面主动学习更多。以下是官方源码仓库以及官方文档地址：
 29 | 
 30 | - Github 地址：[https://github.com/facebook/create-react-app](https://github.com/facebook/create-react-app)
 31 | - 官方文档地址：[https://create-react-app.dev](https://create-react-app.dev/)
 32 | 
 33 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1578586685262-ca35e2db-94b8-4510-a922-8ef68ade06ee.png#align=left&display=inline&height=704&margin=%5Bobject%20Object%5D&name=image.png&originHeight=1408&originWidth=2790&size=145496&status=done&style=none&width=1395)
 34 | 
 35 | ## 初始化 React App 的多种方式
 36 | 
 37 | 常见的初始化 React App 的方式有：
 38 | 
 39 | - 不使用构建工具构建 React App；
 40 | - 使用 Webpack 手动构建 React App；
 41 | - 使用 Create React App 一站式构建 React App；
 42 | - 在在线沙箱平台直接构建 React App（一般用于 Demo 预演，本文不涉及）。
 43 | 
 44 | 下面我们分别进行介绍与实战练习。
 45 | 
 46 | ## 实战 1：使用单个 HTML 文件构建 React App
 47 | 
 48 | React 本身专注于构建用户界面，并不依赖于某个构建工具，因此我们可以用传统的方式引入 React 并书写第一个“Hello World!” App。这种方式是快速尝试 React 的好方法，但并不适用于正式开发。
 49 | 
 50 | 以下 HTML 代码段是一种实现方式，使用了可选的 Babel 编译和 JSX 语法，基于非构建工具的更多初始化页面的方法（如不使用 JSX 等）可以自行探索。
 51 | 
 52 | ```html
 53 | <html>
 54 |   <head>
 55 |     <script src="https://unpkg.com/react@16/umd/react.development.js"></script>
 56 |     <script src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"></script>
 57 |     <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script> <!-- 不需要用于生产环境 -->
 58 |   </head>
 59 |   <body>
 60 |     <div id="root"></div>
 61 |     <script type="text/babel">
 62 |       ReactDOM.render(
 63 |         <h1>Hello, world!</h1>,
 64 |         document.getElementById('root')
 65 |       )
 66 |     </script>
 67 |   </body>
 68 | </html>
 69 | ```
 70 | 
 71 | ## 实战 2：使用 Webpack 手动构建 React App
 72 | 
 73 | 构建工具有很多种，目前最为主流的构建工具当属 Webpack。如何使用 Webpack 逐步构建 React App？
 74 | 
 75 | > 果不其然，为了证明 CRA 的便捷性而引出的本节 Webpack 实战，耗费了一小时多的时间进行了亲自踩坑，搜索了较多的博文都由于发布时间性而不能和最新的版本进行融合，最终根据 Github 中 [react-webpack-babel](https://github.com/ReactJSResources/react-webpack-babel) 库的 package.json 文件里的相关信息才得到实现。
 76 | 
 77 | ```bash
 78 | # 创建一个项目并进入该项目
 79 | $ mkdir react-webpack-steper & cd react-webpack-steper
 80 | # 使用默认选项直接生成一个初始化的 package.json
 81 | $ npm init -y
 82 | # 安装 React 基础包
 83 | $ sudo npm install --save react react-dom
 84 | # 安装 Webpack 相关工具 - 打包、本地启动支持、本地异步请求模拟以及热更新等
 85 | $ sudo npm install --save webpack webpack-cli webpack-dev-server
 86 | # 安装 Babel 相关工具 - 提供 ES6+ 新功能支持
 87 | $ sudo npm install --save-dev @babel/cli @babel-core @babel/preset-env @babel/preset-react
 88 | $ sudo npm install --save-dev babel-loader babel-plugin-module-resolver html-webpack-plugin
 89 | # 新建打包、编译配置文件并准备编写
 90 | $ touch webpack.config.js
 91 | $ touch .babelrc
 92 | # 新建 React 文件
 93 | $ mkdir src
 94 | $ touch src/index.js
 95 | $ touch src/index.html
 96 | ```
 97 | 
 98 | 其中，webpack.config.js 源码如下：
 99 | 
100 | ```javascript
101 | const path = require('path')
102 | const HtmlWebpackPlugin = require('html-webpack-plugin')
103 | 
104 | module.exports = {
105 |   entry: path.resolve(__dirname, './src/index.js'),
106 |   module: {
107 |     rules: [
108 |       {
109 |         test: /\.js$/,
110 |         exclude: /node_modules/,
111 |         loader: 'babel-loader'
112 |       },
113 |     ]
114 |   },
115 |   resolve: {
116 |     extensions: ['*', '.js', '.jsx']
117 |   },
118 |   output: {
119 |     path: path.resolve(__dirname, './build'),
120 |     filename: 'bundle.js',
121 |     publicPath: '/'
122 |   },
123 |   plugins: [
124 |     new HtmlWebpackPlugin({
125 |       template: path.resolve(__dirname, './src/index.html')
126 |     })
127 |   ]
128 | }
129 | ```
130 | 
131 | .babelrc 源码如下：
132 | 
133 | ```javascript
134 | {
135 |   "presets": ["@babel/preset-env", "@babel/preset-react"],
136 |   "plugins": [
137 |     ["module-resolver", {
138 |       "root": ["./src"]
139 |     }]
140 |   ]
141 | }
142 | ```
143 | 
144 | src/index.html 源码如下：
145 | 
146 | ```javascript
147 | <!doctype html>
148 | <html lang="en">
149 | <head>
150 |   <meta charset="utf-8">
151 |   <title>Hello World!</title>
152 | </head>
153 | <body>
154 |   <div id="root">Loading...</div>
155 | </body>
156 | </html>
157 | ```
158 | 
159 | src/index.js 源码如下：
160 | 
161 | ```javascript
162 | import React from 'react'
163 | import ReactDOM from 'react-dom'
164 | 
165 | ReactDOM.render(
166 |   <h1>Hello, world!</h1>,
167 |   document.getElementById('root')
168 | )
169 | ```
170 | 
171 | 此时，一个基于 Webpack 手动搭建的简易型“Hello World”App 开发完成，可以通过如下命令本地运行。
172 | 
173 | ```bash
174 | $ webpack-dev-server --mode development --open --hot
175 | ```
176 | 
177 | 更多自定义内容如添加 devServer 支持、添加多页应用支持...等各种各样新技术栈的支持，也可以引申实战。
178 | 
179 | ## 因此，我们需要 CRA
180 | 
181 | 可见，不使用构建工具编写不切实际，使用构建工具手动搭建 React App 又很繁琐。因此我们需要一个能初始化一个可直接运行项目的工具，并提供各种简易的插件，Create React App 应运而生。
182 | 
183 | > CRA 适用于中小型 React 项目。
184 | 
185 | ### CRA 的设计哲学
186 | 
187 | - 一种依赖关系。尽管 CRA 使用了 Webpack，Babel，ESLint 等各种出色的项目，但我们只需要 CRA 一种依赖；从 CRA 生成项目的 package.json 中也可以看到并没有 Webpack、Babel 的痕迹。
188 | - 无需配置。我们无需进行任何额外配置便可以直接运行代码，专注业务开发；同时 CRA 还提供了开发和生产版本的合理配置。
189 | - 非锁定配置。只需要运行一个命令， 所有的配置项和构建依赖项都将直接“弹出”到项目中，交由我们来修改。
190 | 
191 | ### CRA 包含了什么？
192 | 
193 | CRA 将具有构建现代单页 React 应用所需的一切：
194 | 
195 | - React，JSX，ES6，TypeScript 和 Flow 语法支持；
196 | - ES6+ 标准的支持，例如对象传播运算符；
197 | - CSS 自动添加前缀的支持，因此我们不需要 -webkit- 或其他前缀；
198 | - 快速的交互式单元测试运行程序，内置对覆盖率报告的支持；
199 | - 实时开发服务器，警告常见错误；
200 | - 一个构建脚本，用于将 JS，CSS 和图像与哈希和源映射捆绑在一起进行生产；
201 | - 满足所有渐进式 Web 应用程序标准的 [ServiceWorker](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers) 和 [Web 应用程序清单](https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/) 支持 （注意：从react-scripts@2.0.0及更高版本开始支持 ServiceWorker）；
202 | - 单一依赖项即可轻松更新上述工具。
203 | 
204 | ### CRA 的使用场景
205 | 
206 | Create React App 非常适合：
207 | 
208 | - 在方便且功能丰富的开发环境中学习 React；
209 | - 快速启动新的单页 React 应用程序；
210 | - 快速使用 React 为库和组件创建示例。
211 | 
212 | 如果我们想在没有数百个传递构建工具依赖的情况下尝试 React，请考虑使用单个 HTML 文件构建或使用在线沙箱平台构建。
213 | 
214 | - 如果需要将 React 代码与服务器端模板框架（如 Rails，Django 或 Symfony）集成，或者如果不构建单页应用，请考虑使用更灵活的 [nwb](https://github.com/insin/nwb) 或 [Neutrino](https://neutrino.js.org/)。特别是对于 Rails，可以使用 [Rails Webpacker](https://github.com/rails/webpacker)。对于 Symfony，请尝试 [Symfony's Webpack Encore](https://symfony.com/doc/current/frontend/encore/reactjs.html)；
215 | - 如果需要发布 React 组件，[nwb](https://github.com/insin/nwb) 以及 Neutrino 的 [react-components preset](https://neutrino.js.org/packages/react-components/) 也可以这样做；
216 | - 如果要使用 React 和 Node.js 进行服务器渲染，请查看 [Next.js](https://github.com/zeit/next.js/) 或 [Razzle](https://github.com/jaredpalmer/razzle)。 Create React App 与后端无关，仅生成静态HTML / JS / CSS包；
217 | - 如果网站大部分是静态的（例如，投资组合或博客），请考虑改用 [Gatsby](https://www.gatsbyjs.org/)。与 Create React App 不同，它在构建时会将网站预先渲染为 HTML；
218 | - 最后，如果需要更多自定义设置，请查看 Neutrino 及其 [React preset](https://neutrino.js.org/packages/react/)。
219 | 
220 | ### CRA 支持的浏览器
221 | 
222 | 一些支持的浏览器规则如下：
223 | 
224 | - 默认情况下，生成的项目支持所有现代浏览器。 对 Internet Explorer 9、10 和 11 的支持需要 polyfill。 对于一组支持旧版浏览器的 polyfill，请使用 [react-app-polyfill](https://github.com/facebook/create-react-app/blob/master/packages/react-app-polyfill/README.md)；
225 | - 默认情况下，生成的项目在 package.json 文件中包含一个 browserslist 配置，以针对基于全球使用情况（> 0.2％）的广泛浏览器（用于生产构建）和用于开发的现代浏览器。 这提供了良好的开发体验，尤其是在使用异步/等待等语言功能时，但仍与生产中的许多浏览器保持高度兼容性；
226 | - browserslist 配置控制输出的 JavaScript，以使注入的代码与指定的浏览器兼容。 通过运行构建脚本来创建生产构建时，将使用生产列表，而在运行启动脚本时，将使用开发列表。 可以使用 [https://browserl.ist](https://browserl.ist) 查看配置的浏览器列表支持的浏览器；
227 | - 请注意，这不会自动包括 polyfills，仍然需要根据所支持的浏览器来添加语言功能（见上文）；
228 | - 在编辑 browserslist 配置时，我们的更改可能不会立即被获取。 这是由于 babel-loader 中的一个未检测到 package.json 中更改的问题。 一种快速的解决方案是删除 node_modules/.cache 文件夹，然后重试。
229 | 
230 | 这里的重点是 BrowsersList，一个“在不同的前端工具之间共用目标浏览器和 node 版本的配置工具”。简而言之，就是 Babel 等转移工具通过我们设置的 BrowsersList 中想要支持的浏览器版本来决定哪些语法需要被编译。
231 | 
232 | ### CRA 支持的 ES 标准
233 | 
234 | 一些支持的 ES 标准规则如下：
235 | 
236 | - 该项目支持最新 JavaScript 标准的超集。 除ES6语法功能外，它还支持：
237 |    - [Exponentiation Operator](https://github.com/rwaldron/exponentiation-operator) (ES2016)；
238 |    - [Async/await](https://github.com/tc39/ecmascript-asyncawait) (ES2017)；
239 |    - [Object Rest/Spread Properties](https://github.com/tc39/proposal-object-rest-spread) (ES2018)；
240 |    - [Dynamic import()](https://github.com/tc39/proposal-dynamic-import) (stage 4 proposal)；
241 |    - [Class Fields and Static Properties](https://github.com/tc39/proposal-class-public-fields) (part of stage 3 proposal)；
242 |    - [JSX](https://facebook.github.io/react/docs/introducing-jsx.html), [Flow](https://create-react-app.dev/docs/adding-flow) and [TypeScript](https://create-react-app.dev/docs/adding-typescript)；
243 |    - Learn more about [different proposal stages](https://tc39.github.io/process-document/)。
244 | - 尽管 Facebook 建议谨慎使用实验性功能，但 Facebook 会在产品代码中大量使用这些功能，因此，如果将来任何这些建议发生更改，Facebook 都打算提供 [codemod](https://medium.com/@cpojer/effective-javascript-codemods-5a6686bb46fb)；
245 | - 请注意，默认情况下，该项目不包含任何 [polyfill](https://github.com/facebook/create-react-app/blob/master/packages/react-app-polyfill/README.md)；
246 | - 如果您使用任何其他需要运行时支持的ES6 +功能（例如Array.from（）或Symbol），请确保[手动包括适当的polyfill](https://github.com/facebook/create-react-app/blob/master/packages/react-app-polyfill/README.md)，或者您要定位的浏览器已支持它们。
247 | 
248 | ### CRA 的两个核心库
249 | 
250 | Create React App 有两个核心库，如下:
251 | 
252 | - create-react-app 是全局命令，用于创建初始化的 React 项目；
253 | - react-scripts 是所生成的项目中的开发依赖项，包括运行项目、测试项目、打包项目等多种命令。由于 CRA 的一种依赖性原则，react-scripts 便开放了所有内部其它依赖的使用方式。
254 | 
255 | ## 实战 3：使用 CRA 构建 React App
256 | 
257 | 到这里，我们终于需要通过命令行来安装和使用 CRA，来构建我们的第三个“Hello World”App。
258 | 
259 | ### 全局安装 CRA
260 | 
261 | 为保证每一个新项目都能使用到 CRA 最新最全的功能，请确保 CRA 为最新版本。
262 | 
263 | ```bash
264 | # 在已安装 CRA 的情况下，可以先卸载 CRA
265 | $ npm uninstall -g create-react-app
266 | # 正式安装 CRA
267 | $ npm install -g create-react-app
268 | ```
269 | 
270 | ### 初始化 CRA 项目
271 | 
272 | 根据我们的 npm 版本，选择相应命令来安装最新版的 CRA 并初始化第一个项目。同时检查自己的 node 版本，需要在本地开发计算机上安装 Node 8.16.0 或 Node 10.16.0 或更高版本（但服务器上不需要）。 我们可以使用nvm（macOS / Linux）或 nvm-windows 在不同项目之间切换Node版本。
273 | 
274 | ```bash
275 | # 查看自己的 npm 版本
276 | $ npm --version
277 | 
278 | # 第一种新建项目方式——npm 5.2+ 时，以下命令会安装最新版 CRA
279 | $ npx create-react-app my-app
280 | # 第一种新建项目方式——npm 版本小于等于 5.1 时
281 | $ create-react-app my-app
282 | 
283 | # 第二种新建项目方式
284 | # npm 6+ 开始支持 npm init <initializer> 
285 | $ npm init react-app my-app
286 | 
287 | # 第三种新建项目方式
288 | $ yarn create react-app my-app
289 | ```
290 | 
291 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1578397692108-1eba7684-3757-43c0-96a1-4705bd26ecaf.png#align=left&display=inline&height=298&margin=%5Bobject%20Object%5D&name=image.png&originHeight=595&originWidth=825&size=51054&status=done&style=none&width=412.5)
292 | 
293 | ### 项目的文件结构
294 | 
295 | 通过命令行的构建，我们初始化了第一个 CRA 项目，其中帮我们生成的项目目录结构如下（只有 src 下的文件才会被 Webpack 处理，只有 public 下的文件才能被 public/index.html 使用）：
296 | 
297 | ```bash
298 | my-app
299 | ├── .git # 隐藏文件夹，会初始化第一个 Commit 记录
300 | ├── README.md
301 | ├── node_modules
302 | ├── package.json # 依赖配置文件
303 | ├── .gitignore
304 | ├── [floder_name] # 根目录下可以建立其他文件夹，但不会被用在生产环境中
305 | ├── public # 只有 public 下的文件才能被 public/index.html 使用
306 | │   ├── favicon.ico
307 | │   ├── index.html # public/index.html 页面模板
308 | │   └── manifest.json
309 | └── src # 只有 src 下的文件才会被 Webpack 处理
310 |     ├── App.css
311 |     ├── App.js
312 |     ├── App.test.js
313 |     ├── [floder_name] # 可以建立其他文件夹，以被 Webpack 成功导入
314 |     ├── index.css
315 |     ├── index.js # JavaScript 打包入口文件
316 |     ├── logo.svg
317 |     └── serviceWorker.js
318 | ```
319 | 
320 | 关于 package.json、index.js 和 public/index.html 文件夹，我们通过“实战 2”已经有所了解。前者是 JavaScript 打包入口文件，通常链接整个业务代码；后者是页面模板，是打包后整个静态页面的总入口。
321 | 
322 | 这里对以下两个文件的出现进行简要的意义概括。
323 | _
324 | 
325 | - src/serviceWorker.js：提供渐进式 Web 应用的核心功能，不论网络状况如何都能立即加载，并且在不需要网络请求（离线时）的情况下也能展示 UI ；
326 | - public/manifest.json：是渐进式 Web 应用将自身添加至桌面的功能依赖文件，也可以对图标、名称等信息进行配置。
327 | 
328 | ### 运行 CRA 项目
329 | 
330 | CRA 默认提供了运行、测试、打包、部署以及弹出项目的命令。其中的一些贴士：
331 | 
332 | - npm start 内置热更新机制，代码改动时页面自动刷新；
333 | - npm test 以交互方式运行测试观察程序，默认情况下运行与自上次提交以来更改的文件相关的测试；
334 | - npm run build 将要生产的应用程序生成到生成文件夹。它在生产模式下正确捆绑了React，并优化了构建以获得最佳性能。生成文件被压缩，并且文件名包含哈希；
335 | - npm run eject 将内置的各种 Webpack 配置弹出到项目中，让我们可以进行自定义。同时此操作不可逆，意味着我们承担了弹出配置后的风险。通常不推荐弹出，可以通过 React App Rewired 库进行配置注入。
336 | 
337 | ```bash
338 | # ---- 运行 ----
339 | $ npm start
340 | $ open http://localhost:3000
341 | # ---- 测试 ----
342 | $ npm test
343 | # ---- 打包 ----
344 | $ npm run builds
345 | # ---- 弹出配置 ----
346 | $ npm run eject
347 | ```
348 | 
349 | ### 搭建 CRA 生态
350 | 
351 | 根据官方文档的思路，我们还能从更多角度拓展 CRA 的使用边界，下面进行概要介绍。
352 | 
353 | - 为开发环境添加额外功能：包括“配置编辑器风格”、“开发隔离组件”、“分析打包文件”和“添加 HTTPS 支持”；
354 | - 添加样式与静态资源支持：包括“添加样式表文件”、“添加 CSS Modules 支持”、“添加 Sass 支持”、“添加 PostCSS 支持”、“添加图片文字和字体支持”、“添加 GraphQL 支持”、“使用 public 文件夹”、“进行代码拆分”；
355 | - 添加业务驱动支持：包括安装各种依赖项如“BootStrap”、“Flow”、“TypeScript”、“Delay”、“Router”，以及“导出组件”、“使用全局变量”、“配置环境变量”、“制作渐进式 Web 应用”和“创建生产环境”；
356 | - 添加测试支持：包括“运行测试”和“调试测试”；
357 | - 添加后端集成支持：包括“在开发环境中代理 API 请求”、“使用 AJAX 请求获取数据”、“集成后端 API”和“使用 Title & Meta 标签”；
358 | - 部署进阶：包括“静态服务器”、“Azure”、“Firebase”、“Github Pages”等平台的部署等。
359 | 
360 | 这里无法深入展开，每一个点都可以是一个新的实战，当我们需要某个功能时便可以查阅相关文档来主动探索。其中“分析打包文件”的解读见“实战 4”。
361 | 
362 | ## 实战 4：使用 Source Map Explorer 分析打包文件
363 | 
364 | ```bash
365 | # 安装文件分析工具 source-map-explorer
366 | $ sudo npm install --save source-map-explorer
367 | # 打包项目
368 | $ npm run build
369 | # 将如下命令放入 package.json 中并生成快捷方式 npm run analyze
370 | # $ source-map-explorer 'build/static/js/*.js'
371 | # 注意此命令直接在命令行输入会提示找不到相关命令
372 | $ npm run analyze
373 | ```
374 | 
375 | 对于一个刚被 CRA 生成的 React App 来说，分析的结果如下，包大小总计 129.38k。
376 | 
377 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1578588582058-7e1849b9-420a-4ef1-87ce-f032359d3826.png#align=left&display=inline&height=443&margin=%5Bobject%20Object%5D&name=image.png&originHeight=886&originWidth=1502&size=59266&status=done&style=none&width=751)
378 | 
379 | ## 实战 5：在已有的 React 项目中引入/升级 CRA
380 | 
381 | 回到刚才“实战 2”建立的 react-webpack-steper 项目中，当我们已经编写了一部分业务时，能否直接在当前项目中无痛引入 CRA？
382 | 
383 | 解决思路便是：在大多数情况下，更改 package.json 中的 react-scripts 版本并删除不必要依赖配置，接着在此文件夹中运行 npm install 就足够了，但最好参考更改日志以了解潜在的重大更改。CRA 致力于将重大更改保持在最低限度，以便可以轻松升级 React 脚本。
384 | 
385 | ```bash
386 | # 卸载 CRA 本身已经提供的依赖
387 | $ sudo npm uninstall --save webpack webpack-cli webpack-dev-server
388 | $ sudo npm uninstall --save-dev @babel/cli @babel-core @babel/preset-env @babel/preset-react
389 | $ sudo npm uninstall --save-dev babel-loader babel-plugin-module-resolver html-webpack-plugin
390 | # 删除 CRA 不需要使用的文件
391 | $ rm webpack.config.js .babelrc
392 | # 删除 node_modules
393 | $ rm -rf node_modules
394 | # 手动安装 React Script
395 | $ sudo npm install --save react-scripts@latest
396 | # 由于 CRA 默认规则，将 src/index.html 移至 public/index.html
397 | $ mkdir public
398 | $ mv src/index.html public
399 | # 在 package.json 中添加 React Script 启动命令
400 | $ vim package.json
401 | ```
402 | 
403 | package.json 中添加/覆盖如下指令。
404 | 
405 | ```bash
406 | "scripts": {
407 |     "start": "react-scripts start",
408 |     "build": "react-scripts build",
409 |     "test": "react-scripts test",
410 |     "eject": "react-scripts eject",
411 | ```
412 | 
413 | 再次执行即可。由于每个人的具体配置不一定一致，可根据自身所遇问题进行搜索。升级原理类似。
414 | 
415 | ```bash
416 | # 当没有 BrowsersList 时，CRA 会进行询问并帮助我们生成
417 | $ npm start
418 | ```
419 | 
420 | ## 实战 6：使用 React App Rewired 注入新配置
421 | 
422 | CRA 官方并不推荐使用 npm run eject 弹出配置，这会增加更多的 Webpack 维护工作。对于实在想改的 Webpack 配置来说，我们可以使用 [React App Rewired](https://github.com/timarney/react-app-rewired) 库进行配置注入，这里来做个小例子。
423 | 
424 | > 此工具可以在不 'eject' 也不创建额外 react-scripts 的情况下修改 create-react-app 内置的 webpack 配置，然后你将拥有 create-react-app 的一切特性，且可以根据你的需要去配置 webpack 的 plugins, loaders 等。
425 | 
426 | 继续使用 react-webpack-steper 项目，我们的简易目标是增加 devServer 本地代理。
427 | 
428 | **第一步：安装依赖并进行基础配置**
429 | 
430 | ```bash
431 | # 安装依赖
432 | $ sudo npm install --save-dev react-app-rewired customize-cra
433 | # 根目录建立 config-overrides.js
434 | $ touch config-overrides.js
435 | # 修改 package.json
436 | $ vim package.json
437 | # 运行项目
438 | $ npm start
439 | ```
440 | 
441 | 其中，config-overrides.js 的初始代码为：
442 | 
443 | ```javascript
444 | /* config-overrides.js */
445 | module.exports = function override(config, env) {
446 |   //do stuff with the webpack config...
447 |   return config;
448 | }
449 | ```
450 | 
451 | package.json 的修改思路为：
452 | 
453 | ```javascript
454 | /* package.json */
455 | "scripts": {
456 | - "start": "react-scripts start",
457 | + "start": "react-app-rewired start",
458 | - "build": "react-scripts build",
459 | + "build": "react-app-rewired build",
460 | - "test": "react-scripts test --env=jsdom",
461 | + "test": "react-app-rewired test --env=jsdom",
462 |   "eject": "react-scripts eject"
463 | }
464 | ```
465 | 
466 | **第二步：编写配置，进行代理**
467 | 
468 | ```bash
469 | # 新增配置文件
470 | $ mkdir config
471 | $ touch config/proxy.js
472 | # 修改 config-overrides.js
473 | $ vim config-overrides.js
474 | ```
475 | 
476 | 其中，config/proxy.js 源码是：
477 | 
478 | ```javascript
479 | module.exports = {
480 |   '/api/**': {
481 |       target: 'http://110.114.120.120:8080',
482 |       secure: false,
483 |       changeOrigin: false,
484 |   },
485 | }
486 | ```
487 | 
488 | config-overrides.js 修改为：
489 | 
490 | ```javascript
491 | const { overrideDevServer } = require('customize-cra')
492 | const proxy = require('./config/proxy')
493 | 
494 | module.exports = {
495 |   devServer: overrideDevServer((config) => {
496 |       config.proxy = proxy
497 |       return config
498 |   }),
499 | }
500 | ```
501 | 
502 | 此时，本地的所有 api 开头的接口请求都会被转发到 [http://110.114.120.120:8080](http://110.114.120.120:8080) 的模拟后端 IP 上。
503 | 
504 | ## 对 CRA 未来版本的简单展望
505 | 
506 | 截止目前(2020-01-10)，CRA 的最新版本是 v3.3.0，我们可以从 Github 的 MileStone 中看到未来可能会改善的功能，其中整理并如下所述。
507 | 
508 | - v3.x：添加多入口文件支持（不只是一个 index.js 入口）；使用 worker-loader 添加对 WebWorker 的支持；更早地检查 Node 的版本；添加对子资源完整性 SRI 支持；生产环境中预加载脚本和链接...
509 | - v4.0：支持 Webpack 5.0（Webpack 目前最新版 v4.41.5，v5 也推出了一年多内测版）；在 tsconfig.json 和 jsconfig.json 里新增对 baseUrl 和 paths 的支持（方便写 @ 绝对路径等）；支持 Jest 配置中设置browser 为 true（根据环境提供正确的 Node 或 Browser 模块）...
510 | - v100.0：提供构建过程中的监视模式；适用于 Hooks 的热加载...
511 | 
512 | 让我们一起持续关注。
513 | 
514 | ## 结语
515 | 
516 | 回顾文章，我们从初始化 React App 的多种方式，引出 CRA 的必要性再对其进行较为充分的解释，最后配上 6 个角度来从一些角度对 CRA 的使用方式进行了实战，最后回归到 CRA 的版本展望之中。
517 | 
518 | 感谢你的阅读，如果你有什么更多的疑惑，CRA 的官方文档 + 开源仓库一定会满足你的一切。
519 | 
520 | ![](https://cdn.nlark.com/yuque/0/2020/png/86548/1578591055691-2065e9cb-0776-4c28-85e4-7eab17645dbe.png#align=left&display=inline&height=284&margin=%5Bobject%20Object%5D&name=image.png&originHeight=860&originWidth=796&size=425153&status=done&style=none&width=263)
521 | 
522 | 最后，一起拜读一下 CRA 和 Redux 作者、React 的核心贡献者 Dan Abramov 发布的这篇“[我的十年回顾](https://overreacted.io/my-decade-in-review/)”文章。
523 | 
524 | 现在我们可以开始正式深入地学习 React 技术栈了。
525 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 | Attribution 4.0 International
  2 | 
  3 | =======================================================================
  4 | 
  5 | Creative Commons Corporation ("Creative Commons") is not a law firm and
  6 | does not provide legal services or legal advice. Distribution of
  7 | Creative Commons public licenses does not create a lawyer-client or
  8 | other relationship. Creative Commons makes its licenses and related
  9 | information available on an "as-is" basis. Creative Commons gives no
 10 | warranties regarding its licenses, any material licensed under their
 11 | terms and conditions, or any related information. Creative Commons
 12 | disclaims all liability for damages resulting from their use to the
 13 | fullest extent possible.
 14 | 
 15 | Using Creative Commons Public Licenses
 16 | 
 17 | Creative Commons public licenses provide a standard set of terms and
 18 | conditions that creators and other rights holders may use to share
 19 | original works of authorship and other material subject to copyright
 20 | and certain other rights specified in the public license below. The
 21 | following considerations are for informational purposes only, are not
 22 | exhaustive, and do not form part of our licenses.
 23 | 
 24 |      Considerations for licensors: Our public licenses are
 25 |      intended for use by those authorized to give the public
 26 |      permission to use material in ways otherwise restricted by
 27 |      copyright and certain other rights. Our licenses are
 28 |      irrevocable. Licensors should read and understand the terms
 29 |      and conditions of the license they choose before applying it.
 30 |      Licensors should also secure all rights necessary before
 31 |      applying our licenses so that the public can reuse the
 32 |      material as expected. Licensors should clearly mark any
 33 |      material not subject to the license. This includes other CC-
 34 |      licensed material, or material used under an exception or
 35 |      limitation to copyright. More considerations for licensors:
 36 | 	wiki.creativecommons.org/Considerations_for_licensors
 37 | 
 38 |      Considerations for the public: By using one of our public
 39 |      licenses, a licensor grants the public permission to use the
 40 |      licensed material under specified terms and conditions. If
 41 |      the licensor's permission is not necessary for any reason--for
 42 |      example, because of any applicable exception or limitation to
 43 |      copyright--then that use is not regulated by the license. Our
 44 |      licenses grant only permissions under copyright and certain
 45 |      other rights that a licensor has authority to grant. Use of
 46 |      the licensed material may still be restricted for other
 47 |      reasons, including because others have copyright or other
 48 |      rights in the material. A licensor may make special requests,
 49 |      such as asking that all changes be marked or described.
 50 |      Although not required by our licenses, you are encouraged to
 51 |      respect those requests where reasonable. More_considerations
 52 |      for the public:
 53 | 	wiki.creativecommons.org/Considerations_for_licensees
 54 | 
 55 | =======================================================================
 56 | 
 57 | Creative Commons Attribution 4.0 International Public License
 58 | 
 59 | By exercising the Licensed Rights (defined below), You accept and agree
 60 | to be bound by the terms and conditions of this Creative Commons
 61 | Attribution 4.0 International Public License ("Public License"). To the
 62 | extent this Public License may be interpreted as a contract, You are
 63 | granted the Licensed Rights in consideration of Your acceptance of
 64 | these terms and conditions, and the Licensor grants You such rights in
 65 | consideration of benefits the Licensor receives from making the
 66 | Licensed Material available under these terms and conditions.
 67 | 
 68 | 
 69 | Section 1 -- Definitions.
 70 | 
 71 |   a. Adapted Material means material subject to Copyright and Similar
 72 |      Rights that is derived from or based upon the Licensed Material
 73 |      and in which the Licensed Material is translated, altered,
 74 |      arranged, transformed, or otherwise modified in a manner requiring
 75 |      permission under the Copyright and Similar Rights held by the
 76 |      Licensor. For purposes of this Public License, where the Licensed
 77 |      Material is a musical work, performance, or sound recording,
 78 |      Adapted Material is always produced where the Licensed Material is
 79 |      synched in timed relation with a moving image.
 80 | 
 81 |   b. Adapter's License means the license You apply to Your Copyright
 82 |      and Similar Rights in Your contributions to Adapted Material in
 83 |      accordance with the terms and conditions of this Public License.
 84 | 
 85 |   c. Copyright and Similar Rights means copyright and/or similar rights
 86 |      closely related to copyright including, without limitation,
 87 |      performance, broadcast, sound recording, and Sui Generis Database
 88 |      Rights, without regard to how the rights are labeled or
 89 |      categorized. For purposes of this Public License, the rights
 90 |      specified in Section 2(b)(1)-(2) are not Copyright and Similar
 91 |      Rights.
 92 | 
 93 |   d. Effective Technological Measures means those measures that, in the
 94 |      absence of proper authority, may not be circumvented under laws
 95 |      fulfilling obligations under Article 11 of the WIPO Copyright
 96 |      Treaty adopted on December 20, 1996, and/or similar international
 97 |      agreements.
 98 | 
 99 |   e. Exceptions and Limitations means fair use, fair dealing, and/or
100 |      any other exception or limitation to Copyright and Similar Rights
101 |      that applies to Your use of the Licensed Material.
102 | 
103 |   f. Licensed Material means the artistic or literary work, database,
104 |      or other material to which the Licensor applied this Public
105 |      License.
106 | 
107 |   g. Licensed Rights means the rights granted to You subject to the
108 |      terms and conditions of this Public License, which are limited to
109 |      all Copyright and Similar Rights that apply to Your use of the
110 |      Licensed Material and that the Licensor has authority to license.
111 | 
112 |   h. Licensor means the individual(s) or entity(ies) granting rights
113 |      under this Public License.
114 | 
115 |   i. Share means to provide material to the public by any means or
116 |      process that requires permission under the Licensed Rights, such
117 |      as reproduction, public display, public performance, distribution,
118 |      dissemination, communication, or importation, and to make material
119 |      available to the public including in ways that members of the
120 |      public may access the material from a place and at a time
121 |      individually chosen by them.
122 | 
123 |   j. Sui Generis Database Rights means rights other than copyright
124 |      resulting from Directive 96/9/EC of the European Parliament and of
125 |      the Council of 11 March 1996 on the legal protection of databases,
126 |      as amended and/or succeeded, as well as other essentially
127 |      equivalent rights anywhere in the world.
128 | 
129 |   k. You means the individual or entity exercising the Licensed Rights
130 |      under this Public License. Your has a corresponding meaning.
131 | 
132 | 
133 | Section 2 -- Scope.
134 | 
135 |   a. License grant.
136 | 
137 |        1. Subject to the terms and conditions of this Public License,
138 |           the Licensor hereby grants You a worldwide, royalty-free,
139 |           non-sublicensable, non-exclusive, irrevocable license to
140 |           exercise the Licensed Rights in the Licensed Material to:
141 | 
142 |             a. reproduce and Share the Licensed Material, in whole or
143 |                in part; and
144 | 
145 |             b. produce, reproduce, and Share Adapted Material.
146 | 
147 |        2. Exceptions and Limitations. For the avoidance of doubt, where
148 |           Exceptions and Limitations apply to Your use, this Public
149 |           License does not apply, and You do not need to comply with
150 |           its terms and conditions.
151 | 
152 |        3. Term. The term of this Public License is specified in Section
153 |           6(a).
154 | 
155 |        4. Media and formats; technical modifications allowed. The
156 |           Licensor authorizes You to exercise the Licensed Rights in
157 |           all media and formats whether now known or hereafter created,
158 |           and to make technical modifications necessary to do so. The
159 |           Licensor waives and/or agrees not to assert any right or
160 |           authority to forbid You from making technical modifications
161 |           necessary to exercise the Licensed Rights, including
162 |           technical modifications necessary to circumvent Effective
163 |           Technological Measures. For purposes of this Public License,
164 |           simply making modifications authorized by this Section 2(a)
165 |           (4) never produces Adapted Material.
166 | 
167 |        5. Downstream recipients.
168 | 
169 |             a. Offer from the Licensor -- Licensed Material. Every
170 |                recipient of the Licensed Material automatically
171 |                receives an offer from the Licensor to exercise the
172 |                Licensed Rights under the terms and conditions of this
173 |                Public License.
174 | 
175 |             b. No downstream restrictions. You may not offer or impose
176 |                any additional or different terms or conditions on, or
177 |                apply any Effective Technological Measures to, the
178 |                Licensed Material if doing so restricts exercise of the
179 |                Licensed Rights by any recipient of the Licensed
180 |                Material.
181 | 
182 |        6. No endorsement. Nothing in this Public License constitutes or
183 |           may be construed as permission to assert or imply that You
184 |           are, or that Your use of the Licensed Material is, connected
185 |           with, or sponsored, endorsed, or granted official status by,
186 |           the Licensor or others designated to receive attribution as
187 |           provided in Section 3(a)(1)(A)(i).
188 | 
189 |   b. Other rights.
190 | 
191 |        1. Moral rights, such as the right of integrity, are not
192 |           licensed under this Public License, nor are publicity,
193 |           privacy, and/or other similar personality rights; however, to
194 |           the extent possible, the Licensor waives and/or agrees not to
195 |           assert any such rights held by the Licensor to the limited
196 |           extent necessary to allow You to exercise the Licensed
197 |           Rights, but not otherwise.
198 | 
199 |        2. Patent and trademark rights are not licensed under this
200 |           Public License.
201 | 
202 |        3. To the extent possible, the Licensor waives any right to
203 |           collect royalties from You for the exercise of the Licensed
204 |           Rights, whether directly or through a collecting society
205 |           under any voluntary or waivable statutory or compulsory
206 |           licensing scheme. In all other cases the Licensor expressly
207 |           reserves any right to collect such royalties.
208 | 
209 | 
210 | Section 3 -- License Conditions.
211 | 
212 | Your exercise of the Licensed Rights is expressly made subject to the
213 | following conditions.
214 | 
215 |   a. Attribution.
216 | 
217 |        1. If You Share the Licensed Material (including in modified
218 |           form), You must:
219 | 
220 |             a. retain the following if it is supplied by the Licensor
221 |                with the Licensed Material:
222 | 
223 |                  i. identification of the creator(s) of the Licensed
224 |                     Material and any others designated to receive
225 |                     attribution, in any reasonable manner requested by
226 |                     the Licensor (including by pseudonym if
227 |                     designated);
228 | 
229 |                 ii. a copyright notice;
230 | 
231 |                iii. a notice that refers to this Public License;
232 | 
233 |                 iv. a notice that refers to the disclaimer of
234 |                     warranties;
235 | 
236 |                  v. a URI or hyperlink to the Licensed Material to the
237 |                     extent reasonably practicable;
238 | 
239 |             b. indicate if You modified the Licensed Material and
240 |                retain an indication of any previous modifications; and
241 | 
242 |             c. indicate the Licensed Material is licensed under this
243 |                Public License, and include the text of, or the URI or
244 |                hyperlink to, this Public License.
245 | 
246 |        2. You may satisfy the conditions in Section 3(a)(1) in any
247 |           reasonable manner based on the medium, means, and context in
248 |           which You Share the Licensed Material. For example, it may be
249 |           reasonable to satisfy the conditions by providing a URI or
250 |           hyperlink to a resource that includes the required
251 |           information.
252 | 
253 |        3. If requested by the Licensor, You must remove any of the
254 |           information required by Section 3(a)(1)(A) to the extent
255 |           reasonably practicable.
256 | 
257 |        4. If You Share Adapted Material You produce, the Adapter's
258 |           License You apply must not prevent recipients of the Adapted
259 |           Material from complying with this Public License.
260 | 
261 | 
262 | Section 4 -- Sui Generis Database Rights.
263 | 
264 | Where the Licensed Rights include Sui Generis Database Rights that
265 | apply to Your use of the Licensed Material:
266 | 
267 |   a. for the avoidance of doubt, Section 2(a)(1) grants You the right
268 |      to extract, reuse, reproduce, and Share all or a substantial
269 |      portion of the contents of the database;
270 | 
271 |   b. if You include all or a substantial portion of the database
272 |      contents in a database in which You have Sui Generis Database
273 |      Rights, then the database in which You have Sui Generis Database
274 |      Rights (but not its individual contents) is Adapted Material; and
275 | 
276 |   c. You must comply with the conditions in Section 3(a) if You Share
277 |      all or a substantial portion of the contents of the database.
278 | 
279 | For the avoidance of doubt, this Section 4 supplements and does not
280 | replace Your obligations under this Public License where the Licensed
281 | Rights include other Copyright and Similar Rights.
282 | 
283 | 
284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability.
285 | 
286 |   a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
287 |      EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
288 |      AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
289 |      ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
290 |      IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
291 |      WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
292 |      PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
293 |      ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
294 |      KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
295 |      ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
296 | 
297 |   b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
298 |      TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
299 |      NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
300 |      INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
301 |      COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
302 |      USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
303 |      ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
304 |      DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
305 |      IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
306 | 
307 |   c. The disclaimer of warranties and limitation of liability provided
308 |      above shall be interpreted in a manner that, to the extent
309 |      possible, most closely approximates an absolute disclaimer and
310 |      waiver of all liability.
311 | 
312 | 
313 | Section 6 -- Term and Termination.
314 | 
315 |   a. This Public License applies for the term of the Copyright and
316 |      Similar Rights licensed here. However, if You fail to comply with
317 |      this Public License, then Your rights under this Public License
318 |      terminate automatically.
319 | 
320 |   b. Where Your right to use the Licensed Material has terminated under
321 |      Section 6(a), it reinstates:
322 | 
323 |        1. automatically as of the date the violation is cured, provided
324 |           it is cured within 30 days of Your discovery of the
325 |           violation; or
326 | 
327 |        2. upon express reinstatement by the Licensor.
328 | 
329 |      For the avoidance of doubt, this Section 6(b) does not affect any
330 |      right the Licensor may have to seek remedies for Your violations
331 |      of this Public License.
332 | 
333 |   c. For the avoidance of doubt, the Licensor may also offer the
334 |      Licensed Material under separate terms or conditions or stop
335 |      distributing the Licensed Material at any time; however, doing so
336 |      will not terminate this Public License.
337 | 
338 |   d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
339 |      License.
340 | 
341 | 
342 | Section 7 -- Other Terms and Conditions.
343 | 
344 |   a. The Licensor shall not be bound by any additional or different
345 |      terms or conditions communicated by You unless expressly agreed.
346 | 
347 |   b. Any arrangements, understandings, or agreements regarding the
348 |      Licensed Material not stated herein are separate from and
349 |      independent of the terms and conditions of this Public License.
350 | 
351 | 
352 | Section 8 -- Interpretation.
353 | 
354 |   a. For the avoidance of doubt, this Public License does not, and
355 |      shall not be interpreted to, reduce, limit, restrict, or impose
356 |      conditions on any use of the Licensed Material that could lawfully
357 |      be made without permission under this Public License.
358 | 
359 |   b. To the extent possible, if any provision of this Public License is
360 |      deemed unenforceable, it shall be automatically reformed to the
361 |      minimum extent necessary to make it enforceable. If the provision
362 |      cannot be reformed, it shall be severed from this Public License
363 |      without affecting the enforceability of the remaining terms and
364 |      conditions.
365 | 
366 |   c. No term or condition of this Public License will be waived and no
367 |      failure to comply consented to unless expressly agreed to by the
368 |      Licensor.
369 | 
370 |   d. Nothing in this Public License constitutes or may be interpreted
371 |      as a limitation upon, or waiver of, any privileges and immunities
372 |      that apply to the Licensor or You, including from the legal
373 |      processes of any jurisdiction or authority.
374 | 
375 | 
376 | =======================================================================
377 | 
378 | Creative Commons is not a party to its public
379 | licenses. Notwithstanding, Creative Commons may elect to apply one of
380 | its public licenses to material it publishes and in those instances
381 | will be considered the “Licensor.” The text of the Creative Commons
382 | public licenses is dedicated to the public domain under the CC0 Public
383 | Domain Dedication. Except for the limited purpose of indicating that
384 | material is shared under a Creative Commons public license or as
385 | otherwise permitted by the Creative Commons policies published at
386 | creativecommons.org/policies, Creative Commons does not authorize the
387 | use of the trademark "Creative Commons" or any other trademark or logo
388 | of Creative Commons without its prior written consent including,
389 | without limitation, in connection with any unauthorized modifications
390 | to any of its public licenses or any other arrangements,
391 | understandings, or agreements concerning use of licensed material. For
392 | the avoidance of doubt, this paragraph does not form part of the
393 | public licenses.
394 | 
395 | Creative Commons may be contacted at creativecommons.org.


--------------------------------------------------------------------------------
/site/articles/blitzjs/blitz-introduction-1.md:
--------------------------------------------------------------------------------
  1 | # Blitz.js 入门教程：基于 Next.js 的下一代 React 全栈框架
  2 | 
  3 | ## 译者序
  4 | 
  5 | 苦 JS 生态久已。在 2020 年后，一直徘徊于该为自己构建怎样的技术栈，迟迟没有太多落地成果——库太多了，一个小场景就能有很多个解决方案；方向也太多了，哪怕大前端三个字，现今都能拆分为很多的细分领域。直到遇到了 Rome，看到社区已经开始尝试整合重构 Node 生态的前端工具链；又遇到了 Deno，直接摆脱 Node 的历史遗留问题来建设更贴近现代标准的 JavaScript/TypeScript 运行时；现在又遇到了 Blitz.js，一站式 React 全栈框架，在 Next.js 之上赋能更多的后端场景...于是自己的很多方向性问题都豁然开朗：通过建立不同的 Repo 来专攻不同的方向，且每个 Repo 都能有代表性的同时，覆盖更多的场景。于是——
  6 | 
  7 | - [Deno 钻研之术](https://github.com/hylerrix/deno-tutorial)：看未来，学标准。Node 也不落下。
  8 | - [Deno 算法之旅](https://github.com/hylerrix/deno-algorithm)：刷算法，玩测试。
  9 | - [ECMAScript 面试宝典](https://github.com/hylerrix/es-interview)：备面试，打基础；
 10 | - [Blitz.js + React 全栈开发手册](https://github.com/hylerrix/blitzjs-tutorial)：搞工程，尝全栈。深入 React，实战 Next.js，掌握后端开发。
 11 | - 以及还有一切弃坑的 repo......
 12 | 
 13 | 当然，Blitz.js 还有很多吸引人的特性：
 14 | 
 15 | - **一体式全栈架构**：在一个 Monorepo 里从数据库到用户端全搞定，也没用重复性代码。试想前后端分离的架构下，如果你喜欢 TypeScript 的话，很可能得写两套相同 TS...且这种一体式架构很容易让自己的项目灵感从头到尾地快速落地。
 16 | - **API 不再必须**：REST 和 GraphQL？或许都不需要，交给 Blitz.js 来在编译时构建。当需要提供 API 给更多端使用时，再结合相关库来生成 API。
 17 | - **更轻松的开箱体验**：脚手架初始化后直接提供登录注册甚至重置密码功能，直接支持最基本的后端环境，开箱即用的体验不能再好，同时甚至能通过强大的 blitz generate CLI 快速植入生态圈中的主流库到项目中。
 18 | - **并不会“学不动了”**：基于 Next.js，前端 React，后端 Prisma 等库，Blitz.js 构建于各种已经主流化的生态之上。
 19 | - **拥抱未来**：Blitz.js 预计将于下个月（2021 年 4 月）发布 v1.0 版本。
 20 | 
 21 | 本文属于《[Blitz.js + React 全栈开发手册](https://github.com/hylerrix/blitzjs-tutorial)》系列，原文翻译内容会同步更新到 [Blitz.js 中文仓库](https://github.com/blitz-js/zh-hans.blitzjs.com) 上。欢迎 Star 和 Watch：[https://github.com/hylerrix/blitzjs-tutorial](https://github.com/hylerrix/blitzjs-tutorial)。
 22 | 
 23 | ## 快速入手
 24 | 
 25 | ### 配置你的环境
 26 | 
 27 | 你需要使用 Node 12 或者更新的版本。
 28 | 
 29 | ### 安装 Blitz
 30 | 
 31 | 执行 `npm install -g blitz`
 32 | 
 33 | ### 创建一个新项目
 34 | 
 35 | 1. `blitz new myAppName`
 36 | 1. `cd myAppName`
 37 | 1. `blitz dev`
 38 | 1. 访问你的新项目 [http://localhost:3000](http://localhost:3000)
 39 | 
 40 | ### 欢迎来到 Blitz 社区 👋
 41 | 
 42 | Blitz 社区是个温暖、安全、多样化、包容也不失有趣的社区！ LGBTQ+、女生和少数派欢迎你们的到来。
 43 | 
 44 | [加入我们的 Discord 社区](https://discord.blitzjs.com)，我们会在这里帮助每个人搭建 Blitz 应用。这里也是我们协作共建 Blitz 本身的重要场地。
 45 | 
 46 | 对于提问以及会花费较长时间的讨论，[可以发帖到我们的论坛中](https://github.com/blitz-js/blitz/discussions)。
 47 | 
 48 | 有关完整的介绍，请阅读 社区是如何运作的。文中包括了如何获得帮助、如何报告错误以及如何提出新功能建议等的详细指导。
 49 | 
 50 | **欢迎你的帮助来使 Blitz 变得更好！ 🤝**
 51 | 
 52 | 我们有一个很棒的社区正在共同努力让 Blitz 成为世界上一流的框架。
 53 | 
 54 | 你该如何提供帮助：
 55 | 
 56 | 1. 通过 [在 GitHub 上提交 issue](https://github.com/blitz-js/blitz/issues/new/choose) 来反馈 Bug。
 57 | 1. 贡献代码： 阅读贡献指南，以了解如何开始。
 58 | 1. [赞助 & 捐赠](https://github.com/blitz-js/blitz#sponsors-and-donations)，可以从 $5/月 开始。
 59 | 1. 以及你觉得可以的其它任何方式！我们非常感谢你的任何贡献（如文档、视频、博客等）。如果你遇到任何阻碍，欢迎来 Discord 上与我们交流！:)
 60 | 
 61 | ### 下一步
 62 | 
 63 | #### 教程
 64 | 
 65 | 教程篇 是有关 Blitz 所有基本内容的完整练习，其中包括将模型添加到数据库以及从前端读取和更新数据。
 66 | 
 67 | #### 学习
 68 | 
 69 | 这里有你想要熟悉的 Blitz 的关键概念：
 70 | 
 71 | - 如何 新建页面
 72 | - 如何 使用文件路由系统
 73 | - 如何设置并 使用数据库
 74 | - 如何使用 Blitz Queries 和 Mutations 来读写你的数据库。
 75 | - 如何通过 `blitz generate` 命令来用脚手架生成数据库模型
 76 | 的所有代码。
 77 | 
 78 | ## 入门教程
 79 | 
 80 | 在本教程中，我们将会指导你创建一个简易的投票系统。
 81 | 
 82 | 我们将假设你已经 安装了 Blitz。你可以通过在终端运行以下命令来确定 Blitz 是否已经安装或检查安装的版本号：
 83 | 
 84 | ```bash
 85 | blitz -v
 86 | ```
 87 | 
 88 | 如果 Blitz 已经安装成功，你应该能看到安装的版本号。否则你会收到一条像这样的错误提示：“command not found: blitz”。
 89 | 
 90 | ### 创建一个新应用
 91 | 
 92 | 在命令行中，`cd` 进入你想要创建应用的根目录文件夹后，执行以下命令：
 93 | 
 94 | ```sh
 95 | blitz new my-blitz-app
 96 | ```
 97 | 
 98 | Blitz 会在你当前的文件夹中创建一个 `my-blitz-app` 文件夹。你接着会收到一个选择表单库的提示。本教程中将选择其中推荐的 `React Final Form` 库。
 99 | 
100 | 让我们看看 `blitz new` 命令创建了什么：
101 | 
102 | ```markdown
103 | my-blitz-app
104 | ├── app/
105 | │   ├── api/
106 | │   ├── auth/
107 | │   │   ├── components/
108 | │   │   │   ├── LoginForm.tsx
109 | │   │   │   └── SignupForm.tsx
110 | │   │   ├── mutations/
111 | │   │   │   ├── changePassword.ts
112 | │   │   │   ├── forgotPassword.test.ts
113 | │   │   │   ├── forgotPassword.ts
114 | │   │   │   ├── login.ts
115 | │   │   │   ├── logout.ts
116 | │   │   │   ├── resetPassword.test.ts
117 | │   │   │   ├── resetPassword.ts
118 | │   │   │   └── signup.ts
119 | │   │   ├── pages/
120 | │   │   │   ├── forgot-password.tsx
121 | │   │   │   ├── login.tsx
122 | │   │   │   ├── reset-password.tsx
123 | │   │   │   └── signup.tsx
124 | │   │   └── validations.ts
125 | │   ├── core/
126 | │   │   ├── components/
127 | │   │   │   ├── Form.tsx
128 | │   │   │   └── LabeledTextField.tsx
129 | │   │   ├── hooks/
130 | │   │   │   └── useCurrentUser.ts
131 | │   │   └── layouts/
132 | │   │       └── Layout.tsx
133 | │   ├── pages/
134 | │   │   ├── 404.tsx
135 | │   │   ├── _app.tsx
136 | │   │   ├── _document.tsx
137 | │   │   ├── index.test.tsx
138 | │   │   └── index.tsx
139 | │   └── users/
140 | │       └── queries/
141 | │           └── getCurrentUser.ts
142 | ├── db/
143 | │   ├── index.ts
144 | │   ├── schema.prisma
145 | │   └── seeds.ts
146 | ├── integrations/
147 | ├── mailers/
148 | │   └── forgotPasswordMailer.ts
149 | ├── public/
150 | │   ├── favicon.ico*
151 | │   └── logo.png
152 | ├── test/
153 | │   ├── setup.ts
154 | │   └── utils.tsx
155 | ├── README.md
156 | ├── babel.config.js
157 | ├── blitz.config.js
158 | ├── jest.config.js
159 | ├── package.json
160 | ├── tsconfig.json
161 | ├── types.d.ts
162 | ├── types.ts
163 | └── yarn.lock
164 | ```
165 | 
166 | 上述文件有：
167 | 
168 | - `app/` 文件夹是项目中绝大多数功能的容器。你可以在这里放置任何页面或 API 路由。
169 | - `app/pages/` 文件夹是主要的页面文件夹。如果你使用过 Next.js 你将会立即注意到两者的不同。在 Blitz 中，你可以有许多 `pages` 文件夹，它们将在构建时合并在一起。
170 | - `app/core/` 文件夹是放置整个应用中使用到的通用组件、Hooks 等的主要位置。
171 | - `db/` 是数据库配置所在的位置。如果你正在编写模型或检查迁移情况，可以来这里。
172 | - `public/` 文件夹可以让你放置任何静态资源。如果你有要在应用中使用的图像、文件或视频等，都可以放置在其中。
173 | - `.babelrc.js`、`.env` 等（“dotfiles 文件”）是各种 JavaScript 工具需要用到的配置文件。
174 | - `blitz.config.js` 用于 Blitz 的高级自定义配置，与 `next.config.js` 相同
175 | - `tsconfig.json` 是我们推荐的 TypeScript 设置。
176 | 
177 | ### 开发环境服务器
178 | 
179 | 现在，如果你还没有在 `my-blitz-app` 文件夹下，确保切换到其中，并运行以下命令：
180 | 
181 | ```sh
182 | blitz dev
183 | ```
184 | 
185 | 你将会在命令行中看到如下输出：
186 | 
187 | ```sh
188 | ✔ Compiled
189 | Loaded env from /private/tmp/my-blitz-app/.env
190 | warn  - You have enabled experimental feature(s).
191 | warn  - Experimental features are not covered by semver, and may cause unexpected or broken application behavior. Use them at your own risk.
192 | 
193 | ready - started server on 0.0.0.0:3000, url: http://localhost:3000
194 | info  - Using external babel configuration from /my-blitz-app/babel.config.js
195 | event - compiled successfully
196 | ```
197 | 
198 | 现在服务器已成功运行，浏览器中访问 [localhost:3000](http://localhost:3000)。你将会看到带有 Blitz logo 的欢迎页面。成功了！
199 | 
200 | ### 以用户身份注册
201 | 
202 | Bliz 应用让用户登录和注册开箱即用！现在让我们来尝试一下。点击 **注册** 按钮，输入任何电子邮件和密码，然后单击 **创建账户** 后，你将被重定向到用户主页，并在其中可以看到你的用户 `id` 和 `role`。
203 | 
204 | 如果需要，你也可以尝试注销并重新登录。或在登录页面上单击 **忘记密码**，以尝试重置密码流程。
205 | 
206 | ### 编写你的第一个页面
207 | 
208 | 接下来让我们创建你的第一个页面。
209 | 
210 | 打开 `app/pages/index.tsx` 文件然后替换掉 `Home` 组件的所有内容为这段代码：
211 | 
212 | ```jsx
213 | //...
214 | 
215 | const Home: BlitzPage = () => {
216 |   return (
217 |     <div>
218 |       <h1>Hello, world!</h1>
219 | 
220 |       <Suspense fallback="Loading...">
221 |         <UserInfo />
222 |       </Suspense>
223 |     </div>
224 |   )
225 | }
226 | 
227 | //...
228 | ```
229 | 
230 | 保存文件后你将会看到浏览器页面进行了更新。你可以如你所愿地添加需要的各种自
231 | 定义项，。准备就绪后，请转到下一节。
232 | 
233 | ### 数据库配置
234 | 
235 | 好消息是，已经为你建立好了 SQLite 数据库！你可以在终端中运行 `blitz prisma studio` 来打开一个可以查看数据库数据的 Web 界面。
236 | 
237 | 请注意，在开始第一个实际项目时，你可能希望使用可扩展性更高的数据库（如 PostgreSQL），以避免在将来切换数据库时产生的麻烦。有关更多信息，请参见 数据库概述 篇。目前，我们将继续使用默认的 SQLite 数据库。
238 | 
239 | ### 模型的脚手架代码
240 | 
241 | Blitz 提供了一个方便的 CLI 命令 `generate` 来构建样板代码。我们将使用 `generate` 来创建两个模型：`Question`（问题） 和 `Choice`（选择）。`Question` 包含问题内容和选择列表。`Choice` 包含选择内容、投票计数以及相关的问题。Blitz 将为这两个模型自动生成一个 id、一个创建时间戳以及一个最新更新的时间戳。
242 | 
243 | #### 首先，我们将生成与 `Question` 模型有关的所有信息：
244 | 
245 | ```bash
246 | blitz generate all question text:string
247 | ```
248 | 
249 | 当出现提示框时，按 **Enter** 以运行 `prisma migrate`，这将使用新的模型来更新你的数据库架构。此时会要求一个名称，可以输入“add question”之类的值。
250 | 
251 | ```bash
252 | CREATE    app/pages/questions/[questionId].tsx
253 | CREATE    app/pages/questions/[questionId]/edit.tsx
254 | CREATE    app/pages/questions/index.tsx
255 | CREATE    app/pages/questions/new.tsx
256 | CREATE    app/questions/components/QuestionForm.tsx
257 | CREATE    app/questions/queries/getQuestion.ts
258 | CREATE    app/questions/queries/getQuestions.ts
259 | CREATE    app/questions/mutations/createQuestion.ts
260 | CREATE    app/questions/mutations/deleteQuestion.ts
261 | CREATE    app/questions/mutations/updateQuestion.ts
262 | 
263 | ✔ Model for 'question' created in schema.prisma:
264 | 
265 | > model Question {
266 | >   id        Int      @default(autoincrement()) @id
267 | >   createdAt DateTime @default(now())
268 | >   updatedAt DateTime @updatedAt
269 | >   text      String
270 | > }
271 | 
272 | ? Run 'prisma migrate dev' to update your database? (Y/n) › true
273 | ```
274 | 
275 | ```bash
276 | Environment variables loaded from .env
277 | Prisma schema loaded from db/schema.prisma
278 | Datasource "db": SQLite database "db.sqlite" at "file:./db.sqlite"
279 | 
280 | ✔ Name of migration … add question
281 | The following migration(s) have been created and applied from new schema changes:
282 | 
283 | migrations/
284 |   └─ 20210217035805_add_question/
285 |     └─ migration.sql
286 | 
287 | ✔ Generated Prisma Client (2.17.0) to ./node_modules/@prisma/client in 103ms
288 | 
289 | Everything is now in sync.
290 | ```
291 | 
292 | `generate` 命令搭配 `all` 类型将生成相关的模型、queries、mutation 和页面文件。请参见 Blitz generate 页面查询更多可用的类型选项。
293 | 
294 | #### 接下来，我们将生成带有相应 queries 和 mutations 的 `Choice` 模型。
295 | 
296 | 这次我们搭配 `resource` 类型，因为我们不需要为 `Choice` 模型生成页面：
297 | 
298 | ```bash
299 | blitz generate resource choice text votes:int:default=0 belongsTo:question
300 | ```
301 | 
302 | 同样，在系统提示你进行迁移时，按 **Enter** 后输入迁移的名称。
303 | 
304 | ```bash
305 | CREATE    app/choices/queries/getChoice.ts
306 | CREATE    app/choices/queries/getChoices.ts
307 | CREATE    app/choices/mutations/createChoice.ts
308 | CREATE    app/choices/mutations/deleteChoice.ts
309 | CREATE    app/choices/mutations/updateChoice.ts
310 | 
311 | ✔ Model for 'choice' created in schema.prisma:
312 | 
313 | > model Choice {
314 | >   id         Int      @default(autoincrement()) @id
315 | >   createdAt  DateTime @default(now())
316 | >   updatedAt  DateTime @updatedAt
317 | >   text       String
318 | >   votes      Int      @default(0)
319 | >   question   Question @relation(fields: [questionId], references: [id])
320 | >   questionId Int
321 | > }
322 | 
323 | ? Run 'prisma migrate dev' to update your database? (Y/n) › true
324 | ```
325 | 
326 | #### 最后，让我们更新 `Question` 模型以关联到 `Choice` 上。
327 | 
328 | 打开 `db/schema.prisma` 并在 `Question` 模型中添加 `choices Choice[]`。
329 | 
330 | ```diff
331 | model Question {
332 |   id        Int      @id @default(autoincrement())
333 |   createdAt DateTime @default(now())
334 |   updatedAt DateTime @updatedAt
335 |   text      String
336 | + choices   Choice[]
337 | }
338 | ```
339 | 
340 | 然后运行 `blitz prisma generate` 来更新 prisma 客户端以同步 schema 的更改。这里不涉及数据库迁移，因为数据库中没有实际字段添加到 `Question` 模型中。
341 | 
342 | ### 访问 Prisma 数据库客户端
343 | 
344 | 现在，让我们跳进 Blitz 交互式 Shell 中，并使用 Blitz 为你提供的 Primsa 数据库客户端。要启动 Blitz 控制台，请使用以下命令：
345 | 
346 | ```bash
347 | blitz console
348 | ```
349 | 
350 | 一旦你进入控制台后，浏览数据库客户端：
351 | 
352 | ```bash
353 | # No questions are in the system yet.
354 | ⚡ > await db.question.findMany()
355 | []
356 | 
357 | # Create a new Question:
358 | ⚡ > let q = await db.question.create({data: {text: "What's new?"}})
359 | undefined
360 | 
361 | # See the entire object:
362 | ⚡ > q
363 | {
364 |   id: 1,
365 |   createdAt: 2020-06-15T15:06:14.959Z,
366 |   updatedAt: 2020-06-15T15:06:14.959Z,
367 |   text: "What's new?"
368 | }
369 | 
370 | # Or, access individual values on the object:
371 | ⚡ > q.text
372 | "What's new?"
373 | 
374 | # Change values by using the update function:
375 | ⚡ > q = await db.question.update({where: {id: 1}, data: {text: "What's up?"}})
376 | {
377 |   id: 1,
378 |   createdAt: 2020-06-15T15:06:14.959Z,
379 |   updatedAt: 2020-06-15T15:13:17.394Z,
380 |   text: "What's up?"
381 | }
382 | 
383 | # db.question.findMany() now displays all the questions in the database:
384 | ⚡ > await db.question.findMany()
385 | [
386 |   {
387 |     id: 1,
388 |     createdAt: 2020-06-15T15:06:14.959Z,
389 |     updatedAt: 2020-06-15T15:13:17.394Z,
390 |     text: "What's up?"
391 |   }
392 | ]
393 | ```
394 | 
395 | ### 更新模型属性生成的代码
396 | 
397 | > 在再次运行该应用之前，我们需要自定义一些已生成的代码。最终这些修复过程将不再需要——但就目前而言，我们需要解决结果未解决的问题。
398 | 
399 | 自动生成的页面，当前并未使用你在生成过程中定义的实际模型的属性。以后会支持，但现在，需要我们手动修复生成的页面。
400 | 
401 | #### Question 页面
402 | 
403 | 进入 `app/pages/questions/index.tsx`. 请注意到一个 `QuestionsList` 组件已经为你生成了：
404 | 
405 | ```jsx
406 | // app/pages/questions/index.tsx
407 | 
408 | export const QuestionsList = () => {
409 |   const router = useRouter()
410 |   const page = Number(router.query.page) || 0
411 |   const [{questions, hasMore}] = usePaginatedQuery(getQuestions, {
412 |     orderBy: {id: "asc"},
413 |     skip: ITEMS_PER_PAGE * page,
414 |     take: ITEMS_PER_PAGE,
415 |   })
416 | 
417 |   const goToPreviousPage = () => router.push({query: {page: page - 1}})
418 |   const goToNextPage = () => router.push({query: {page: page + 1}})
419 | 
420 |   return (
421 |     <div>
422 |       <ul>
423 |         {questions.map((question) => (
424 |           <li key={question.id}>
425 |             <Link href={`/questions/${question.id}`}>
426 |               <a>{question.name}</a>
427 |             </Link>
428 |           </li>
429 |         ))}
430 |       </ul>
431 | 
432 |       <button disabled={page === 0} onClick={goToPreviousPage}>
433 |         Previous
434 |       </button>
435 |       <button disabled={!hasMore} onClick={goToNextPage}>
436 |         Next
437 |       </button>
438 |     </div>
439 |   )
440 | }
441 | ```
442 | 
443 | 不过目前跑不通的！请记住我们创建的 `Question` 模型上面没有任何“name”字段。
444 | 要解决此问题，请替换 `question.name` 为 `question.text`。
445 | 
446 | ```diff
447 | // app/pages/questions/index.tsx
448 | 
449 | export const QuestionsList = () => {
450 |   const router = useRouter()
451 |   const page = Number(router.query.page) || 0
452 |   const [{questions, hasMore}] = usePaginatedQuery(getQuestions, {
453 |     orderBy: {id: "asc"},
454 |     skip: ITEMS_PER_PAGE * page,
455 |     take: ITEMS_PER_PAGE,
456 |   })
457 | 
458 |   const goToPreviousPage = () => router.push({query: {page: page - 1}})
459 |   const goToNextPage = () => router.push({query: {page: page + 1}})
460 | 
461 |   return (
462 |     <div>
463 |       <ul>
464 |         {questions.map((question) => (
465 |           <li key={question.id}>
466 |             <Link href={`/questions/${question.id}`}>
467 | -              <a>{question.name}</a>
468 | +              <a>{question.text}</a>
469 |             </Link>
470 |           </li>
471 |         ))}
472 |       </ul>
473 | 
474 |       <button disabled={page === 0} onClick={goToPreviousPage}>
475 |         Previous
476 |       </button>
477 |       <button disabled={!hasMore} onClick={goToNextPage}>
478 |         Next
479 |       </button>
480 |     </div>
481 |   )
482 | }
483 | ```
484 | 
485 | 接下来，我们将类似的修复方法应用于 `app/questions/components/QuestionForm.tsx` 中。在表单提交中，将 `LabeledTextField` 中 `name` 变为 `text`。
486 | 
487 | ```diff
488 | export function QuestionForm<S extends z.ZodType<any, any>>(
489 |   props: FormProps<S>,
490 | ) {
491 |   return (
492 |     <Form<S> {...props}>
493 | -     <LabeledTextField name="name" label="Name" placeholder="Name" />
494 | +     <LabeledTextField name="text" label="Text" placeholder="Text" />
495 |     </Form>
496 |   )
497 | }
498 | ```
499 | 
500 | #### `createQuestion` mutation
501 | 
502 | 在 `app/questions/mutations/createQuestion.ts` 中，我们需要更新 `CreateQuestion` zod 验证模式，使用 `text` 而不是 `name`。
503 | 
504 | ```diff
505 | // app/questions/mutations/createQuestion.ts
506 | 
507 | const CreateQuestion = z
508 |   .object({
509 | -   name: z.string(),
510 | +   text: z.string(),
511 |   })
512 |   .nonstrict()
513 | // ...
514 | ```
515 | 
516 | #### `updateQuestion` mutation
517 | 
518 | 在 `app/questions/mutations/updateQuestion.ts` 中，我们需要更新 `UpdateQuestion` zod 验证模式，使用 `text` 而不是 `name`。
519 | 
520 | ```diff
521 | // app/questions/mutations/updateQuestion.ts
522 | 
523 | const UpdateQuestion = z
524 |   .object({
525 |     id: z.number(),
526 | -   name: z.string(),
527 | +   text: z.string(),
528 |   })
529 |   .nonstrict()
530 | // ...
531 | ```
532 | 
533 | #### `deleteQuestion` mutation
534 | 
535 | Prisma 尚不支持“级联删除”。在本教程的上下文中，这意味着它在删除 `Question` 时不会删除相关的 `Choice`数据。我们需要临时改动生成的 `deleteQuestion` mutation，以便手动做这件事。在文本编辑框中打开 `app/questions/mutations/deleteQuestion.ts` 并将以下内容添加到函数主体的顶
536 | 部。
537 | 
538 | ```typescript
539 | await db.choice.deleteMany({where: {questionId: id}})
540 | ```
541 | 
542 | 最终的效果应该为：
543 | 
544 | ```diff
545 | // app/questions/mutations/deleteQuestion.ts
546 | 
547 | export default resolver.pipe(
548 |   resolver.zod(DeleteQuestion),
549 |   resolver.authorize(),
550 |   async ({id}) => {
551 | +   await db.choice.deleteMany({where: {questionId: id}})
552 |     const question = await db.question.deleteMany({where: {id}})
553 | 
554 |     return question
555 |   },
556 | )
557 | ```
558 | 
559 | 现在，此 mutation 将在删除问题本身之前，删除与问题相关的选择。
560 | 
561 | #### 现在尝试创建、更新和删除问题
562 | 
563 | 太棒了！现在确保你的程序正常运行。否则在你的终端中执行 `blitz dev`，然后访问 `localhost:3000/questions`。尝试创建问题并编辑、删除它们。
564 | 
565 | ### 在问题表格中添加选择项
566 | 
567 | 到目前为止，你做的很棒！我们要做的下一件事是在我们的问题中添加选择。在你的编辑器中打开 `app/questions/components/QuestionForm.tsx`。
568 | 
569 | 添加另外三个 `<LabeledTextField>` 组件作为选择。
570 | 
571 | ```diff
572 | export function QuestionForm<S extends z.ZodType<any, any>>(
573 |   props: FormProps<S>,
574 | ) {
575 |   return (
576 |     <Form<S> {...props}>
577 |       <LabeledTextField name="text" label="Text" placeholder="Text" />
578 | +     <LabeledTextField name="choices.0.text" label="Choice 1" />
579 | +     <LabeledTextField name="choices.1.text" label="Choice 2" />
580 | +     <LabeledTextField name="choices.2.text" label="Choice 3" />
581 |     </Form>
582 |   )
583 | }
584 | ```
585 | 
586 | 现在打开 `app/pages/questions/new.tsx` 并设置 `initialValues` 为如下：
587 | 
588 | ```diff
589 |       <QuestionForm
590 |         submitText="Create Question"
591 | -       // initialValues={{ }}
592 | +       initialValues={{choices: []}}
593 |         onSubmit={async (values) => {
594 |           try {
595 |             const question = await createQuestionMutation(values)
596 |             router.push(`/questions/${question.id}`)
597 |           } catch (error) {
598 |             console.error(error)
599 |             return {
600 |               [FORM_ERROR]: error.toString(),
601 |             }
602 |           }
603 |         }}
604 |       />
605 | ```
606 | 
607 | 接下来打开 `app/questions/mutations/createQuestion.ts` 并更新 zod 模式，来让 mutation 接收 choice 数据。而且我们还需要更新 `db.question.create` 调用，以便 choice 也可以被创建。
608 | 
609 | ```diff
610 | // app/questions/mutations/createQuestion.ts
611 | 
612 | const CreateQuestion = z
613 |   .object({
614 |     text: z.string(),
615 | +   choices: z.array(z.object({text: z.string()})),
616 |   })
617 |   .nonstrict()
618 | 
619 | export default resolver.pipe(
620 |   resolver.zod(CreateQuestion),
621 |   resolver.authorize(),
622 |   async (input) => {
623 | -   const question = await db.question.create({data: input})
624 | +   const question = await db.question.create({
625 | +     data: {
626 | +       ...input,
627 | +       choices: {create: input.choices},
628 | +     },
629 | +   })
630 | 
631 |     return question
632 |   },
633 | )
634 | ```
635 | 
636 | #### 试试看
637 | 
638 | 现在你可以转到 `localhost:3000/questions/new` 并创建一个带有选择的新问题！
639 | 
640 | ### 列出选择
641 | 
642 | 该轻松一下了。返回浏览器中的 `localhost:3000/questions` 并查看你创建的所有问题。让我们在这些问题下列出相关的选择如何？首先，我们需要自定义问题查询函数。在 Prisma 中，你需要手动让客户端知道你需要查询的嵌套关系，将你的 `getQuestion.ts` 和 `getQuestions.ts` 文件更改为如下所示：
643 | 
644 | ```diff
645 | // app/questions/queries/getQuestion.ts
646 | 
647 | const GetQuestion = z.object({
648 |   // This accepts type of undefined, but is required at runtime
649 |   id: z.number().optional().refine(Boolean, "Required"),
650 | })
651 | 
652 | export default resolver.pipe(
653 |   resolver.zod(GetQuestion),
654 |   resolver.authorize(),
655 |   async ({id}) => {
656 | -   const question = await db.question.findFirst({where: {id}})
657 | +   const question = await db.question.findFirst({
658 | +     where: {id},
659 | +     include: {choices: true},
660 | +   })
661 | 
662 |     if (!question) throw new NotFoundError()
663 | 
664 |     return question
665 |   },
666 | )
667 | ```
668 | 
669 | ```diff
670 | // app/questions/queries/getQuestions.ts
671 | 
672 | interface GetQuestionsInput
673 |   extends Pick<
674 |     Prisma.QuestionFindManyArgs,
675 |     "where" | "orderBy" | "skip" | "take"
676 |   > {}
677 | 
678 | export default resolver.pipe(
679 |   resolver.authorize(),
680 |   async ({where, orderBy, skip = 0, take = 100}: GetQuestionsInput) => {
681 |     const {items: questions, hasMore, nextPage, count} = await paginate({
682 |       skip,
683 |       take,
684 |       count: () => db.question.count({where}),
685 |       query: (paginateArgs) =>
686 |         db.question.findMany({
687 |           ...paginateArgs,
688 |           where,
689 |           orderBy,
690 | +         include: {choices: true},
691 |         }),
692 |     })
693 | 
694 |     return {
695 |       questions,
696 |       nextPage,
697 |       hasMore,
698 |       count,
699 |     }
700 |   },
701 | )
702 | ```
703 | 
704 | 现在在浏览器中跳回我们主要的 Question 页面 (`app/pages/questions/index.tsx`)，我们可以列出每个问题的选择。并将此代码添加到我们 `QuestionsList` 中的 `Link` 下：
705 | 
706 | ```diff
707 | // app/pages/questions/index.tsx
708 | 
709 | // ...
710 | {
711 |   questions.map((question) => (
712 |     <li key={question.id}>
713 |       <Link href={`/questions/${question.id}`}>
714 |         <a>{question.text}</a>
715 |       </Link>
716 | +     <ul>
717 | +       {question.choices.map((choice) => (
718 | +         <li key={choice.id}>
719 | +           {choice.text} - {choice.votes} votes
720 | +         </li>
721 | +       ))}
722 | +     </ul>
723 |     </li>
724 |   ))
725 | }
726 | // ...
727 | ```
728 | 
729 | 现在在浏览器中访问 `/questions` 路由。**神奇吧！**
730 | 
731 | ### 让我们允许用户对这些问题投票！
732 | 
733 | 在浏览器中打开 `app/pages/questions/[questionId].tsx`。首先，我们将对该页面进行一些改造。
734 | 
735 | 1. 替换 `<h1>Question {question.id}</h1>` 为 `<h1>{question.text}</h1>`.
736 | 1. 删除 `pre` 元素，并将如下复制到之前写的选择列表中：
737 | 
738 | ```jsx
739 | <ul>
740 |   {question.choices.map((choice) => (
741 |     <li key={choice.id}>
742 |       {choice.text} - {choice.votes} votes
743 |     </li>
744 |   ))}
745 | </ul>
746 | ```
747 | 
748 | 如果返回浏览器，页面目前看起来像这样！
749 | 
750 | ![](https://cdn.nlark.com/yuque/0/2021/png/86548/1616475118256-6e625fe9-db7f-44ec-9a07-68a3eced32c7.png#align=left&display=inline&height=285&margin=%5Bobject%20Object%5D&originHeight=570&originWidth=1134&size=0&status=done&style=none&width=567)
751 | 
752 | ### 现在是时候来增加投票功能！
753 | 
754 | 首先我们需要打开 `app/choices/mutations/updateChoice.ts`，更新 zod 模式，添加新增投票功能。
755 | 
756 | ```diff
757 | const UpdateChoice = z
758 |   .object({
759 |     id: z.number(),
760 | -   name: z.string(),
761 |   })
762 |   .nonstrict()
763 | 
764 | export default resolver.pipe(
765 |   resolver.zod(UpdateChoice),
766 |   resolver.authorize(),
767 |   async ({id, ...data}) => {
768 | -   const choice = await db.choice.update({where: {id}, data})
769 | +   const choice = await db.choice.update({
770 | +     where: {id},
771 | +     data: {votes: {increment: 1}},
772 | +   })
773 | 
774 |     return choice
775 |   },
776 | )
777 | ```
778 | 
779 | 返回到 `app/pages/questions/[questionId].tsx` 中进行如下更改：
780 | 
781 | 在我们的 `li` 中，新增一个如下的 `button`：
782 | 
783 | ```jsx
784 | <li key={choice.id}>
785 |   {choice.text} - {choice.votes} votes
786 |   <button>Vote</button>
787 | </li>
788 | ```
789 | 
790 | 接下来，导入我们更新的 `updateChoice` mutation，并在页面中创建 `handleVote` 函数。
791 | 
792 | ```diff
793 | // app/pages/questions/[questionId].tsx
794 | +import updateChoice from "app/choices/mutations/updateChoice"
795 | 
796 | //...
797 | 
798 | export const Question = () => {
799 |   const router = useRouter()
800 |   const questionId = useParam("questionId", "number")
801 |   const [deleteQuestionMutation] = useMutation(deleteQuestion)
802 |   const [question] = useQuery(getQuestion, {id: questionId})
803 | + const [updateChoiceMutation] = useMutation(updateChoice)
804 | +
805 | + const handleVote = async (id: number) => {
806 | +   try {
807 | +     await updateChoiceMutation({id})
808 | +     refetch()
809 | +   } catch (error) {
810 | +     alert("Error updating choice " + JSON.stringify(error, null, 2))
811 | +   }
812 | + }
813 | 
814 |   return (
815 | ```
816 | 
817 | 然后我们需要更新问题相关的 `useQuery` 调用以返回需要在 `handleVote` 内部使用的 `refetch` 函数。
818 | 
819 | ```diff
820 | // app/pages/questions/[questionId].tsx
821 | 
822 | //...
823 | - const [question] = useQuery(getQuestion, {id: questionId})
824 | + const [question, {refetch}] = useQuery(getQuestion, {id: questionId})
825 | //...
826 | ```
827 | 
828 | 最后，我们将告诉新的 `button` 来调用该函数！
829 | 
830 | ```jsx
831 | <button onClick={() => handleVote(choice.id)}>Vote</button>
832 | ```
833 | 
834 | 最终的 `Question` 组件应该是这个样子：
835 | 
836 | ```jsx
837 | export const Question = () => {
838 |   const router = useRouter()
839 |   const questionId = useParam("questionId", "number")
840 |   const [deleteQuestionMutation] = useMutation(deleteQuestion)
841 |   const [question, {refetch}] = useQuery(getQuestion, {id: questionId})
842 |   const [updateChoiceMutation] = useMutation(updateChoice)
843 | 
844 |   const handleVote = async (id: number) => {
845 |     try {
846 |       await updateChoiceMutation({id})
847 |       refetch()
848 |     } catch (error) {
849 |       alert("Error updating choice " + JSON.stringify(error, null, 2))
850 |     }
851 |   }
852 | 
853 |   return (
854 |     <>
855 |       <Head>
856 |         <title>Question {question.id}</title>
857 |       </Head>
858 | 
859 |       <div>
860 |         <h1>{question.text}</h1>
861 |         <ul>
862 |           {question.choices.map((choice) => (
863 |             <li key={choice.id}>
864 |               {choice.text} - {choice.votes} votes
865 |               <button onClick={() => handleVote(choice.id)}>Vote</button>
866 |             </li>
867 |           ))}
868 |         </ul>
869 | 
870 |         <Link href={`/questions/${question.id}/edit`}>
871 |           <a>Edit</a>
872 |         </Link>
873 | 
874 |         <button
875 |           type="button"
876 |           onClick={async () => {
877 |             if (window.confirm("This will be deleted")) {
878 |               await deleteQuestionMutation({id: question.id})
879 |               router.push("/questions")
880 |             }
881 |           }}
882 |           style={{marginLeft: "0.5rem"}}
883 |         >
884 |           Delete
885 |         </button>
886 |       </div>
887 |     </>
888 |   )
889 | }
890 | ```
891 | 
892 | ### 最后，让我们支持编辑某问题下的一个选择
893 | 
894 | 如果单击现有问题之一上的“编辑”按钮，你将看到它使用与创建问题相同的形式。至
895 | 此，该部分已经完成！我们只需要更新我们的 mutation。
896 | 
897 | 打开 `app/questions/mutations/updateQuestion.ts` 并进行如下改动：
898 | 
899 | ```diff
900 | // app/questions/mutations/updateQuestion.ts
901 | import {resolver} from "blitz"
902 | import db from "db"
903 | import * as z from "zod"
904 | 
905 | const UpdateQuestion = z
906 |   .object({
907 |     id: z.number(),
908 |     text: z.string(),
909 | +   choices: z.array(
910 | +     z.object({id: z.number().optional(), text: z.string()}).nonstrict(),
911 | +   ),
912 |   })
913 |   .nonstrict()
914 | 
915 | export default resolver.pipe(
916 |   resolver.zod(UpdateQuestion),
917 |   resolver.authorize(),
918 |   async ({id, ...data}) => {
919 | -   const question = await db.question.update({where: {id}, data})
920 | +   const question = await db.question.update({
921 | +     where: {id},
922 | +     data: {
923 | +       ...data,
924 | +       choices: {
925 | +         upsert: data.choices.map((choice) => ({
926 | +           // Appears to be a prisma bug,
927 | +           // because `|| 0` shouldn't be needed
928 | +           where: {id: choice.id || 0},
929 | +           create: {text: choice.text},
930 | +           update: {text: choice.text},
931 | +         })),
932 | +       },
933 | +     },
934 | +   })
935 | 
936 |     return question
937 |   },
938 | )
939 | ```
940 | 
941 | `[upsert](https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#upsert)` 是一种特殊的操作，表示“如果存在此项目，请对其进行更新。否则创建它”。这对于
942 | 当前情况是完美的，因为我们不需要用户在创建问题时同时添加三个选择。所以如果
943 | 用户通过编辑问题添加另一个选择，则将在此处创建它。
944 | 
945 | ### 结尾
946 | 
947 | 🥳 恭喜！你创建了自己的 Blitz 应用！祝你玩得开心，也欢迎与你的朋友分享。现在，你已经完成了本教程，为什么不尝试使你的投票应用变得更好呢？你可以尝试：
948 | 
949 | - 添加样式 (提示, 试试 `blitz install tailwind` 或 `blitz install chakra-ui`)
950 | - 显示更多有关选票的统计信息
951 | - 在 Render 或 Vercel 上实时部署。
952 | 
953 | 如果你想与全球 Blitz 社区分享你的项目，没有比 Discord 更好的地方了。
954 | 
955 | 访问 [discord.blitzjs.com](https://discord.blitzjs.com)。然后，将连接发布到 **#built-with-blitz** 频道来与所有人共享！
956 | 
957 | ## 译者结语
958 | 
959 | 本文内容属于 [Blitz.js 官方文档](https://blitzjs.com/docs) - 简介章节的前半部分。总共十四个章节（简介、社区、基础、页面、路由、权限、数据库、Queries 和 Mutations、后端架构、部署、配方、配置、CLI 和模板）。未来不定期翻译其余章节，也可能会原创一些文章。
960 | 
961 | 《[Blitz.js + React 全栈开发手册](https://github.com/hylerrix/blitzjs-tutorial)》系列专注探索 Blitz.js + React 全栈应用开发，原文翻译内容会同步更新到 [Blitz.js 中文仓库](https://github.com/blitz-js/zh-hans.blitzjs.com) 上。欢迎 Star、Watch 或关注公众号 (@ningowood) 来及时接收消息。
962 | 
963 | > 2021 © [https://github.com/hylerrix/blitzjs-tutorial](https://github.com/hylerrix/blitzjs-tutorial)
964 | 


--------------------------------------------------------------------------------