docs

Expo Documentation

This is the public documentation forExpo,its SDK, client, and services (EAS). This documentation is built using Next.js and you can access it online athttps://docs.expo.dev/.

NoteContributors:Please make sure that you edit the docs in thepages/versions/unversionedfor SDK reference if you want your changes to apply to the next SDK version too!

Note If you are looking for Expo Documentation Writing Style guidelines, please referExpo Documentation Style Guide.

To run locally in development mode

Download a copy of this repository.

git clone https://github /expo/expo.git

Thencdinto thedocsdirectory and install dependencies with:

yarn

Then you can run the app with (make sure you have no server running on port3002):

yarn run dev

Now the documentation is running athttp://localhost:3002,and any changes you make to markdown or JavaScript files will automatically trigger reloads.

To run locally in production mode

yarn runexport
yarn run export-server

Edit Docs Content

All documentation-related content is inside thepagesdirectory. We write docs in markdown with the help of custom React components that provide additional functionality, such as embedding Snack examples, representing commands inside a terminal component and so on.

The documentation is divided into four main sections:

Home:Provides a guided path from starting a project from scratch to deploying it to app stores.
Guides:General purpose and fundamental guides that help you understand how Expo works and how to use it. This section also contains all EAS related documentation.
Reference:Detailed reference documentation for all Expo APIs and modules. All Expo SDK API docs are located underpages/versionsdirectory. We keep separate versions of documentation for each SDK version currently supported in Expo Go. SeeUpdate latest version of docsfor more information.
Learn:Tutorials and guides that help you learn how to use Expo and React Native.

Note We are currently in the process of moving our API documentation to being auto-generated usingexpotools'sGenerateDocsAPIDatacommand for some Expo libraries.

Metadata of a page

Each markdown page can be provided metadata in the heading, distinguished by:

---
metadata: goes here
---

These metadata items include:

title:Title of the page shown as the heading and in search results.
description:Description of the page shown in search results and open graph descriptions when the page is shared on social media sites.
hideFromSearch:Whether to hide the page from Algolia search results. Defaults tofalse.
hideInSidebar:Whether to hide this page from the sidebar. Defaults tofalse.
hideTOC:Whether to hide the table of contents (appears on the right sidebar). Defaults tofalse.
sidebar_title:The title of the page to display in the sidebar. Defaults to the page title.
maxHeadingDepth:The max level of headings shown in Table of Content on the right side. Defaults to3.

Edit Code

The docs are written with Next.js and TypeScript. If you need to make code changes, follow steps from theTo run locally in development modesection, then open a separate terminal and run the TypeScript compiler in watch mode — it will watch your code changes and notify you about errors.

yarn watch

When you are done, you should runprettierto format your code. Also, don't forget to run tests and linter before committing your changes.

yarn prettier
yarntest
yarn lint

Prose linter

We useValeto lint our docs for style and grammar based onExpo's writing style guide.

There are two ways you can use it:

Use Vale in VS Code (Recommended)

Open the doc file (*.mdx) that you are working on and you'll may see suggested lines (yellow squiggly) in VS Code editor.

Run the`lint-prose`script

In a terminal window, run theyarn run lint-prosescript frompackage.json.This will run Vale for all markdown files in thepagesdirectory.

Redirects

Server-side redirects

These redirects are limited in their expressiveness - you can map a path to another path, but no regular expressions are supported. See client-side redirects for more of that. Server-side redirects are re-created on each run ofdeploy.sh.

We currently do two client-side redirects, using meta tags withhttp-equiv= "refresh":

/->/versions/latest/
/versions->/versions/latest

This method is not great for accessibility and should be avoided where possible.

Client-side redirects

Use these for more complex rules than one-to-one path-to-path redirect mapping. For example, we use client-side redirects to strip the.htmlextension off, and to identify if the request is for a version of the documentation that we no longer support.

You can add your own client-side redirect rules incommon/error-utilities.ts.

Search

We use Algolia as a main search results provider for our docs. Besides the query, results are also filtered based on theversiontag which represents the user's current location. The tag is set in thecomponents/DocumentationPage.tsxhead.

Inui/components/CommandMenu/utils.ts,you can see thefacetFiltersset to[['version:none', 'version:{version}']].Translated to English, this means - search on all pages whereversionisnone,or the currently selected version. Here are the rules we use to set this tag:

