feat: @uploadthing/expo

.changeset/afraid-berries-burn.md

@@ -0,0 +1,6 @@
+---
+"@uploadthing/react": minor
+"@uploadthing/expo": minor
+---
+
+feat: support expo

.npmrc

@@ -4,4 +4,9 @@
 save-workspace-protocol=false
 prefer-workspace-packages=true
 
+# Expo doesn't play nice with pnpm by default.
+# The symbolic links of pnpm break the rules of Expo monorepos.
+# @link https://docs.expo.dev/guides/monorepos/#common-issues
+node-linker=hoisted
+
 engine-strict=true

docs/src/pages/api-reference/expo.mdx

@@ -0,0 +1,171 @@
+import { Callout } from "nextra-theme-docs";
+
+## `generateReactNativeHelpers`
+
+The `generateReactNativeHelpers` function is used to generate the
+useImageUploader and useDocumentUploader hooks you use to interact with
+UploadThing in your app.
+
+```tsx copy filename="utils/uploadthing.tsx"
+import { generateReactNativeHelpers } from "@uploadthing/expo";
+
+import type { UploadRouter } from "~/app/api/uploadthing+api";
+
+export const { useImageUploader, useDocumentUploader } =
+  generateReactNativeHelpers<UploadRouter>({
+    /**
+     * Your server url.
+     * @default process.env.EXPO_PUBLIC_SERVER_URL
+     * @remarks In dev we will also try to use Expo.debuggerHost
+     */
+    url: "https://my-server.com",
+  });
+```
+
+## `useImageUploader`
+
+A hook wrapping the native `expo-image-picker` module that allows access to the
+camera and photo library and uploads files to your server. The first time the
+user triggers the picker they will be prompted to grant your app permission to
+access the camera or photo library.
+
+```tsx copy filename="app/example-uploader.tsx"
+import { Alert, Pressable, Text, View } from "react-native";
+
+import { useImageUploader } from "@uploadthing/expo";
+
+export function MultiUploader() {
+  const { openImagePicker, isUploading } = useImageUploader("imageUploader", {
+    /**
+     * Any props here are forwarded to the underlying `useUploadThing` hook.
+     * Refer to the React API reference for more info.
+     */
+    onClientUploadComplete: () => Alert.alert("Upload Completed"),
+    onUploadError: (error) => Alert.alert("Upload Error", error.message),
+  });
+
+  return (
+    <View>
+      <Pressable
+        onPress={() => {
+          openImagePicker({
+            input, // Matches the input schema from the FileRouter endpoint
+            source: "library", // or "camera"
+            onInsufficientPermissions: () => {
+              Alert.alert(
+                "No Permissions",
+                "You need to grant permission to your Photos to use this",
+                [
+                  { text: "Dismiss" },
+                  { text: "Open Settings", onPress: openSettings },
+                ],
+              );
+            },
+          });
+        }}
+      >
+        <Text>Select Image</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+### Configuration
+
+| Prop     | Type                  | Required | Notes                                            | Description                                                                       |
+| :------- | :-------------------- | :------- | :----------------------------------------------- | --------------------------------------------------------------------------------- |
+| endpoint | `keyof UploadRouter`  | Yes      |                                                  | The name of the [route](./server#FileRouter) you want this button to upload to    |
+| opts     | `UseUploadThingProps` | No       | [See docs](/api-reference/react#configuration-3) | Props forwarded to the underlying `useUploadThing` hook from `@uploadthing/react` |
+
+### Returns
+
+| Prop            | Type                                              | Description                                                                      |
+| :-------------- | :------------------------------------------------ | :------------------------------------------------------------------------------- |
+| openImagePicker | `(opts: OpenImagePickerOptions) => Promise<void>` | Function to open the native image picker and start uploading the selected files. |
+| isUploading     | boolean                                           | Flag whether file(s) are currently uploading                                     |
+
+```ts
+type OpenImagePickerOptions = {
+  input: TInput; // Matches the input schema from the FileRouter endpoint
+  source: "library" | "camera";
+  /**
+   * Callback to run if the user cancels the picker.
+   */
+  onCancel?: () => void;
+  /**
+   * Callback to run if the user hasn't granted your app permission to the camera or photo library.
+   */
+  onInsufficientPermissions: () => void;
+};
+```
+
+## `useDocumentUploader`
+
+A hook wrapping the native `expo-document-picker` module that allows access to
+the native file system and uploads files to your server.
+
+```tsx copy filename="app/example-uploader.tsx"
+import { Alert, Pressable, Text, View } from "react-native";
+
+import { useDocumentUploader } from "@uploadthing/expo";
+
+export function MultiUploader() {
+  const { openDocumentPicker, isUploading } = useDocumentUploader("document", {
+    /**
+     * Any props here are forwarded to the underlying `useUploadThing` hook.
+     * Refer to the React API reference for more info.
+     */
+    onClientUploadComplete: () => Alert.alert("Upload Completed"),
+    onUploadError: (error) => Alert.alert("Upload Error", error.message),
+  });
+
+  return (
+    <View>
+      <Pressable
+        onPress={() => {
+          openDocumentPicker({
+            input, // Matches the input schema from the FileRouter endpoint
+            onInsufficientPermissions: () => {
+              Alert.alert(
+                "No Permissions",
+                "You need to grant permission to your Photos to use this",
+                [
+                  { text: "Dismiss" },
+                  { text: "Open Settings", onPress: openSettings },
+                ],
+              );
+            },
+          });
+        }}
+      >
+        <Text>Select Document</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+### Configuration
+
+| Prop     | Type                  | Required | Notes                                            | Description                                                                       |
+| :------- | :-------------------- | :------- | :----------------------------------------------- | --------------------------------------------------------------------------------- |
+| endpoint | `keyof UploadRouter`  | Yes      |                                                  | The name of the [route](./server#FileRouter) you want this button to upload to    |
+| opts     | `UseUploadThingProps` | No       | [See docs](/api-reference/react#configuration-3) | Props forwarded to the underlying `useUploadThing` hook from `@uploadthing/react` |
+
+### Returns
+
+| Prop            | Type                                              | Description                                                                      |
+| :-------------- | :------------------------------------------------ | :------------------------------------------------------------------------------- |
+| openImagePicker | `(opts: OpenImagePickerOptions) => Promise<void>` | Function to open the native image picker and start uploading the selected files. |
+| isUploading     | boolean                                           | Flag whether file(s) are currently uploading                                     |
+
+```ts
+type OpenImagePickerOptions = {
+  input: TInput; // Matches the input schema from the FileRouter endpoint
+  /**
+   * Callback to run if the user cancels the picker.
+   */
+  onCancel?: () => void;
+};
+```

docs/src/pages/getting-started/expo.mdx

@@ -0,0 +1,201 @@
+import { Callout, Steps } from "nextra-theme-docs";
+
+# Expo Setup
+
+UploadThing is the easiest way to add file uploads to your native mobile
+applications powered by export.
+
+<Callout type="info">
+  Check out a full example
+  [here](https://github.com/pingdotgg/uploadthing/tree/main/examples/minimal-expo)
+</Callout>
+
+## Package Setup
+
+<Steps>
+
+### Install the packages
+
+```bash copy npm2yarn
+npm install uploadthing @uploadthing/expo expo-image-picker expo-document-picker
+```
+
+### Add env variables
+
+<Callout>
+  If you don't already have a uploadthing secret key, [sign
+  up](https://uploadthing.com/sign-in) and create one from the
+  [dashboard!](https://uploadthing.com/dashboard)
+</Callout>
+
+```bash copy
+UPLOADTHING_SECRET=... # A secret key for your app (starts with sk_live_)
+UPLOADTHING_APP_ID=... # Your app id
+EXPO_PUBLIC_SERVER_URL=... # Absolute URL to your server
+```
+
+</Steps>
+
+## Set Up A FileRouter
+
+<Callout type="info">
+  Steps 1 and 2 below assumes you're using [Expo API
+  routes](https://docs.expo.dev/router/reference/api-routes/) which are
+  currently experimental. You can also choose to use a standalone server using
+  some of our [backend adapters, e.g. Fetch](/backend-adapters/fetch)
+</Callout>
+
+<Steps>
+### Creating your first FileRoute
+
+<Callout>
+  For more details on how to create a file router, see the
+  [router](/api-reference/server#file-routes) docs
+</Callout>
+
+All files uploaded to uploadthing are associated with a FileRoute. The following
+is a very minimalistic example, with a single FileRoute "imageUploader". Think
+of a FileRoute similar to an endpoint, it has:
+
+- Permitted types ["image", "video", etc]
+- Max file size
+- (Optional) `middleware` to authenticate and tag requests
+- `onUploadComplete` callback for when uploads are completed
+
+To get full insight into what you can do with the FileRoutes, please refer to
+the [File Router API](/api-reference/server#file-routes).
+
+```ts copy filename="src/app/api/uploadthing+api.ts"
+import { createUploadthing, UploadThingError } from "uploadthing/server";
+import type { FileRouter } from "uploadthing/server";
+
+const f = createUploadthing();
+
+const auth = (req: Request) => ({ id: "fakeId" }); // Fake auth function
+
+const uploadRouter = {
+  profileImage: f({
+    image: {
+      maxFileSize: "4MB",
+    },
+  })
+    .middleware(async ({ req }) => {
+      // This code runs on your server before upload
+      const user = await auth(req);
+
+      // If you throw, the user will not be able to upload
+      if (!user) throw new UploadThingError("Unauthorized");
+
+      // Whatever is returned here is accessible in onUploadComplete as `metadata`
+      return { userId: user.id };
+    })
+    .onUploadComplete(({ file, metadata }) => {
+      // This code RUNS ON YOUR SERVER after upload
+      console.log("Upload complete for userId:", metadata.userId);
+
+      console.log("file url", file.url);
+
+      // !!! Whatever is returned here is sent to the clientside `onClientUploadComplete` callback
+      return { uploadedBy: metadata.userId };
+    }),
+} satisfies FileRouter;
+export type UploadRouter = typeof uploadRouter;
+```
+
+### Create an API route using the FileRouter
+
+```ts copy filename="src/app/api/uploadthing+api.ts"
+import { createRouteHandler } from "uploadthing/server";
+
+const uploadRouter = { ... } satisfies FileRouter;
+export type UploadRouter = typeof uploadRouter;
+
+export const { GET, POST } = createRouteHandler({
+  router: uploadRouter,
+
+  // Apply an (optional) custom config:
+  // config: { ... },
+});
+```
+
+> See configuration options in
+> [server API reference](/api-reference/server#createroutehandler)
+
+### Generate typed hooks
+
+Unlike the other UploadThing packages, the Expo package does not include any
+prebuilt components. Instead, we provide some helper hooks to help interact with
+the native file pickers.
+
+```tsx copy filename="src/utils/uploadthing.ts"
+import { generateReactNativeHelpers } from "@uploadthing/expo";
+
+import type { UploadRouter } from "~/app/api/uploadthing+api";
+
+export const { useImageUploader, useDocumentUploader } =
+  generateReactNativeHelpers<UploadRouter>({
+    /**
+     * Your server url.
+     * @default process.env.EXPO_PUBLIC_SERVER_URL
+     * @remarks In dev we will also try to use Expo.debuggerHost
+     */
+    url: "https://my-server.com",
+  });
+```
+
+### Use the FileRouter in your app
+
+```tsx copy filename="src/routes/index.tsx"
+import { openSettings } from "expo-linking";
+import { Alert, Pressable, StyleSheet, Text, View } from "react-native";
+
+import { useImageUploader } from "~/utils/uploadthing";
+
+export default function Home() {
+  const { openImagePicker, isUploading } = useImageUploader({
+    /**
+     * Any props here are forwarded to the underlying `useUploadThing` hook.
+     * Refer to the React API reference for more info.
+     */
+    onClientUploadComplete: () => Alert.alert("Upload Completed"),
+    onUploadError: (error) => Alert.alert("Upload Error", error.message),
+  });
+
+  return (
+    <View>
+      <Pressable
+        style={styles.button}
+        onPress={() => {
+          openImagePicker({
+            input, // Matches the input schema from the FileRouter endpoint
+            source: "library", // or "camera"
+            onInsufficientPermissions: () => {
+              Alert.alert(
+                "No Permissions",
+                "You need to grant permission to your Photos to use this",
+                [
+                  { text: "Dismiss" },
+                  { text: "Open Settings", onPress: openSettings },
+                ],
+              );
+            },
+          })
+        }}
+      >
+        <Text>Select Image</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  button: { ... },
+});
+```
+
+</Steps>
+
+## Deployment
+
+Follow the
+[Expo Router API Routes Deployment Guide](https://docs.expo.dev/router/reference/api-routes/#deployment)

examples/minimal-expo/.env.example

@@ -0,0 +1 @@
+UPLOADTHING_SECRET="sk_live_xxx"