Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[router] add platform extension docs #27409

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

[router] add platform extension docs #27409

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3a03f9b
[router] add platform extension docs
marklawlor Mar 4, 2024
7ed3b8f
Update docs/pages/router/reference/api-routes.mdx
marklawlor Mar 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/pages/router/advanced/platform-specific-modules.mdx
View file
Open in desktop
Expand Up @@ -3,6 +3,8 @@ title: Platform-specific Modules
description: Learn how to switch modules based on the platform in Expo Router.
---

> **warning** Platform specific extensions were added in Expo Router 3.x.x. This guide is only needed if you are using an older version of Expo Router.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> **warning** Platform specific extensions were added in Expo Router 3.x.x. This guide is only needed if you are using an older version of Expo Router.
> **warning** Platform specific extensions were added in Expo Router `3.x.x`. Follow this guide only if you are using an older version of Expo Router.


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

While building your app, you may want to show specific content based on the current platform. Platform-specific modules can make the experience more native to a given platform. The following sections describe the ways you can achieve this with Expo Router.
Expand Down
22 changes: 21 additions & 1 deletion docs/pages/router/create-pages.mdx
View file
Open in desktop
Expand Up @@ -56,7 +56,27 @@ For example, create the **app** directory in your project and then create a file

The above example matches the `/` route in the app and the browser. Files named **index** match the parent directory and do not add a path segment. For example, **app/settings/index.js** matches `/settings` in the app.

> Platform extensions (for example, **.ios.js**, **.native.ts**) are not supported in the **app** directory. See [Platform-specific modules](/router/advanced/platform-specific-modules), for more information.
## Platform specific extensions

> **warning** Platform-specific extensions were added in Expo Router 3.x.x. If you are using an older version, please see [Platform-specific modules](/router/advanced/platform-specific-modules), for more information.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> **warning** Platform-specific extensions were added in Expo Router 3.x.x. If you are using an older version, please see [Platform-specific modules](/router/advanced/platform-specific-modules), for more information.
> **warning** Platform-specific extensions were added in Expo Router `3.x.x`. If you are using an older version of the library, follow instructions from [Platform-specific modules](/router/advanced/platform-specific-modules).


Metro bundler's platform-specific extensions (for example, **.ios.js** or **.native.ts**) are supported in the **app** directory only if a **non-platform version** also exists. This ensures that routes are universal across platforms for deep linking.

Consider the following project:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Consider the following project:
Consider the following project structure:


<FileTree
files={[
'app/_layout.js',
'app/_layout.web.js',
'app/index.js',
'app/about.js',
'app/about.web.js',
]}
/>

In this project, the **\_layout.web.js** file is used as a layout on the web and **\_layout.js** is used on all other platform. The **index.js** file is used as the home page for all platforms. The **about.web.js** file is used as the about page for the web and **about.js** file is used on all other platforms.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In this project, the **\_layout.web.js** file is used as a layout on the web and **\_layout.js** is used on all other platform. The **index.js** file is used as the home page for all platforms. The **about.web.js** file is used as the about page for the web and **about.js** file is used on all other platforms.
In the above file structure:
- **\_layout.web.js** file is used as a layout on the web and **\_layout.js** is used on all other platforms.
- **index.js** file is used as the home page for all platforms.
- **about.web.js** file is used as the about page for the web, and the **about.js** file is used on all other platforms.

There's a lot going on in the above paragraph, let's convert it to a list of items. Plus, also fix a couple typos.


> **info** Always provide a file without a platform extension to ensure every platform has a default implementation.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> **info** Always provide a file without a platform extension to ensure every platform has a default implementation.
> **info** Providing a route file without a platform-specific extension is required to ensure every platform has a default implementation.

Since in the first paragraph we say this is requirement for Metro bundler to recognize a platform specific extension only if non-platform specific extension exits, let's say it like that here. Since this is a callout, we can be authoritative and clear about this.

Also, what does "default implementation" mean here? is it the layout? or the home screen?


## Dynamic routes

Expand Down
2 changes: 2 additions & 0 deletions docs/pages/router/reference/api-routes.mdx
View file
Open in desktop
Expand Up @@ -104,6 +104,8 @@ Deploy the website and server to a [hosting provider](#deployment) to access the

</Step>

> **warning** API routes filenames annot have platform specific extensions. For example, `hello+api.web.ts` will not work.
marklawlor marked this conversation as resolved.
Show resolved Hide resolved

## Requests

Requests use the global, standard [`Request`](https://fetch.spec.whatwg.org/#request) object.
Expand Down