all unversioned pages use the version tagnone,
all versioned pages use the SDK version (for example,v51.0.0orv50.0.0),
all pages withhideFromSearch: truefrontmatter entry don't have the version tag.

Currently, the base results for Expo docs are combined with other results from multiple sources, such as:

manually defined paths for Expo dashboard located inui/components/CommandMenu/expoEntries.ts,
public Algolia index for React Native website,
React Native directory public API, see the directoryREADME.mdfor more details.

Quirks

You can't have curly brace without quotes: `{}` ->{}.

Deployment

The docs are deployed automatically via a GitHub Action each time a PR with docs changes is merged tomain.

How-tos

Internal linking

If you need to link from one MDX file to another, please use the static/full path to this file (avoid relative links):

from:tutorial/button.mdx,to:introduction/expo.mdx->/introduction/expo
from:index.mdx,to:guides/errors.mdx#tracking-js-errors->/guides/errors/#tracking-javascript-errors

Validate all current links by runningyarn lint-linksscript.

Update latest version of docs

When we release a new SDK, we copy theunversioneddirectory, and rename it to the new version. Latest version of docs is read frompackage.jsonso make sure to update theversionkey there as well.

Make sure to also grab the upgrade instructions from the release notes blog post and put them inupgrading-expo-sdk-walkthrough.mdx.

That's all you need to do. Theversionsdirectory is listed on server start to find all available versions. The routes and navbar contents are automatically inferred from the directory structure withinversions.

Because the navbar is automatically generated from the directory structure, the default ordering of the links under each section is Alpha betical. However, for many sections, this is not ideal UX. So, if you wish to override the Alpha betical ordering, manipulate page titles inconstants/navigation.js.

Update API reference docs

The API reference docs are generated from the TypeScript source code.

This section walks through the process of updating documentation for an Expo package. Throughout this document, we will assume we want to update TypeDoc definitions of property insideexpo-constantsas an example.

For more information on how TypeDoc/JSDoc parses comments, seeDoc comments in TypeDoc documentation.

Prerequisites

Before proceeding, make sure you:

Haveexpo/repo cloned on your machine
Make sure toinstalldirenvand rundirenv allowat the root of theexpo/repo.
Have gone through the steps mentioned in"Download and Setup" in the contribution guideline.
Can runexpo/docsapplocally.
Can runet(Expotools)command locally.

Once you have made sure the development setup is ready, proceed to the next section:

Step 1: Update the package's TypeDoc

After you have identified which package docs you want to update, open a terminal window and navigate to that packages directory. For example:

#Navigate to expo-constants package directory inside expo/ repo
cdexpo/packages/expo-constants

Then, open.tsfile in your code editor/IDE where you want to make changes/updates.
Start the TypeScript build compilation in watch mode usingyarn buildin the terminal window.
Make the update. For example, we want to update the TypeDoc description ofexpoConfigproperty
- Inside thesrc/directory, openConstants.types.tsfile.
- Search forexpoConfigproperty. It has a current description as shown below:
```
/**
* The standard Expo confg object defined in `app.json` and `app.config.js` files. For both
* classic and modern manifests, whether they are embedded or remote.
*/
expoConfig:ExpoConfig|null;
```
In the above example, let's fix the typo by changingconfgtoconfig:

/**
* The standard app config object defined in `app.json` and `app.config.js` files. For both
* classic and modern manifests, whether they are embedded or remote.
*/
expoConfig:ExpoConfig|null;

Before moving to the next step, make sure to exit the "watch mode" by pressingCtrl + Cfrom the keyboard.

Step 2: Apply TypeDoc updates to expo/docs repo

Important

If you are fi xing issues in package's reference or after an SDK version is released, make sure to only update theunversionedreference of that package. This way the changes will be reflected in the next SDK version from themainbranch. Updating the reference for a specific SDK version requires updating that SDK's branch.

In the terminal window and run the following command with to generate the JSON data file for the package (which is stored at the locationexpo/docs/public/static/data/[SDK-VERSION])

Read theNOTEin the below snippet for updating the docs forunversioned:

et generate-docs-api-data --packageName expo-constants

#### NOTE ####
#To update a specific SDK reference, run the command by mentioning the SDK version
et gdad -p expo-constants --sdk 51

#For more information about et command, run: et gdad --help

Why updateunversioneddocs?If these are new changes/updates, apply them tounversionedto make sure that those changes are part of the next SDK version.

Step 3: See the changes in the docs repo

