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

Update quickstarts #1626

Merged
merged 11 commits into from
Oct 28, 2024
Merged

Update quickstarts #1626

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
228f170
nextjs quickstart
alexisintech Oct 11, 2024
239841d
wip
alexisintech Oct 21, 2024
93d2913
update
alexisintech Oct 21, 2024
a5a9537
wip
alexisintech Oct 21, 2024
ac4d196
Merge branch 'main' into aa/DOCS-9383
victoriaxyz Oct 25, 2024
08ecad1
place --> create
alexisintech Oct 25, 2024
5a8af92
add missing reference to astro global types
alexisintech Oct 25, 2024
cc7df6c
apply code review suggestions
alexisintech Oct 25, 2024
decf436
Merge branch 'main' into aa/DOCS-9383
victoriaxyz Oct 28, 2024
6a016d8
add comment about astro types line
alexisintech Oct 28, 2024
9532a83
expo quickstart
alexisintech Oct 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 26 additions & 21 deletions docs/quickstarts/astro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,21 +25,19 @@ description: Add authentication and user management to your Astro app with Clerk
]}
>
- Install `@clerk/astro`
- Set up your environment keys to test your app locally
- Add TypeScript declarations
- Add the `clerk()` integration to your application
- Use Clerk middleware to implement route-specific authentication
- Set your Clerk API keys
- Add `clerkMiddleware()`
- Create a header with Clerk components for users to sign in and out
</TutorialHero>

Clerk's [Astro SDK](/docs/references/astro/overview) provides a set of components, hooks, and stores that make it easy to build authentication and user management features in your Astro app.

<Steps>
### Install `@clerk/astro`

Add Clerk's Astro SDK to your project:
Clerk's [Astro SDK](/docs/references/astro/overview) provides a set of components, hooks, and stores that make it easy to build authentication and user management features in your Astro app.

Add the SDK to your project by running the following command:

<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
```bash {{ filename: 'terminal' }}
npm install @clerk/astro
```
Expand All @@ -53,15 +51,14 @@ Clerk's [Astro SDK](/docs/references/astro/overview) provides a set of component
```
</CodeBlockTabs>

### Set environment variables
### Set your Clerk API keys

<SignedIn>
Add the following keys to your `.env.local` file. These keys can always be retrieved from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard.
Add the following keys to your `.env.local` file. These keys can always be retrieved from the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard.
</SignedIn>

<SignedOut>
1. Navigate to the Clerk Dashboard.
1. In the navigation sidebar, select [API Keys](https://dashboard.clerk.com/last-active?path=api-keys).
1. In the Clerk Dashboard, navigate to the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page.
1. In the **Quick Copy** section, copy your Clerk publishable and secret key.
1. Paste your keys into your `.env.local` file.

Expand All @@ -78,8 +75,8 @@ Clerk's [Astro SDK](/docs/references/astro/overview) provides a set of component
To configure Clerk in your Astro application, you will need to update your `astro.config.mjs`.

- Add the Clerk integration to the `integrations` list.
- Install an [SSR adapter](https://docs.astro.build/en/guides/server-side-rendering/#official-adapters). For this quickstart we chose the [`@astrojs/node`](https://docs.astro.build/en/guides/integrations-guide/node/) adapter. You can use any Node based adapter you wish.
- Set `output` to `server`. This is required when deploying to a host supporting SSR.
- Install an [SSR adapter](https://docs.astro.build/en/guides/server-side-rendering/#official-adapters). This quickstart uses the [`@astrojs/node`](https://docs.astro.build/en/guides/integrations-guide/node/) adapter.
- Set `output` to `server`. This is required when deploying to a host supporting SSR.

```ts {{ filename: 'astro.config.mjs', mark: [2, 3, [6, 8]] }}
import { defineConfig } from 'astro/config'
Expand All @@ -93,13 +90,14 @@ Clerk's [Astro SDK](/docs/references/astro/overview) provides a set of component
})
```

### Add middleware to your application
### Add `clerkMiddleware()` to your app

[`clerkMiddleware()`](/docs/references/astro/clerk-middleware) grants you access to user authentication state throughout your application, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add `clerkMiddleware()` to your application, follow these steps:

1. Create a `middleware.ts` file inside your `src/` directory.
1. In your `middleware.ts` file, export an `onRequest` constant and assign the result of the `clerkMiddleware` function to it.
[`clerkMiddleware()`](/docs/references/astro/clerk-middleware) grants you access to user authentication state throughout your application, on any route or page. It also allows you to protect specific routes from unauthenticated users. To add `clerkMiddleware()` to your application, follow these steps:

1. Create a `middleware.ts` file.
- If you're using the `/src` directory, place `middleware.ts` in the `/src` directory.
Copy link
Contributor

Choose a reason for hiding this comment

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

Just a nit, I prefer put or create vs. `place.

