从 Create React App 迁移

本页介绍如何从 Create React App 迁移到 Parcel。

自动迁移

cra-to-parcel 是一个可以自动将未弹出的 Create React App 应用迁移到 Parcel 的脚本。要运行它，请 cd 进入您的项目，然后运行以下命令：

npx cra-to-parcel

这将迁移您的依赖、配置和源代码以使用 Parcel。请参阅下面的部分，了解更多详细信息，或者如果您更喜欢手动应用步骤。

如果在此过程中遇到任何问题，请在 Github 上提交 issue。

手动迁移

1. 迁移依赖

使用您的包管理器（如 npm/yarn/pnpm），删除 react-scripts 并添加 parcel。

npm rm react-scripts
npm install parcel --save-dev

接下来，在您的 package.json 中，将 react-scripts 替换为 parcel。您可以完全删除 "eject" 脚本。另外，添加一个指向 public/index.html 的 "source" 字段，这将是您应用的入口点。

package.json:

{
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "eject": "react-scripts eject"
  }
}

package.json:

{
  "source": "public/index.html",
  "scripts": {
    "start": "parcel",
    "build": "parcel build"
  }
}

2. 更新 public/index.html

在 public/index.html 中，将模板变量 %PUBLIC_URL% 替换为 .，以直接指向文件。

public/index.html:

<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />

public/index.html:

<link rel="icon" href="./favicon.ico" />

接下来，在 public/index.html 中添加一个指向 src/index.js 的 <script> 标签。它应该放在关闭的 </body> 元素之前。

public/index.html:

  <!-- ... -->
  <script type="module" src="../src/index.js"></script>
  </body>
</html>

3. 迁移 SVG 导入

如果您使用 Create React App 的 SVG 组件导入功能，请按照这些说明在 .parcelrc 中添加 @parcel/transformer-svg-jsx。

.parcelrc:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "jsx:*.svg": ["...", "@parcel/transformer-svg-jsx"],
    "jsx:*": ["..."]
  }
}

然后，转换导入语句以使用 jsx: 前缀：

src/SomeComponent.jsx:

import { ReactComponent as Logo } from './logo.svg';

public/index.html:

import Logo from 'jsx:./logo.svg';

不带 jsx: 前缀导入 SVG 将返回一个 URL，就像在 Create React App 中一样。

4. 迁移 GraphQL 导入

如果您使用 Create React App 的 GraphQL 导入功能，或其他 Babel 宏，您需要在 babel.config.json 配置文件中添加 babel-plugin-macros。

babel.config.json:

{
  "plugins": ["babel-plugin-macros"]
}

Parcel 开箱即用地支持其他 JavaScript 转译功能（如 JSX、TypeScript 和 Preset Env），因此它们不需要在 Babel 配置文件中。请参阅文档以获取更多信息。

5. 迁移 CSS

Parcel 开箱即用地支持 CSS、CSS 模块、SASS 和自动前缀。如果您使用 Create React App 的 @import-normalize 功能，您需要在 .postcssrc 配置中添加 postcss-normalize。

.postcssrc:

{
  "plugins": ["postcss-normalize"]
}

另外，如果您使用 Tailwind CSS，您需要在 .postcssrc 中添加 tailwindcss 插件。有关更多详细信息，请参见文档。

6. 迁移测试

接下来，您需要更新 "test" 脚本以直接运行 Jest。首先，安装所需的依赖：

npm install jest jest-watch-typeahead babel-jest babel-preset-react-app identity-obj-proxy --save-dev

然后，更新 package.json 中的 "test" 脚本：

package.json:

{
  "scripts": {
    "test": "react-scripts test"
  }
}

package.json:

{
  "scripts": {
    "test": "jest"
  }
}

现在创建以下文件：

jest.config.json:

{
  "roots": ["<rootDir>/src"],
  "collectCoverageFrom": ["src/**/*.{js,jsx,ts,tsx}", "!src/**/*.d.ts"],
  "setupFilesAfterEnv": ["<rootDir>/src/setupTests.js"],
  "testMatch": [
    "<rootDir>/src/**/__tests__/**/*.{js,jsx,ts,tsx}",
    "<rootDir>/src/**/*.{spec,test}.{js,jsx,ts,tsx}"
  ],
  "testEnvironment": "jsdom",
  "transform": {
    "^.+\\.(js|jsx|mjs|cjs|ts|tsx)$": "<rootDir>/config/jest/babelTransform.js",
    "^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)": "<rootDir>/config/jest/fileTransform.js"
  },
  "transformIgnorePatterns": [
    "[/\\\\]node_modules[/\\\\].+\\.(js|jsx|mjs|cjs|ts|tsx)$",
    "^.+\\.module\\.(css|sass|scss)$"
  ],
  "modulePaths": [],
  "moduleNameMapper": {
    "^react-native$": "react-native-web",
    "^.+\\.(css|sass|scss)$": "identity-obj-proxy",
    "^jsx:.+\\.svg": "<rootDir>/config/jest/SvgComponent.js"
  },
  "moduleFileExtensions": [
    "web.js",
    "js",
    "web.ts",
    "ts",
    "web.tsx",
    "tsx",
    "json",
    "web.jsx",
    "jsx",
    "node"
  ],
  "watchPlugins": [
    "jest-watch-typeahead/filename",
    "jest-watch-typeahead/testname"
  ],
  "resetMocks": true
}

config/babelTransform.js:

const babelJest = require("babel-jest").default;

module.exports = babelJest.createTransformer({
  presets: [
    [
      require.resolve("babel-preset-react-app"),
      {
        runtime: "automatic",
      },
    ],
  ],
  babelrc: false,
  configFile: false,
});

config/fileTransform.js:

const path = require("path").default;

module.exports = {
  process(src, filename) {
    const assetFilename = JSON.stringify(path.basename(filename));
    return `module.exports = ${assetFilename};`;
  },
};

config/SvgComponent.js:

export function SvgComponent() {
  return null;
}

7. 设置 eslint

Create React App 使用 Eslint 来检查您的代码。Parcel 默认不包含代码检查，但您可以在 package.json 中设置单独的 npm 脚本来运行它。

首先，安装所需的依赖：

npm install eslint eslint-config-react-app --save-dev

然后，在 package.json 中添加一个 "lint" 脚本：

package.json:

{
  "scripts": {
    "lint": "eslint src"
  }
}

要运行代码检查器，请运行 npm run lint。

8. 更新 .gitignore

在您的 .gitignore 文件中添加以下文件：

.parcel-cache
dist

9. 启动开发服务器

大功告成！现在您可以使用 npm start 启动开发服务器。在首次构建您的应用时，Parcel 可能会安装它需要的额外插件和依赖。

如果在此过程中遇到任何问题，请在 Github 上提交 issue。