Skip to content

Commit

Permalink
[docs] Update outdated info in Expo SDK libraries section (expo#28504)
Browse files Browse the repository at this point in the history
# Why

<!--
Please describe the motivation for this PR, and link to relevant GitHub
issues, forums posts, or feature requests.
-->
This PR:
- Platform compatibility table with platform tags and a screenshot taken
from `expo-device` as an example.
- Updates info about what an API reference page contains to include the
config plugin.
- Remove `expo-device` example as it has no relevance here (as a reader
I want to learn what an API reference page contains)
- Update styles for React Native components API example.

# Test Plan

<!--
Please describe how you tested this change and how a reviewer could
reproduce your test, especially if this PR does not include automated
tests! If possible, please also provide terminal output and/or
screenshots demonstrating your test/reproduction.
-->

Run docs locally and visit:
http://localhost:3002/workflow/using-libraries/#expo-sdk-libraries

## Preview

![CleanShot 2024-04-29 at 00 47
37@2x](https://github.com/expo/expo/assets/10234615/16caaeb4-c0fa-4685-9887-94839e71c6ac)


# Checklist

<!--
Please check the appropriate items below if they apply to your diff.
This is required for changes to Expo modules.
-->

- [ ] Documentation is up to date to reflect these changes (eg:
https://docs.expo.dev and README.md).
- [ ] Conforms with the [Documentation Writing Style
Guide](https://github.com/expo/expo/blob/main/guides/Expo%20Documentation%20Writing%20Style%20Guide.md)
- [ ] This diff will work correctly for `npx expo prebuild` & EAS Build
(eg: updated a module plugin).
  • Loading branch information
amandeepmittal authored May 7, 2024
1 parent 1236b88 commit 13ec73f
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 43 deletions.
64 changes: 21 additions & 43 deletions docs/pages/workflow/using-libraries.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ description: Learn how to use libraries based on React Native, Expo SDK and thir
---

import { ConfigReactNative } from '~/components/plugins/ConfigSection';
import PlatformsSection from '~/components/plugins/PlatformsSection';
import InstallSection from '~/components/plugins/InstallSection';
import { BoxLink } from '~/ui/components/BoxLink';
import { Terminal } from '~/ui/components/Snippet';
import { SnackInline } from '~/ui/components/Snippet';
import ImageSpotlight from '~/components/plugins/ImageSpotlight';

Every app is inevitably going to use a third-party library, so it's important to understand how to determine whether a library is compatible with your project.

Expand All @@ -21,12 +21,11 @@ To use a React Native component or API in your project, import it from the `reac
<SnackInline>

```jsx
import * as React from 'react';
import { Text, View } from 'react-native';

export default function App() {
return (
<View style={{ flex: 1, paddingTop: 100 }}>
<View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
<Text>Hello, world!</Text>
</View>
);
Expand All @@ -39,61 +38,43 @@ export default function App() {

The Expo SDK picks up where the React Native core libraries end. It provides access to a lot of device and system functionality such as audio, barcode scanning, camera, calendar, contacts, video, and so on. It also adds other powerful libraries like updates, maps, OAuth authentication tools, and more. For more information, see how we decide [what goes into the Expo SDK](https://expo.fyi/whats-in-the-sdk).

To use a library from the Expo SDK, find the one you are looking for in the [API Reference](/versions/latest/) or through the documentation Search bar.
To use a library from the Expo SDK, find the one you are looking for in the [API reference](/versions/latest/) or use the documentation search.

<ConfigReactNative>

If you initialized your app using `npx react-native init` and you don't have the `expo` package installed in it yet, refer to the [installing Expo modules guide](/bare/installing-expo-modules).
If you initialized your app using `npx react-native init` and you don't have the `expo` package installed in it yet, see the [installing Expo modules guide](/bare/installing-expo-modules) for more information.

</ConfigReactNative>

At the top of the page you will see a description of the library and a platform compatibility table. It tells you which platforms and environments the library is compatible with. It looks like this:
You will see the platform compatibility tags at the top of each API reference. It tells you which platforms and environments the library is compatible with. For example, the platform tags for the [`expo-device`](/versions/latest/sdk/device/) library look like the following:

<PlatformsSection android emulator ios simulator web />
<ImageSpotlight
alt="Platform compatibility tags for expo-device library on its API reference."
src="/static/images/guides/platform-tags.png"
style={{ maxWidth: 480 }}
/>

After the platform compatibility table, there will be an Installation section, with instructions that look like this:
After the platform compatibility table, there is a library's description and a section with instructions on installing the library. For example:

<InstallSection packageName="expo-device" hideBareInstructions />

The `npx expo install` command will pick a version of the library that is compatible with your project and then use your JavaScript package manager (such as npm) to install it.

Next, under the API section the reference page will tell you how to import the library in your code:
The `npx expo install` command picks a library version compatible with your project and then uses your JavaScript package manager (such as npm) to install it.

```js
import * as Device from 'expo-device';
```
Next, a typical API reference includes:

This section also lists all of the types, functions, and classes available. If you use TypeScript, you can see this information in your TypeScript-compatible code editor (such as Visual Studio Code) with auto-completion.
- Config plugin usage information if the library requires a config plugin.
- A code example that shows how to use the library.
- API section that lists how to import the library, followed by a list of hooks, props, types, methods, and classes that the library provides.

Now you can use the library in your project:

<SnackInline dependencies={['expo-device']}>

```jsx
import * as React from 'react';
import { Text, View } from 'react-native';
import * as Device from 'expo-device';

export default function App() {
return (
<View style={{ flex: 1, paddingTop: 100 }}>
<Text>
{Device.manufacturer}: {Device.modelName}
</Text>
</View>
);
}
```

</SnackInline>
> **Note**: If you use TypeScript, you can see the information included in the API section in your TypeScript-compatible code editor (such as VS Code) with auto-completion.
## Third-party libraries

### Finding a third-party library

[React Native Directory](https://reactnative.directory) is a searchable database of libraries built specifically for React Native. If the library that you are looking for is not provided by React Native or the Expo SDK then this is the best place to look first when trying to find a library for your app.

After the React Native Directory, the [npm registry](https://www.npmjs.com/) is the next best place. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments. Any library that is compatible with React Native is compatible with the Expo project when you create a [development build](/workflow/overview/#development-builds). However, it may not be compatible with the [Expo Go][expo-go] app.
After the React Native Directory, the [npm registry](https://www.npmjs.com/) is the next best place. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments. Any library that is compatible with React Native is compatible with the Expo project when you create a [development build](/workflow/overview/#development-builds). However, it may not be compatible with the [Expo Go](https://expo.dev/go) app.

### Determining third-party library compatibility

Expand All @@ -118,9 +99,9 @@ To determine if a new dependency changes native project directories, you can che
### Installing a third-party library

> We recommend always using `npx expo install` instead of `npm install` or `yarn add` directly because it allows [Expo CLI][expo-cli] to pick a compatible version of a library when possible and also warn you about known incompatibilities.
> We recommend always using `npx expo install` instead of `npm install` or `yarn add` directly because it allows [Expo CLI](/more/expo-cli/) to pick a compatible version of a library when possible and also warn you about known incompatibilities.
Once you have determined if the library is compatible with React Native, use [Expo CLI][expo-cli] to install the package:
Once you have determined if the library is compatible with React Native, use [Expo CLI](/more/expo-cli/) to install the package:

<Terminal cmd={['$ npx expo install @react-navigation/native']} />

Expand All @@ -136,13 +117,10 @@ If your project does not support [Expo Prebuild](/workflow/prebuild) then you wo

</ConfigReactNative>

If the module is not supported in [Expo Go][expo-go], you can create a [development build](/develop/development-builds/introduction/):
If the module is not supported in [Expo Go](https://expo.dev/go), you can create a [development build](/develop/development-builds/introduction/):

<BoxLink
title="Add custom native code"
description="Learn how to add custom native code to your Expo project."
href="/workflow/customizing/"
/>

[expo-cli]: /more/expo-cli/
[expo-go]: https://expo.dev/go
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 13ec73f

Please sign in to comment.