Copy link
Member Author

Choose a reason for hiding this comment

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

yeah good call

- If you're not using the `/src` directory, place `middleware.ts` in the root directory alongside `.env.local`.
1. In your `middleware.ts` file, export an `onRequest` constant and assign the result of the `clerkMiddleware()` function to it.
```tsx {{ filename: 'src/middleware.ts' }}
import { clerkMiddleware } from '@clerk/astro/server'

Expand All @@ -116,9 +114,14 @@ Clerk's [Astro SDK](/docs/references/astro/overview) provides a set of component
/// <reference types="@clerk/astro/env" />
victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved
```

### Add components to your app
### Add Clerk components to your app

You can control which content signed in and signed out users can see with Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components). Create a header using the following components:
alexisintech marked this conversation as resolved.
Show resolved Hide resolved

Clerk offers components that allow you to protect your pages. These components are used to control the visibility of your pages based on the user's authentication state.
- [`<SignedIn>`](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**.
- [`<SignedOut>`](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**.
- [`<UserButton />`](/docs/components/user/user-button): Shows the avatar from the account the user is signed in with. When selected, it opens a dropdown menu with account management options.
alexisintech marked this conversation as resolved.
Show resolved Hide resolved
- [`<SignInButton />`](/docs/components/unstyled/sign-in-button): An unstyled component that links to the sign-in page. For this example, because you have not specified any props or [environment variables](/docs/deployments/clerk-environment-variables) for the sign-in URL, the component will link to the [Account Portal sign-in page.](/docs/customization/account-portal/overview)
alexisintech marked this conversation as resolved.
Show resolved Hide resolved

```astro {{ filename: 'src/layouts/SiteLayout.astro' }}
---
Expand Down Expand Up @@ -151,6 +154,8 @@ Clerk's [Astro SDK](/docs/references/astro/overview) provides a set of component
</html>
```

Then, use the layout on your homepage:

```astro {{ filename: 'src/pages/index.astro' }}
---
import SiteLayout from '../layouts/SiteLayout.astro'
Expand Down
51 changes: 24 additions & 27 deletions docs/quickstarts/expo.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,18 @@ description: Add authentication and user management to your Expo app with Clerk.
>
- Create an Expo application
- Install `@clerk/expo`
- Set up your environment keys to test your app locally
- Add `<ClerkProvider />` to your application
- Set your Clerk API keys
- Add `<ClerkProvider />`
- Protect specific pages with authentication
- Use Clerk hooks to enable users to sign in and out of your application
- Use Clerk hooks to enable users to sign in and out
</TutorialHero>

<Steps>
### Create an Expo application

To get started using Clerk with Expo, create a new Expo project and install the necessary dependencies. See the [Expo documentation](https://docs.expo.dev/tutorial/create-your-first-app/) for more information.
Create a new Expo project and install the necessary dependencies by running the following command:

<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
```bash filename="terminal"
npx create-expo-app application-name --template blank && cd application-name
npx expo install react-dom react-native-web @expo/metro-runtime
Expand All @@ -53,9 +53,11 @@ description: Add authentication and user management to your Expo app with Clerk.

### Install `@clerk/clerk-expo`

Add Clerk's [Expo SDK](/docs/references/expo/overview) to your project:
Clerk's [Expo SDK](/docs/references/expo/overview) gives you access to prebuilt components, hooks, and helpers to make user authentication easier.

Add the SDK to your project by running the following command:

<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
```bash filename="terminal"
npm install @clerk/clerk-expo
```
Expand All @@ -69,17 +71,16 @@ description: Add authentication and user management to your Expo app with Clerk.
```
</CodeBlockTabs>

### Set your environment variables
### Set your Clerk API keys

<SignedIn>
Add the following keys to your `.env` file. These keys can always be retrieved from your project's [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) page in the Clerk Dashboard.
Add your Clerk publishable key to your `.env` file. It can always be retrieved from the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page of your Clerk Dashboard.
</SignedIn>

<SignedOut>
1. Navigate to the Clerk Dashboard.
1. In the navigation sidebar, select [API Keys](https://dashboard.clerk.com/last-active?path=api-keys).
1. In the **Quick Copy** section, copy your Clerk publishable and secret key.
1. Paste your keys into your `.env` file.
1. In the Clerk Dashboard, navigate to the [**API Keys**](https://dashboard.clerk.com/last-active?path=api-keys) page.
1. In the **Quick Copy** section, copy your Clerk publishable key.
1. Paste your key into your `.env` file.

The final result should resemble the following:
</SignedOut>
Expand All @@ -90,7 +91,9 @@ description: Add authentication and user management to your Expo app with Clerk.

### Add `<ClerkProvider>` to your root layout

All Clerk hooks and components must be children of [`<ClerkProvider>`](/docs/components/clerk-provider), which provides active session and user context. Clerk also provides `<ClerkLoaded>`, which will not render child content unless the Clerk API has loaded.
The [`<ClerkProvider>`](/docs/components/clerk-provider) component wraps your application to provide active session and user context to Clerk's hooks and other components. You must pass your publishable key as a prop to the `<ClerkProvider>` component.
alexisintech marked this conversation as resolved.
Show resolved Hide resolved

Clerk also provides [`<ClerkLoaded>`](/docs/components/control/clerk-loaded), which will not render child content unless the Clerk API has loaded.
alexisintech marked this conversation as resolved.
Show resolved Hide resolved

To grant your entire app access to Clerk session data and ensure nothing renders until Clerk loads, add both components to your root layout as shown in the following example:
alexisintech marked this conversation as resolved.
Show resolved Hide resolved

Expand All @@ -102,9 +105,7 @@ description: Add authentication and user management to your Expo app with Clerk.
const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY!

if (!publishableKey) {
throw new Error(
'Missing Publishable Key. Please set EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY in your .env',
)
throw new Error('Add EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY to your .env file')
}

return (
Expand All @@ -117,13 +118,13 @@ description: Add authentication and user management to your Expo app with Clerk.
}
```

### Configure the Token Cache with Expo
### Configure the token cache

The token cache is used to persist the active user's session token. Clerk stores this token in memory by default, however it is recommended to use a token cache for production applications.
The token cache is used to persist the active user's session token. Clerk stores this token in memory by default. However, it is recommended to use a token cache for production applications.
alexisintech marked this conversation as resolved.
Show resolved Hide resolved

Install `expo-secure-store`, which you'll use as your token cache:

<CodeBlockTabs type="installer" options={["npm", "yarn", "pnpm"]}>
<CodeBlockTabs options={["npm", "yarn", "pnpm"]}>
```bash {{ filename: 'terminal' }}
npm install expo-secure-store
```
Expand Down Expand Up @@ -186,9 +187,7 @@ description: Add authentication and user management to your Expo app with Clerk.
const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY!

if (!publishableKey) {
throw new Error(
'Missing Publishable Key. Please set EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY in your .env',
)
throw new Error('Add EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY in your .env')
}

return (
Expand All @@ -204,9 +203,9 @@ description: Add authentication and user management to your Expo app with Clerk.
> [!TIP]
> When you sign a user out with [`signOut()`](/docs/references/react/use-auth#use-auth-returns), Clerk will remove the user's session JWT from the token cache.

### Conditionally render content
### Protect your pages

You can control which content signed-in and signed-out users can see with Clerk's [control components](/docs/components/overview#what-are-control-components). For this quickstart, you'll use:
You can control which content signed-in and signed-out users can see with Clerk's [prebuilt control components](/docs/components/overview#what-are-control-components). For this quickstart, you'll use:

- [`<SignedIn>`](/docs/components/control/signed-in): Children of this component can only be seen while **signed in**.
- [`<SignedOut>`](/docs/components/control/signed-out): Children of this component can only be seen while **signed out**.
Expand Down Expand Up @@ -462,8 +461,6 @@ See the [`expo-updates`](https://docs.expo.dev/versions/latest/sdk/updates) libr

## Next steps

See the following guides to take the next steps toward fleshing out your Expo app.

<Cards>
- [OAuth with Expo](/docs/custom-flows/oauth-connections)
- Learn more how to build a custom OAuth flow with Expo.
Expand Down
Loading
Loading