Skip to content

Commit fad0ca9

Browse files
committed
Update docs
1 parent bd96da6 commit fad0ca9

File tree

2 files changed

+42
-17
lines changed

2 files changed

+42
-17
lines changed

docs/fern/docs/pages/getting-started/setup.mdx

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,20 @@ slug: getting-started/setup
44

55
## Setup
66

7-
To get started with Stack, you need to create a [Next.js](https://nextjs.org/docs) project with the App router. If you are starting from scratch, run the following:
7+
To get started with Stack, you need to create a [Next.js](https://nextjs.org/docs) project with the App router. If you are starting from scratch, you can just run the following:
88

99
```sh title="Terminal"
1010
npx create-next-app@latest --app stack-example
1111
cd stack-example
12+
npx @stackframe/init-stack@latest
1213
```
1314

14-
You can choose between two ways to install Stack: the setup wizard or manual installation. We recommend using the setup wizard first as it is very easy. However, if you have a non-standard project structure or the setup wizard doesn't work for you, you can follow the manual installation guide.
15+
If you are adding Stack to an existing project, you can choose between two ways to install Stack: the setup wizard or manual installation. We recommend using the setup wizard first. However, if you have a non-standard project structure or the setup wizard doesn't work for you, you can follow the manual installation guide.
1516

1617
<Tabs>
1718
<Tab title="Setup wizard (Recommended)">
1819

19-
20-
To setup stack, you can run Stack's installation wizard with the following command:
20+
You can run Stack's installation wizard with the following command:
2121

2222
```sh title="Terminal"
2323
npx @stackframe/init-stack@latest
@@ -114,11 +114,11 @@ npm install @stackframe/stack
114114
</Tab>
115115
</Tabs>
116116

117-
That's it! Stack is now configured in your Next.js project. If you start your Next.js app with `npm run dev` and navigate to [http://localhost:3000/handler/signup](http://localhost:3000/handler/signup), you will see the Stack sign-up page!
117+
That's it! Stack is now configured in your Next.js project. If you start your Next.js app with `npm run dev` and navigate to [http://localhost:3000/handler/signup](http://localhost:3000/handler/signup), you will see the Stack sign-up page.
118118

119119
![Stack sign up page](../imgs/signup-page.png)
120120

121-
After signing up/in, you will be redirected back to the home page, which is empty/default for now. We will add some useful information to it in the next section. You can also check out [http://localhost:3000/handler/account-settings](http://localhost:3000/handler/account-settings) page which looks like this:
121+
After signing up/in, you will be redirected back to the home page. We will show you how to add useful information to it in the next section. You can also check out the [http://localhost:3000/handler/account-settings](http://localhost:3000/handler/account-settings) page which looks like this:
122122

123123
![Stack account settings page](../imgs/account-settings-page.png)
124124

docs/fern/docs/pages/getting-started/users.mdx

Lines changed: 36 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
slug: getting-started/users
33
---
44

5-
In [the last guide](./setup.mdx), we created `StackServerApp` and `StackProvider`. In this section, we will show you how to utilize them for accessing and modifying the current user information on Server Components and Client Components, respectively.
5+
In [the last guide](./setup.mdx), we initialized Stack. This created new files containing a `StackServerApp` and `StackProvider`. In this section, we will show you how to utilize those for accessing and modifying the current user information on Server Components and Client Components, respectively.
66

77
## Use the current user in a client component
88

@@ -14,16 +14,16 @@ import { useStackApp } from "@stackframe/stack";
1414

1515
export function MyComponent() {
1616
const app = useStackApp();
17-
const user = app.useUser(); // or just import useUser and use it directly
17+
const user = app.useUser();
1818
return <div>{user ? `Hello, ${user.displayName ?? "anon"}` : 'You are not logged in'}</div>;
1919
}
2020
```
2121

22-
Because it's so common, `useUser()` is also exposed as a standalone hook. This means that you can simply invoke `useUser()` as an alias for `useStackApp().useUser()`. (This is not true for other hooks; for example, you must call `useStackApp().useProject()` instead of `useProject()`.)
22+
Because it's so common, `useUser()` is also exposed as a standalone hook: `import { useUser } from "@stackframe/stack"`. This is simply a shortcut because `useUser()` is shorter than `useStackApp().useUser()`. (This is not the case with other hooks; most are on the `StackClientApp` object, for example, you must explicitly call `useStackApp().useProject()` versus `useProject()`.)
2323

2424
## Use the current user in a server component
2525

26-
On Server Components, you don't need `useStackApp()`. Instead, you can just import the `StackServerApp` that you created in the previous chapter:
26+
On Server Components, you don't need `useStackApp()`. Instead, you can just import the `StackServerApp` that you created in the previous chapter (usually you would find it in the root or `src` directory):
2727

2828
```tsx title="Server user profile"
2929
import { stackServerApp } from "@/stack";
@@ -41,11 +41,27 @@ The difference between `getUser()` and `useUser()` is that `useUser()` will re-r
4141

4242
## Protecting a page
4343

44-
Call `useUser` (or `getUser`) with the `{ or: 'redirect' }` option to protect the page. If the user is not logged in, they will be redirected to the sign-in page.
44+
There are three ways to protect a page: Using middleware, in Client Components with `useUser({ or: "redirect" })`, and in Server Components with `await getUser({ or: "redirect" })`.
45+
46+
Middleware can be used whenever it is easy to tell whether a page should be protected given just the URL, for example you have a `/private` section only accessible to logged-in users.
47+
48+
On Client Components, the `useUser({ or: 'redirect' })` hook will redirect the user to the sign-in page if they are not logged in. Similarly, on Server Components, call `await getUser({ or: "redirect" })` to protect a page (or component).
4549

4650
<Tabs>
51+
<Tab title="Middleware">
52+
```tsx title="middleware.tsx"
53+
"use client";
54+
import { useUser } from "@stackframe/stack";
55+
56+
export default function Protected() {
57+
useUser({ or: 'redirect' });
58+
return <h1>You can only see this if you are logged in</h1>
59+
}
60+
```
61+
</Tab>
62+
4763
<Tab title="Client Component">
48-
```tsx title="Client-side protection"
64+
```tsx title="my-component.tsx"
4965
"use client";
5066
import { useUser } from "@stackframe/stack";
5167

@@ -57,7 +73,7 @@ Call `useUser` (or `getUser`) with the `{ or: 'redirect' }` option to protect th
5773
</Tab>
5874

5975
<Tab title="Server Component">
60-
```tsx title="Server-side protection"
76+
```tsx title="my-component.tsx"
6177
import { stackServerApp } from "@/stack";
6278

6379
export default async function Protected() {
@@ -68,11 +84,20 @@ Call `useUser` (or `getUser`) with the `{ or: 'redirect' }` option to protect th
6884
</Tab>
6985
</Tabs>
7086

87+
<Note>
88+
If you have sensitive information hidden in the page HTML itself, be aware of Next.js differences when using Server vs. Client Components. Irregardless of which method you use, attackers will never be able to, say, impersonate a user.
7189

72-
## Signing out
90+
**Server Components**: Next.js may send individual components on the same page to the client separately. For example, if you have two files `layout.tsx` (protected) and `page.tsx` (not protected), the bundled HTML of the `page.tsx` may still be sent to the browser even if the user is not logged in. (Normal browsers will never display it, but attackers may be able to retrieve it.)
91+
92+
To remediate this, every component that contains sensitive information should be protected, not just the page/layout. Usually, this is quite natural, as you need the `User` object to retrieve sensitive data anyways.
7393

74-
You can sign out the user by redirecting them to `/handler/signout` or simply by calling `user.signOut()`. The user will be redirected to `afterSignOut` URL. you can customize it in the `StackServerApp` constructor (see [here](/docs/api-documentation/app)).
94+
**Client Components**: Client components are always sent to the user, regardless of page protection. This is standard Next.js behavior. For more information, please refer to the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/rendering/composition-patterns#keeping-server-only-code-out-of-the-client-environment). (Again, this will not allow attackers to impersonate a user).
95+
</Note>
96+
97+
98+
## Signing out
7599

100+
You can sign out the user by redirecting them to `/handler/signout` or simply by calling `user.signOut()`. They will be redirected to the URL [configured as `afterSignOut` in the `StackServerApp`](/docs/api-documentation/app).
76101

77102
<Tabs>
78103
<Tab title="user.signOut()">
@@ -82,7 +107,7 @@ You can sign out the user by redirecting them to `/handler/signout` or simply by
82107

83108
export default function SignOutButton() {
84109
const user = useUser();
85-
return <button onClick={user?.signOut}>Sign Out</button>;
110+
return user ? <button onClick={() => user.signOut()}>Sign Out</button> : "Not signed in";
86111
}
87112
```
88113
</Tab>
@@ -174,7 +199,7 @@ To see more examples of how to use the `User` object, check out the [User API do
174199

175200
## Custom User Information
176201

177-
You can update the user's information by calling `user.update()` with the new data. The user data from the `userUser()` hook is automatically will also be updated automatically. Here is an example:
202+
You can update the user's information by calling `user.update()` with the new data. The user data from the `userUser()` hook will also be updated automatically. Here is an example:
178203

179204
```tsx title="Update user display name"
180205
'user client';

0 commit comments

Comments
 (0)