使用 TypeScript
有关使用 TypeScript 配置 Expo 项目的深入指南。
Expo 对 TypeScript 有一流的支持。Expo SDK 的 JavaScript 接口是用 TypeScript 编写的。
¥Expo has first-class support for TypeScript. The JavaScript interface of Expo SDK is written in TypeScript.
本指南提供了一种快速开始新项目的方法,以及将现有的基于 JavaScript 的 Expo 项目迁移到使用 TypeScript 的步骤。
¥This guide provides a quick way to get started for a new project and also steps to migrate your existing JavaScript based Expo project to use TypeScript.
快速开始
¥Quick start
要创建新项目,请使用包含基本 TypeScript 配置、示例代码和基本导航结构的默认模板:
¥To create a new project, use the default template which includes base TypeScript configuration, example code, and basic navigation structure:
-
npx create-expo-app@latest
使用上述命令创建新项目后,请确保遵循以下说明:
¥After you create a new project using the command above, make sure to follow instructions from:
-
设置你的环境 提供设置本地开发环境所需的步骤。
¥Set up your environment which provides required steps for setting local development environment.
-
开始开发 提供有关触发开发服务器、文件结构和其他功能的详细信息。
¥Start developing which provides information on triggering a development server, file structure, and details about other features.
迁移现有 JavaScript 项目
¥Migrating existing JavaScript project
要迁移你现有的基于 JavaScript 的项目以使用 TypeScript,请按照以下说明操作:
¥To migrate your existing JavaScript based project to use TypeScript, follow the instructions below:
1
Rename files to use .tsx or .ts extension
Rename files to convert them to TypeScript. For example, start with the root component file such as App.js and rename it to App.tsx:
-
mv App.js App.tsx
Tip: Use the .tsx extension if the file includes React components (JSX). If the file does not include any JSX, you can use the .ts file extension.
2
Install required development dependencies
To install required devDependencies
such as typescript
and @types/react
in package.json:
-
npx expo install typescript @types/react --dev
-
npx expo install typescript @types/react "--" --dev
Alternatively, runnpx expo start
command to installtypescript
and@types/react
dev dependencies.
3
Add base configuration with tsconfig.json
A project's tsconfig.json should extend expo/tsconfig.base
by default. You can automatically generate a tsconfig.json file by running the command:
-
npx expo customize tsconfig.json
The default configuration in tsconfig.json is user-friendly and encourages adoption. If you prefer strict type checking and reduce the chances of runtime errors, enable strict
under compilerOptions
:
{
"extends": "expo/tsconfig.base",
"compilerOptions": {
"strict": true
}
}
4
Path aliases (Optional)
Expo CLI supports path aliases in tsconfig.json automatically. It allows importing modules with custom aliases instead of relative paths.
For example, to import Button
component from src/components/Button.tsx using the alias @/components/Button, add the alias @/*
in tsconfig.json and set it to the src directory:
{
"extends": "expo/tsconfig.base",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
Disable path aliases for SDK 50 and above
tsconfigPaths
is enabled by default which allows you to set path aliases. You can disable it by setting tsconfigPaths
to false
in the project's app config:
{
"expo": {
"experiments": {
"tsconfigPaths": false
}
}
}
Considerations
When using path aliases, consider the following:
- Restart Expo CLI after modifying tsconfig.json to update path aliases. You don't need to clear the Metro cache when the aliases change.
- If not using TypeScript, jsconfig.json can serve as an alternative to tsconfig.json.
- Path aliases add additional resolution time when defined.
- Path aliases are only supported by Metro (including Metro web) and not by the deprecated
@expo/webpack-config
. - Bare projects require additional setup for this feature. See the Metro setup guide for more information.
5
Absolute imports (Optional)
To enable absolute imports from a project's root directory, define compilerOptions.baseUrl
the tsconfig.json file:
{
"extends": "expo/tsconfig.base",
"compilerOptions": {
"baseUrl": "./"
}
}
For example, setting the above configuration allows importing Button
component from the path src/components/Button:
import Button from 'src/components/Button';
Considerations
When using absolute imports, consider the following:
compilerOptions.paths
are resolved relative to thecompilerOptions.baseUrl
if it is defined, otherwise they're resolved against the project root directory.compilerOptions.baseUrl
is resolved before node modules. This means if you have a file named./path.ts
, it can be imported instead of a node module namedpath
.- Restarting Expo CLI is necessary to update
compilerOptions.baseUrl
after modifying the tsconfig.json. - If you're not using TypeScript, jsconfig.json can serve as an alternative to tsconfig.json.
- Absolute imports are only supported by Metro (including Metro web) and not by
@expo/webpack-config
. - Bare projects require additional setup for this feature. See the versioned Metro setup guide for more information.
Type generation
Some Expo libraries provide both static types and type generation capabilities. These types are automatically generated when the project builds or by running the npx expo customize tsconfig.json
command.
TypeScript for project's config files
Additional setup is required to use TypeScript for configuration files such as metro.config.js or app.config.js. You need to utilize ts-node
require hook to import TypeScript files within your JS config file. This hook allows TypeScript imports while keeping the root file as JavaScript.
-
npx expo install ts-node --dev
-
npx expo install ts-node "--" --dev
metro.config.js
Update metro.config.js to require metro.config.ts file:
require('ts-node/register');
module.exports = require('./metro.config.ts');
Update metro.config.ts file with your project's metro configuration:
import { getDefaultConfig } from 'expo/metro-config';
const config = getDefaultConfig(__dirname);
module.exports = config;
Deprecated: webpack.config.js
Install the @expo/webpack-config
package.
require('ts-node/register');
module.exports = require('./webpack.config.ts');
import createExpoWebpackConfigAsync from '@expo/webpack-config/webpack';
import { Arguments, Environment } from '@expo/webpack-config/webpack/types';
module.exports = async function (env: Environment, argv: Arguments) {
const config = await createExpoWebpackConfigAsync(env, argv);
// Customize the config before returning it.
return config;
};
app.config.js
默认支持 app.config.ts。但是,它不支持外部 TypeScript 模块或 tsconfig.json 自定义。你可以使用以下方法来获得更全面的 TypeScript 设置:
¥app.config.ts is supported by default. However, it doesn't support external TypeScript modules, or tsconfig.json customization. You can use the following approach to get a more comprehensive TypeScript setup:
import 'ts-node/register'; // Add this to import TypeScript files
import { ExpoConfig } from 'expo/config';
const config: ExpoConfig = {
name: 'my-app',
slug: 'my-app',
};
export default config;
其他 TypeScript 功能
¥Other TypeScript features
某些语言功能可能需要额外的配置。例如,如果你想使用装饰器,则需要添加 experimentalDecorators
选项。有关可用属性的更多信息,请参阅 TypeScript 编译器选项 文档。
¥Some language features may require additional configuration. For example, if you want to use decorators you'll need to add the experimentalDecorators
option. For more information on the available properties see the TypeScript compiler options documentation.
了解如何使用 TypeScript
¥Learn how to use TypeScript
官方 TypeScript 手册 是开始学习 TypeScript 的好地方。
¥A good place to start learning TypeScript is the official TypeScript Handbook.
对于 TypeScript 和 React 组件,我们建议参考 React TypeScript 备忘单 来了解如何在各种常见情况下键入 React 组件。
¥For TypeScript and React components, we recommend referring to the React TypeScript CheatSheet to learn how to type your React components in a variety of common situations.