Back to Details

expo-examples

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Expo Examples

Expo 示例

expo/examples is Expo's official library of ~70 integration examples — directories named 
with-<library>
(e.g. 
with-stripe
, 
with-maps
), each built around one library or service. These are not full apps: they're managed projects (no 
ios/
/
android/
dirs — native setup is via config plugins), and the typical one is a single screen of ~100–200 lines. Mine them for the canonical integration pattern — the dependency set, 
app.json
config plugins, and minimal wiring Expo maintains against the current SDK — and adapt that into the user's app. Don't expect to lift an application architecture from them.
Reach for an example before hand-rolling an integration. (Kinds — full-stack, showcases, starters — are noted in 
./references/catalog.md
.)
expo/examples 是 Expo 官方的集成示例库，包含约70个集成示例——每个示例目录命名为 
with-<library>
（例如 
with-stripe
、
with-maps
），围绕单个库或服务构建。这些并非完整应用：它们是托管式项目（没有 
ios/
/
android/
目录——原生配置通过 config plugins 实现），典型示例仅为一个约100-200行代码的单页面。你可以从中提取规范的集成模式——Expo 针对当前 SDK 维护的依赖集、
app.json
配置插件以及最简实现逻辑，并将其适配到你的应用中。不要指望从这些示例中获取完整的应用架构。
在手动实现集成前，先参考示例。（示例类型——全栈、展示、启动模板等——在 
./references/catalog.md
中有标注。）

Two modes

两种使用模式

  1. Inspiration / adapt (most common) — the user already has a project. Find the matching example, read its key files, and apply the pattern to their code.
  2. Scaffold — greenfield. Start a fresh project directly from the example.
  1. 参考/适配（最常见）——用户已有项目。找到匹配的示例，阅读其关键文件，将模式应用到自己的代码中。
  2. 脚手架——从零开始。直接从示例创建全新项目。

Workflow

工作流程

1. Find the right example

1. 找到合适的示例

Map the user's need to an example name (e.g. payments → 
with-stripe
, auth → 
with-clerk
). 
./references/catalog.md
is a categorized snapshot for fast triage — but it drifts, so confirm against the live list:
bash
undefined
将用户需求映射到示例名称（例如支付 → 
with-stripe
，身份验证 → 
with-clerk
）。
./references/catalog.md
是分类快照，可快速筛选——但内容可能滞后，因此需对照实时列表确认：
bash
undefined

Live example names:

实时示例名称：

gh api repos/expo/examples/contents --jq '.[] | select(.type=="dir" and (.name|startswith(".")|not)) | .name'
gh api repos/expo/examples/contents --jq '.[] | select(.type=="dir" and (.name|startswith(".")|not)) | .name'

Aliases (renamed) + deprecated (dead/moved) examples — check before recommending:

别名（已重命名）+ 已弃用（失效/迁移）示例——推荐前请检查：

gh api repos/expo/examples/contents/meta.json --jq '.content' | base64 -d

`meta.json` is the source of truth for what's renamed or dead (deprecated examples are removed from the repo tree but still listed here, each with a `message`). If an example is in its `deprecated` map, don't recommend it — follow the `message` to the modern path. If it's in `aliases`, use the `destination`.
gh api repos/expo/examples/contents/meta.json --jq '.content' | base64 -d

`meta.json` 是重命名或失效示例的权威来源（已弃用示例已从仓库目录移除，但仍会在此列出，并附带 `message`）。如果示例在 `deprecated` 映射中，请勿推荐——按照 `message` 中的指引使用最新方案。如果在 `aliases` 中，请使用 `destination` 指定的名称。

2a. Inspiration mode — study without touching the user's project

2a. 参考模式——无需改动用户项目即可学习

The common case: the user already has an app and wants to see how Expo does something. Read the example as reference and apply the patterns by hand — never scaffold an example on top of their project.
First, list the whole example in one call. Integration code is often nested (e.g. Stripe's server routes live in 
app/api/
), so a one-level listing misses the important files:
bash
gh api 'repos/expo/examples/git/trees/master?recursive=1' \
  --jq '.tree[].path | select(startswith("with-stripe/"))'
Then read the high-signal files first: 
README.md
(setup) → 
package.json
(deps) → 
app.json
(config plugins / permissions) → the integration code the manifest revealed → 
.env
(required secrets). Per file:
bash
gh api repos/expo/examples/contents/with-stripe/utils/stripe-server.ts --jq '.content' | base64 -d
常见场景：用户已有应用，想了解 Expo 如何实现某功能。将示例作为参考资料阅读，手动应用模式——切勿在用户项目上搭建示例脚手架。
**首先，一次性列出整个示例的所有文件。**集成代码通常嵌套（例如 Stripe 的服务器路由位于 
app/api/
），因此仅列出一级目录会遗漏重要文件：
bash
gh api 'repos/expo/examples/git/trees/master?recursive=1' \
  --jq '.tree[].path | select(startswith("with-stripe/"))'
然后优先阅读高价值文件： 
README.md
（设置说明）→ 
package.json
（依赖）→ 
app.json
（配置插件/权限）→ 清单中显示的集成代码 → 
.env
（所需密钥）。读取单个文件的命令：
bash
gh api repos/expo/examples/contents/with-stripe/utils/stripe-server.ts --jq '.content' | base64 -d