Now, in the terminal window, navigate toexpo/docsrepo and run the commandyarn run devto see the changes applied

Openhttp://localhost:3002/in the browser and go to the API doc to see the changes you have made. Make sure to select the right SDK version to see the changes in the left sidebar.

Tips

Disable changelog

After making changes, when you are opening the PR, consider addingin the PR description if the changes you are making are docs-related changes (such as updating the field description or fi xing a typo, and so on).

This will make sure that the ExpoBot on GitHub will not complain about updating the package's changelog (some of these changes, as described above, are not worth mentioning in the changelog).

Use the correct package name

Some of the packages have documentation spread over multiple pages. For example,expo-avpackage has a separate base interface, and some of the information is separated intoAudioandVideocomponents. For such packages, always make sure to check thename of the packageforetcommand.

Sync app.json/app.config.js with the schema

To render the app.json / app.config.js properties table, we currently store a local copy of the appropriate version of the schema.

If the schema is updated, to sync and rewrite our local copy, runyarn run schema-sync <SDK version integer>oryarn run schema-sync unversioned.

Add images and assets

You can add images and assets to thepublic/staticdirectory. They'll be served by the production and staging servers atstatic.

Add videos

Record the video using QuickTime
Installffmpeg(brew install ffmpeg)
Runffmpeg -i your-video-name.mov -vcodec h264 -acodec mp2 your-video-name.mp4to convert to mp4.
If the width of the video is larger than ~1200px, then run this to shrink it:ffmpeg -i your-video.mp4 -filter:v scale= "1280:trunc(ow/a/2)*2" your-video-smaller.mp4
Put the video in the appropriate location inpublic/static/videosand use it in your docs page MDX like this:

import{ContentSpotlight}from'~/ui/components/ContentSpotlight';

// Change the path to point to the relative path to your video from within the `static/videos` directory
<ContentSpotlightfile="guides/color-schemes.mp4"/>;

Add code block

Code blocks are a great way to add code snippets to our docs. We leverage the usual code block Markdown syntax, but it's expanded to support code block titles and additional params.

{/*For plain code block the syntax is unchanged (but we recommend to always add a title to the snippet):*/}
```js
//Your code goes in here
```

{/*To add a title, enter it right after the language, in the code block starting line:*/}
```js myFile.js
// Your code goes in here
```
```js Title for a code block
// Your code goes in here
```

{/*Title and params can be separated by pipe ( "|" ) characters, but they also work for block without a title:*/}
```js myFile.js|collapseHeight=600
// Your code goes in here
```
```js collapseHeight=200
// Your code goes in here
```

Supported additional params

Param	Type	Description
`collapseHeight`	number	The custom height that the code block uses to collapse automatically. The default value is`408`and is applied unless the`collapseHeight`param has been specified.

Add inline Snack examples

Snacks are a great way to add instantly-runnable examples to our docs. TheSnackInlinecomponent can be imported to any markdown file, and used like this:

importSnackInlinefrom'~/components/plugins/SnackInline';

<SnackInlinelabel='My Example Label'dependencies={['array of','packages','this Snack relies on']}>
```js
//All your code goes in here

//You can use:
/*@info Some text goes here*/
constmyVariable=SomeCodeThatDoesStuff();
/*@end*/
//to create hoverable-text, which reveals the text inside of `@info` onHover.

//You can use:
/*@hide Content that is still shown, like a preview.*/
Everythinginhere is hiddeninthe example Snack until
you open itinsnack.expo.dev
/*@end*/
//to shorten the length of code block shown in our docs.
//Hidden code will still be present when opening in Snack or using "Copy" action.
```
</SnackInline>

Add multiple code variants

Sometimes it's useful to show multiple ways of doing something, for instance, maybe you'd like to have an example using a React class component, and also an example of a functional component. TheTabsplugin is really useful for this, and this is how you'd use it in a markdown file:

import{Tabs,Tab}from'~/ui/components/Tabs';

<Tabs>
<Tablabel="Add 1 One Way">
```js
addOne=asyncx=>{
/*@info This text will be shown onHover*/
returnx+1;
/*@end*/
};
```
</Tab>
<Tab label="Add 1 Another Way">
```js
addOne = async x => {
/* @info This text will be shown onHover */
return x++;
/* @end */
};
```
</Tab>
</Tabs>

Note:The components should not be indented or they will not be parsed correctly.

Exclude pages from DocSearch

