You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/fern/docs/pages/getting-started/setup.mdx
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,20 +4,20 @@ slug: getting-started/setup
4
4
5
5
## Setup
6
6
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:
8
8
9
9
```sh title="Terminal"
10
10
npx create-next-app@latest --app stack-example
11
11
cd stack-example
12
+
npx @stackframe/init-stack@latest
12
13
```
13
14
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.
15
16
16
17
<Tabs>
17
18
<Tabtitle="Setup wizard (Recommended)">
18
19
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:
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.
118
118
119
119

120
120
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:
Copy file name to clipboardExpand all lines: docs/fern/docs/pages/getting-started/users.mdx
+36-11Lines changed: 36 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
slug: getting-started/users
3
3
---
4
4
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.
6
6
7
7
## Use the current user in a client component
8
8
@@ -14,16 +14,16 @@ import { useStackApp } from "@stackframe/stack";
14
14
15
15
exportfunction MyComponent() {
16
16
const app =useStackApp();
17
-
const user =app.useUser();// or just import useUser and use it directly
17
+
const user =app.useUser();
18
18
return <div>{user?`Hello, ${user.displayName??"anon"}`:'You are not logged in'}</div>;
19
19
}
20
20
```
21
21
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()`.)
23
23
24
24
## Use the current user in a server component
25
25
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):
27
27
28
28
```tsx title="Server user profile"
29
29
import { stackServerApp } from"@/stack";
@@ -41,11 +41,27 @@ The difference between `getUser()` and `useUser()` is that `useUser()` will re-r
41
41
42
42
## Protecting a page
43
43
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).
45
49
46
50
<Tabs>
51
+
<Tabtitle="Middleware">
52
+
```tsx title="middleware.tsx"
53
+
"use client";
54
+
import { useUser } from"@stackframe/stack";
55
+
56
+
exportdefaultfunction Protected() {
57
+
useUser({ or: 'redirect' });
58
+
return <h1>You can only see this if you are logged in</h1>
59
+
}
60
+
```
61
+
</Tab>
62
+
47
63
<Tabtitle="Client Component">
48
-
```tsx title="Client-side protection"
64
+
```tsx title="my-component.tsx"
49
65
"use client";
50
66
import { useUser } from"@stackframe/stack";
51
67
@@ -57,7 +73,7 @@ Call `useUser` (or `getUser`) with the `{ or: 'redirect' }` option to protect th
57
73
</Tab>
58
74
59
75
<Tabtitle="Server Component">
60
-
```tsx title="Server-side protection"
76
+
```tsx title="my-component.tsx"
61
77
import { stackServerApp } from"@/stack";
62
78
63
79
exportdefaultasyncfunction Protected() {
@@ -68,11 +84,20 @@ Call `useUser` (or `getUser`) with the `{ or: 'redirect' }` option to protect th
68
84
</Tab>
69
85
</Tabs>
70
86
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.
71
89
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.
73
93
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
75
99
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).
76
101
77
102
<Tabs>
78
103
<Tabtitle="user.signOut()">
@@ -82,7 +107,7 @@ You can sign out the user by redirecting them to `/handler/signout` or simply by
returnuser?<buttononClick={() =>user.signOut()}>Sign Out</button>:"Not signed in";
86
111
}
87
112
```
88
113
</Tab>
@@ -174,7 +199,7 @@ To see more examples of how to use the `User` object, check out the [User API do
174
199
175
200
## Custom User Information
176
201
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:
0 commit comments