No gh? Raw URL (branch is master):

没有 gh 工具？使用原始 URL（分支为 master）：

curl -s https://raw.githubusercontent.com/expo/examples/master/with-stripe/utils/stripe-server.ts

**Reading more than a couple of files?** Many integrations are spread across server routes, a client provider, and config (Stripe is). Skip the per-file calls — pull the whole example into a **throwaway/gitignored dir (not the user's project)** and read it freely with Grep/Read, then apply by hand:

```bash
npx degit expo/examples/with-stripe /tmp/expo-ref/with-stripe   # clean copy, no git history
curl -s https://raw.githubusercontent.com/expo/examples/master/with-stripe/utils/stripe-server.ts

**需要阅读多个文件？**许多集成代码分散在服务器路由、客户端提供者和配置中（例如 Stripe）。跳过逐个文件调用——将整个示例拉取到一个**临时/已忽略 git 的目录（不要放在用户项目中）**，使用 Grep/Read 自由阅读，然后手动应用：

```bash
npx degit expo/examples/with-stripe /tmp/expo-ref/with-stripe   # 干净副本，无 git 历史

fallback without degit (sparse-checkout, no full ~64 MB clone):

没有 degit 的替代方案（稀疏检出，无需克隆完整的 ~64 MB 仓库）：

git clone --depth 1 --filter=blob:none --sparse https://github.com/expo/examples.git /tmp/expo-ref/examples
&& (cd /tmp/expo-ref/examples && git sparse-checkout set with-stripe)

Read from there with Grep/Read; delete the scratch dir when done.
git clone --depth 1 --filter=blob:none --sparse https://github.com/expo/examples.git /tmp/expo-ref/examples
&& (cd /tmp/expo-ref/examples && git sparse-checkout set with-stripe)

在此目录中使用 Grep/Read 阅读；完成后删除临时目录。

2b. Scaffold mode — new project from an example

2b. 脚手架模式——从示例创建新项目

bash
npx create-expo --example with-stripe   # short form:  npx create-expo -e with-stripe
bun create expo --example with-stripe    # with bun
bash
npx create-expo --example with-stripe   # 简写形式：  npx create-expo -e with-stripe
bun create expo --example with-stripe    # 使用 bun

3. Adapt into the user's app — non-destructively (critical)

3. 适配到用户应用——非破坏性操作（至关重要）

When the user already has an app, add only what the example introduces; never overwrite their setup.
  • Version-align — don't copy pinned versions. Examples track the latest SDK, so their 
    package.json
    pins won't match an older project. Add only the missing deps with 
    npx expo install <pkg>
    (it resolves SDK-correct versions) instead of copying exact versions.
  • Merge config, don't replace it. Add only the 
    app.json
    /
    app.config.*
    plugins and permissions the example introduces that the user lacks — keep their existing config block intact.
  • Port the integration code.
  • Recreate env vars from the example's 
    .env
    shape — it holds placeholders, never working secrets.
Done when the integration code is ported and every dependency, config plugin, permission, and env var it needs is accounted for in the user's app — not when it merely looks wired up.
当用户已有应用时，仅添加示例引入的内容；切勿覆盖现有配置。
  • 版本对齐——不要复制固定版本。示例跟踪最新SDK，因此其 
    package.json
    中的固定版本可能与旧项目不匹配。仅使用 
    npx expo install <pkg>
    添加缺失的依赖（它会解析与 SDK 兼容的版本），而非复制精确版本。
  • **合并配置，不要替换。**仅添加示例中用户缺少的 
    app.json
    /
    app.config.*
    插件和权限——保留现有配置块不变。
  • 移植集成代码。
  • 重新创建环境变量——示例的 
    .env
    仅包含占位符，切勿使用有效密钥。
完成标志：集成代码已移植，且用户应用中已包含所需的所有依赖、配置插件、权限和环境变量——而非仅实现了表面上的连接。

Gotchas

注意事项

  • Default branch is 
    master
    ,     not 
    main
    (matters for raw URLs and sparse checkout).
  • Single-click deploy. Every example has a launch URL: 
    https://launch.expo.dev/?github=https://github.com/expo/examples/tree/master/<example>
    .
  • 默认分支是 
    master
    ，而非 
    main
    （对原始 URL 和稀疏检出很重要）。
  • **一键部署。**每个示例都有启动 URL：
    https://launch.expo.dev/?github=https://github.com/expo/examples/tree/master/<example>
    。

Related skills

相关技能

  • Tailwind / NativeWind styling → 
    expo-tailwind-setup
  • Native UI components → 
    building-native-ui
  • Authoring a native module → 
    expo-module
  • Upgrade the SDK before adopting a latest-SDK example → 
    upgrading-expo
  • Tailwind / NativeWind 样式 → 
    expo-tailwind-setup
  • 原生 UI 组件 → 
    building-native-ui
  • 编写原生模块 → 
    expo-module
  • 在采用最新 SDK 示例前升级 SDK → 
    upgrading-expo

References

参考资料

  • ./references/catalog.md
    — categorized snapshot of the example library for fast triage.
  • ./references/catalog.md
    ——示例库的分类快照，用于快速筛选。