To ignore a page from the search result, usehideFromSearch: trueon that page. This removes the<meta name= "docsearch:version" >tag from that page and filters it from our facet-based search.

Please note thathideFromSearchonly prevents the page from showing up in the internal docs search (Algolia). The page will still show up in search engine results like Google. For a page to be hidden even from search engine results, you need to edit the sitemap that is generated via our Next.js config (next.config.js).

Exclude directories from the sidebar

Certain directories are excluded from the sidebar to prevent it from getting too long and unnavigable. You can find a list of these directories, and add new ones, inconstants/navigation.jsunderhiddenSections.

If you just want to hide a single page from the sidebar, sethideInSidebar: truein the page metadata.

Use`Terminal`component for shell commands snippets

Whenever shell commands are used or referred, useTerminalcomponent to make the code snippets copy/pasteable. This component can be imported into any markdown file.

import{Terminal}from'~/ui/components/Snippet';

{/*for single command and one prop:*/}

<Terminalcmd={['$ npx expo install package']}/>

{/*for multiple commands:*/}

<Terminal
cmd={['# Create a new Expo project','$ npx create-expo-app --template bare-minimum','']}
cmdCopy="npx create-expo-app --template bare-minimum"
/>

Use callouts

Four different types of callouts can be used with markdown syntax for>...blockquote. Each callout represents a purpose.

>Normal callout that doesn't demand much attention but is required to add as a note.

>**info**Callout that is informative and demands attention is required to add as a note or a tip.

>**warning**Callout that is used for warnings and deprecation messages.

>**error**Callout that is used for errors and breaking changes or deprecated changes in the archive.

Add last update date manually

All docs pages are automatically updated with the last update date of the file based on their Git commit history. This information is reflected in the footer of a docs page withLast updated on....

If you need to add the date manually, addmodificationDateto the frontmatter of the.mdxfile. For example:

---
modificationDate:April 8th, 2024
{/* Other frontmatter fields */}
---

This pattern is used for some of the pages where we manually update the modification date, such asBuild server infrastructure.

Docs areas that are excluded or do not include an updated date are SDK API references and Tutorials sections under Learn.

Prettier

Please commit any sizeable diffs that are the result ofprettierseparately to make reviews as easy as possible.

If you have a code block using/* @info */highlighting, use{/* prettier-ignore */}on the block and take care to preview the block in the browser to ensure that the indentation is correct - the highlighting annotation will sometimes swallow newlines.

Name		Name	Last commit message	Last commit date
parent directory ..
.vale/writing-styles/expo-docs		.vale/writing-styles/expo-docs
common		common
components		components
constants		constants
global-styles		global-styles
mdx-plugins		mdx-plugins
pages		pages
providers		providers
public		public
scenes/get-started		scenes/get-started
scripts		scripts
types		types
ui		ui
.eslintignore		.eslintignore
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.prettierrc		.prettierrc
.puppeteerrc.cjs		.puppeteerrc.cjs
.vale.ini		.vale.ini
LICENSE		LICENSE
README.md		README.md
deploy.sh		deploy.sh
jest.config.js		jest.config.js
next-env.d.ts		next-env.d.ts
next.config.js		next.config.js
package.json		package.json
postcss.config.cjs		postcss.config.cjs
tailwind.config.cjs		tailwind.config.cjs
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Files

docs

Directory actions

More options

Directory actions

More options

Latest commit

History

docs

Folders and files

parent directory

README.md

Expo Documentation

To run locally in development mode

To run locally in production mode

Edit Docs Content

Metadata of a page

Edit Code

Prose linter

Use Vale in VS Code (Recommended)

Run thelint-prosescript

Redirects

Server-side redirects

Client-side redirects

Search

Quirks

Deployment

How-tos

Internal linking

Update latest version of docs

Update API reference docs

Prerequisites

Step 1: Update the package's TypeDoc

Step 2: Apply TypeDoc updates to expo/docs repo

Step 3: See the changes in the docs repo

Tips

Disable changelog

Use the correct package name

Sync app.json/app.config.js with the schema

Add images and assets

Add videos

Add code block

Supported additional params

Add inline Snack examples

Add multiple code variants

Exclude pages from DocSearch

Exclude directories from the sidebar

UseTerminalcomponent for shell commands snippets

Use callouts

Add last update date manually

Prettier

Run the`lint-prose`script

Use`Terminal`component for shell commands snippets