From e9bca40daf10ff18e588bc71b1d1593afdb39a9f Mon Sep 17 00:00:00 2001 From: Stan Wohlwend Date: Mon, 4 Mar 2024 03:07:12 +0100 Subject: [PATCH] Update documentation --- docs/docs/01-getting-started/01-setup.md | 94 +++++++++++ docs/docs/01-getting-started/02-users.md | 155 ++++++++++++++++++ .../docs/01-getting-started/03-server-side.md | 11 ++ .../04-going-into-production.md | 11 ++ docs/docs/01-setup.md | 83 ---------- .../01-customization/01-overview.md | 85 ++++++++++ .../02-examples}/01-signin.md | 8 +- .../02-examples}/02-signup.md | 0 .../02-examples}/_category_.json | 6 +- .../01-customization}/_category_.json | 6 +- docs/docs/02-user-and-protect-page.md | 110 ------------- .../01-app.md} | 2 +- .../02-components.md/01-stack-handler.md | 6 + .../02-components.md/01-stack-provider.md | 6 + .../02-components.md}/_category_.json | 6 +- .../02-components.md/email-verification.md | 4 + .../02-components.md/forgot-password.md | 4 + .../02-components.md/oauth-callback.md | 4 + .../02-components.md/password-reset.md | 4 + .../02-components.md/sign-in.md | 4 + .../02-components.md/sign-up.md | 4 + .../01-use-stack-app.md | 6 + .../03-standalone-hooks.md/_category_.json | 7 + .../03-standalone-hooks.md/use-user.md | 4 + docs/docs/03-custom-pages.md | 41 ----- docs/docs/04-server-usage.md | 5 - docs/docs/05-nextjs-api/02-auth.md | 5 - docs/docs/06-server-api/01-user.md | 5 - docs/docs/06-server-api/02-auth.md | 5 - docs/docusaurus.config.js | 10 +- docs/package.json | 1 + docs/sidebars.js | 30 +++- docs/src/css/custom.css | 14 ++ pnpm-lock.yaml | 5 +- 34 files changed, 475 insertions(+), 276 deletions(-) create mode 100644 docs/docs/01-getting-started/01-setup.md create mode 100644 docs/docs/01-getting-started/02-users.md create mode 100644 docs/docs/01-getting-started/03-server-side.md create mode 100644 docs/docs/01-getting-started/04-going-into-production.md delete mode 100644 docs/docs/01-setup.md create mode 100644 docs/docs/02-advanced-guides/01-customization/01-overview.md rename docs/docs/{07-pages => 02-advanced-guides/01-customization/02-examples}/01-signin.md (70%) rename docs/docs/{07-pages => 02-advanced-guides/01-customization/02-examples}/02-signup.md (100%) rename docs/docs/{07-pages => 02-advanced-guides/01-customization/02-examples}/_category_.json (53%) rename docs/docs/{06-server-api => 02-advanced-guides/01-customization}/_category_.json (50%) delete mode 100644 docs/docs/02-user-and-protect-page.md rename docs/docs/{05-nextjs-api/01-user.md => 03-api-documentation/01-app.md} (80%) create mode 100644 docs/docs/03-api-documentation/02-components.md/01-stack-handler.md create mode 100644 docs/docs/03-api-documentation/02-components.md/01-stack-provider.md rename docs/docs/{05-nextjs-api => 03-api-documentation/02-components.md}/_category_.json (52%) create mode 100644 docs/docs/03-api-documentation/02-components.md/email-verification.md create mode 100644 docs/docs/03-api-documentation/02-components.md/forgot-password.md create mode 100644 docs/docs/03-api-documentation/02-components.md/oauth-callback.md create mode 100644 docs/docs/03-api-documentation/02-components.md/password-reset.md create mode 100644 docs/docs/03-api-documentation/02-components.md/sign-in.md create mode 100644 docs/docs/03-api-documentation/02-components.md/sign-up.md create mode 100644 docs/docs/03-api-documentation/03-standalone-hooks.md/01-use-stack-app.md create mode 100644 docs/docs/03-api-documentation/03-standalone-hooks.md/_category_.json create mode 100644 docs/docs/03-api-documentation/03-standalone-hooks.md/use-user.md delete mode 100644 docs/docs/03-custom-pages.md delete mode 100644 docs/docs/04-server-usage.md delete mode 100644 docs/docs/05-nextjs-api/02-auth.md delete mode 100644 docs/docs/06-server-api/01-user.md delete mode 100644 docs/docs/06-server-api/02-auth.md diff --git a/docs/docs/01-getting-started/01-setup.md b/docs/docs/01-getting-started/01-setup.md new file mode 100644 index 000000000..420fed1bc --- /dev/null +++ b/docs/docs/01-getting-started/01-setup.md @@ -0,0 +1,94 @@ +--- +sidebar_position: 1 +--- + +# Installation & Setup + +## Installation + +To get started with the Stack, you need to have [Next.js](https://nextjs.org/docs) setup for you project. If you are starting from scratch, run the following command to create a new Next.js project: + +```bash +npx create-next-app@latest stack-example +``` + +Once you have your Next.js project setup, you can install Stack by running the following command: + +```bash +npm install @stackframe/stack +``` + +## Setup + +1. If you haven't already, [register a new account on Stack](https://app.stackframe.co). Create a project in the dashboard, create a new API Key from the left sidebar, and copy the project ID, publishable client key, and secret server key into a new file called `.env.local` in the root of your Next.js project: + + ```javascript + NEXT_PUBLIC_STACK_PROJECT_ID= + NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY= + STACK_SECRET_SERVER_KEY= + ``` + +2. Create `StackServerApp` in `lib/stack.ts`: + + ```tsx + import "server-only"; + import { StackServerApp } from "@stackframe/stack"; + + export const stackApp = new StackServerApp({ + // Automatically reads your API keys from the environment variables you set above. + // + // Alternatively, you could set them manually: + // + // projectId: process.env.NEXT_PUBLIC_STACK_PROJECT_ID, + // publishableClientKey: process.env.NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY, + // secretServerKey: process.env.STACK_SECRET_SERVER_KEY, + + tokenStore: "nextjs-cookie", // storing auth tokens in cookies + }); + ``` + + This will create a server app that you can later use to access Stack from your Next.js server. + +3. Create a new file in `app/handler/[...stack]/page.tsx` and paste the following code: + + ```tsx + import { StackHandler } from "@stackframe/stack"; + import { stackApp } from "lib/stack"; + + export default function Handler(props) { + return ; + } + ``` + + This will create pages for sign-in, sign-up, password reset, and others. Additionally, it will be used as a callback URL for OAuth. You can [replace them with your own pages](/docs/customization) later. + + +4. In your `app/layout.tsx`, wrap your entire layout with a `StackProvider`. Afterwards, it should look like this: + + ```tsx + import { StackProvider } from "@stackframe/stack"; + import { stackApp } from "@stackframe/stack"; + + export default function Layout({ children }) { + return ( + + + + {children} + + + + ); + } + ``` + + This lets you use the `useStackApp()` and `useUser()` hooks. + +5. 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`, you will see the Stack sign-up page! + + ![Stack sign up page](../imgs/signup-page.png) + + +## Next steps + +Next, we will show you how to get user information, protect a page, and modify the user profile. diff --git a/docs/docs/01-getting-started/02-users.md b/docs/docs/01-getting-started/02-users.md new file mode 100644 index 000000000..6995c73d2 --- /dev/null +++ b/docs/docs/01-getting-started/02-users.md @@ -0,0 +1,155 @@ +--- +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +# Users & Protected Pages + +In [the last section](/docs/01-setup), 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. + +## Client Components + +We can use the `useStackApp()` hook to get a `StackClientApp` object. With it, we can retrieve the current user in Client Components: + +```tsx +"use client"; +import { useStackApp } from "@stackframe/stack"; + +export function MyComponent() { + const app = useStackApp(); + const user = app.useUser(); + + return
{user ? `Hello, ${user.displayName}` : 'You are not logged in'}
; +} +``` + +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()`.) + +## Server Components + +On Server Components, you don't need `useStackApp()`. Instead, you can just import the `StackServerApp` that you created in the previous chapter: + +```tsx +import "server-only"; +import { stackApp } from "lib/stack"; + +export default async function MyComponent() { + const user = await stackApp.getUser(); + + return
{user ? `Hello, ${user.displayName}` : 'You are not logged in'}
; +} +``` + +:::info + +The difference between `getUser()` and `useUser()` is that `useUser()` will re-render the component when the user changes (for example on signout), while `getUser()` will only fetch the user once. Since Server Components cannot re-render, `useUser()` cannot be used there. + +::: + + +## Protecting a page + +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. + + + + ```tsx + "use client"; + import { useStackApp } from "@stackframe/stack"; + + export default function Protected() { + useUser({ or: 'redirect' }); + return

You can only see this if you are logged in

+ } + ``` + + + + ```tsx + import "server-only"; + import { useStackApp } from "@stackframe/stack"; + + export default async function Protected() { + await stack.getUser({ or: 'redirect' }); + return

You can only see this if you are logged in

+ } + ``` + + + +## Examples + +### User profile + +Stack automatically creates a user profile on sign-up. Let's create a page that displays this information. + +Depending on whether you want to use a Client or Server Component, copy the following code into `app/page.tsx`: + + + +```tsx +'use client'; +import { useStackApp } from "@stackframe/stack"; + +export default function PageClient() { + const app = useStackApp(); + return ( +
+

Home

+ {user ? ( +
+

Welcome, {user.displayName}

+

Your e-mail: {user.primaryEmail}

+

Your e-mail verification status: {user.primaryEmailVerified}

+ +
+ ) : ( +
+

You are not logged in

+ + +
+ )} +
+ ); +} +``` + + + +```tsx +import "server-only"; +import { stack } from "../lib/stack"; + +export default async function Page() { + const user = await stack.getUser(); + return ( +
+

Home

+ {user ? ( +
+

Welcome, {user.displayName}

+

Your e-mail: {user.primaryEmail}

+

Your e-mail verification status: {user.primaryEmailVerified}

+ +
+ ) : ( +
+

You are not logged in

+ + +
+ )} +
+ ); +} +``` + + + +## Next steps + +Next, we will take a look at the actions that can be taken from the server-side. diff --git a/docs/docs/01-getting-started/03-server-side.md b/docs/docs/01-getting-started/03-server-side.md new file mode 100644 index 000000000..2edbd7f1c --- /dev/null +++ b/docs/docs/01-getting-started/03-server-side.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 3 +--- + +# Server-Side App + +Compared to `StackClientApp` (which is available to everyone with just a publishable client key), `StackServerApp` has some extra features. Particularly, it can be used to view & modify *other* users. Hence, it is crucial to keep the secret server key secure. + +## Next steps + +Next, we will try to understand what steps we need to go into production. diff --git a/docs/docs/01-getting-started/04-going-into-production.md b/docs/docs/01-getting-started/04-going-into-production.md new file mode 100644 index 000000000..021807869 --- /dev/null +++ b/docs/docs/01-getting-started/04-going-into-production.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 4 +--- + +# Going Into Production + +// TODO + +## Next steps + +Next, we will show how to customize or create your own custom pages. diff --git a/docs/docs/01-setup.md b/docs/docs/01-setup.md deleted file mode 100644 index 805e0daae..000000000 --- a/docs/docs/01-setup.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Install & Setup - -## Installation - -To get started with the Stack, you need to have [Next.js](https://nextjs.org/docs) setup for you project. If you are starting from scratch, run the following command to create a new Next.js project: - -```bash -npx create-next-app@latest stack-example -``` - -Once you have your Next.js project setup, you can install Stack by running the following command: - -```bash -npm install @stack/next -``` - -## Setup - -1. Register an account on Stack [here](https://stack.app) if you don't already have and account. Create an project in the dashboard, and put the Project ID, publishable client key, and secret server key in the `.env.local` file in the root of your Next.js project like this: - - ```javascript - NEXT_PUBLIC_STACK_PROJECT_ID= - NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY= - STACK_SECRET_SERVER_KEY= - ``` - -2. Create `StackServerApp` in `lib/stack.ts`: - - ```tsx - import { StackServerApp } from '@stack/next'; - - export const stack = new StackServerApp({ - tokenStore: "nextjs-cookie", // storing auth tokens in cookies - }); - ``` - - This will create a server app that handles all the server side functions. You can import it from other files to use the functions bind to it. - -3. Create a new file and its parent folders in the Next.js app folder: `app/handler/[...stack]/page.tsx`. Then add the following code to the file: - - ```tsx - import { StackHandler } from "stack"; - import { stackServerApp } from "lib/stack"; - - export default function Handler(props) { - return ; - } - ``` - - The handler will be handle all the pages like `signin`, `signup`, `password-reset`, etc. automatically for you. You can later customize and change the route of these pages easily. - - -4. In your `app/layout.tsx`, add the `StackProvider`, it should look something like this: - ```tsx - import { StackProvider } from '@stack/next'; - import { stack } from 'lib/stack'; - - export default function Layout({ children }) { - return ( - - - - {children} - - - - ); - } - ``` - - The provider will provide information to the frontend functions and hooks. - -5. That's it! Stack is not 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`, you should see the Stack signup page liek this: - ![Stack sign up page](./imgs/signup-page.png) - - -## Next steps - -Now you have a basic stack setup in your Next.js project and you can already access all the features like signup, signin, reset password, etc. In the next section, we will show you how to protect a page, get user information, and using functions like signout. \ No newline at end of file diff --git a/docs/docs/02-advanced-guides/01-customization/01-overview.md b/docs/docs/02-advanced-guides/01-customization/01-overview.md new file mode 100644 index 000000000..7cb9c766f --- /dev/null +++ b/docs/docs/02-advanced-guides/01-customization/01-overview.md @@ -0,0 +1,85 @@ +--- +sidebar_position: 1 +title: Overview +--- + +# Customization Overview + +Stack provides two ways to customize the UI: + +- **CSS customization**: You can modify default UI looks by overriding the styles of class names beginning with `wl_`, such as `wl_btn`. +- **Custom pages**: You can create custom pages for sign in, sign up, reset password and more, thanks to built-in components. +- **From scratch**: If all else fails, you can always reimplement our components from scratch with the helper functions that we provide. + +## CSS customization + +You can modify the default UI looks by overriding the styles of class names beginning with `wl_`, such as `wl_btn`. (Please stay tuned — we're updating this part of the documentation!) + +## Custom pages + +By default, `StackHandler` creates all pages you need. However, if you'd like a bit of additional control, you can always use our built-in components (such as ``) to build your own pages for all features. For example, if you have the following in `app/signin/page.tsx`: + +```tsx +import { SignIn } from "@stackframe/stack"; + +export default function CustomSignInPage() { + return
+

My Custom Sign In page

+ +
; +} +``` + +Then you can instruct the Stack app in `lib/stack.ts` to use your custom sign in page: + +```tsx +export const stackApp = new StackServerApp({ + // ... + // add these three lines + urls: { + signIn: '/signin', + } +}); +``` + +You are now all set! If you visit the `/signin` page, you should see your custom sign in page. If your user visits a protected page or the old `/handler/signin` URL, they will be redirected to your new sign-in page. + +For more examples, please refer to the [Examples](/docs/category/examples). + + +## From scratch + +We also provide the low-level functions powering our components, so that you can build your own logic. For example, to build a custom OAuth sign-in button, create a file at `app/signin/page.tsx`: + +```tsx +"use client"; +import { useStackApp } from "@stackframe/stack"; + +export default function CustomOAuthSignInPage() { + const app = useStackApp(); + + return
+

My Custom Sign In page

+ +
; +} +``` + +Again, edit the Stack app in `lib/stack.ts` to use your custom sign in page: + +```tsx +export const stackApp = new StackServerApp({ + // ... + // add these three lines + urls: { + signIn: '/signin', + } +}); +``` + +As above, visit the `/signin` page to see your newly created custom OAuth page. + + +## Next steps + +Take a look at the [customization examples](/docs/category/examples) to see how to build custom pages for sign in, sign up, reset password, and more. diff --git a/docs/docs/07-pages/01-signin.md b/docs/docs/02-advanced-guides/01-customization/02-examples/01-signin.md similarity index 70% rename from docs/docs/07-pages/01-signin.md rename to docs/docs/02-advanced-guides/01-customization/02-examples/01-signin.md index 22896f610..db6c4eb83 100644 --- a/docs/docs/07-pages/01-signin.md +++ b/docs/docs/02-advanced-guides/01-customization/02-examples/01-signin.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Sign In -## Default Sign In Component +## Custom page with `SignIn` component ```tsx 'use client'; @@ -13,11 +13,11 @@ import { useStackApp, SignIn } from "stack"; export default function DefaultSignIn() { const app = useStackApp(); - return ; + return ; } ``` -Note that if you don't pass in a `redirectUrl`, the user will be redirected to the same page, which is useful if you want to build a sign in modal. +`redirectUrl` is optional and defaults to the current page. ## Custom OAuth Sign In @@ -40,4 +40,4 @@ export default function CustomOAuthSignIn() { ## Custom Credential Sign In -```tsx \ No newline at end of file +```tsx diff --git a/docs/docs/07-pages/02-signup.md b/docs/docs/02-advanced-guides/01-customization/02-examples/02-signup.md similarity index 100% rename from docs/docs/07-pages/02-signup.md rename to docs/docs/02-advanced-guides/01-customization/02-examples/02-signup.md diff --git a/docs/docs/07-pages/_category_.json b/docs/docs/02-advanced-guides/01-customization/02-examples/_category_.json similarity index 53% rename from docs/docs/07-pages/_category_.json rename to docs/docs/02-advanced-guides/01-customization/02-examples/_category_.json index 0247a0031..37ad9f38a 100644 --- a/docs/docs/07-pages/_category_.json +++ b/docs/docs/02-advanced-guides/01-customization/02-examples/_category_.json @@ -1,7 +1,7 @@ { - "label": "Pages", - "position": 7, + "label": "Examples", + "position": 2, "link": { "type": "generated-index" } -} \ No newline at end of file +} diff --git a/docs/docs/06-server-api/_category_.json b/docs/docs/02-advanced-guides/01-customization/_category_.json similarity index 50% rename from docs/docs/06-server-api/_category_.json rename to docs/docs/02-advanced-guides/01-customization/_category_.json index 696ea49f6..e899ec708 100644 --- a/docs/docs/06-server-api/_category_.json +++ b/docs/docs/02-advanced-guides/01-customization/_category_.json @@ -1,7 +1,7 @@ { - "label": "Server API", - "position": 6, + "label": "Customization", + "position": 1, "link": { "type": "generated-index" } -} \ No newline at end of file +} diff --git a/docs/docs/02-user-and-protect-page.md b/docs/docs/02-user-and-protect-page.md deleted file mode 100644 index 7ca49f2a3..000000000 --- a/docs/docs/02-user-and-protect-page.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -sidebar_position: 2 ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - -# User and Protect Page - -## User information page - -Let's create a home page which will show the user name and a log out button when the user is logged in, and links to the login and signup when the user is not logged in. Let's create a page in `app/page.tsx`. - -Note that if you are using client component, you have to put this in a separate file like `apps/page-client.tsx` and import it in the `app/page.tsx` file. - - - -```tsx -'use client'; -import { useUser, redirectToSignIn, redirectToSignUp, signOut } from '@stack/next'; - -export default function Home() { - const user = useUser(); - return ( -
-

Home

- {user ? ( -
-

Welcome, {user.displayName}

- -
- ) : ( -
-

You are not logged in

- - -
- )} -
- ); -} -``` - - - -```tsx -import { stack } from '../lib/stack'; - -export default function Page() { - const user = await stack.getUser(); - return ( -
-

Home

- {user ? ( -
-

Welcome, {user.displayName}

- Sign Out -
- ) : ( -
-

You are not logged in

- Sign in - Sign up -
- )} -
- ); -} -``` - - - -Now if you navigate to `http://localhost:3000`, you should see the home page. - -## Protect a page - -If you want to protect a page so that only logged in users can access it, you can add `{ or: 'redirect' }` to the `useUser` hook or `stack.getUser` function. Here is an example server side example: - - - -```tsx -'use client'; -import { useUser, redirectToSignIn } from '@stack/next'; - -export default function Protected() { - useUser({ or: 'redirect' }); - return

You can only see this if you are logged in

-} -``` - - - -```tsx -import { stack } from '../lib/stack'; - -export default function Protected() { - await stack.getUser({ or: 'redirect' }); - return

You can only see this if you are logged in

-} -``` - - - -## Next steps - -Now you have a basic stack setup in your Next.js project and you also know how to use and interact with the stack functions. In the next sections, we will show how to customize or create your own custom pages and how to use stack in your backend server. - - - diff --git a/docs/docs/05-nextjs-api/01-user.md b/docs/docs/03-api-documentation/01-app.md similarity index 80% rename from docs/docs/05-nextjs-api/01-user.md rename to docs/docs/03-api-documentation/01-app.md index 65dd77fa3..2d90e4232 100644 --- a/docs/docs/05-nextjs-api/01-user.md +++ b/docs/docs/03-api-documentation/01-app.md @@ -2,4 +2,4 @@ sidebar_position: 1 --- -# User +# App diff --git a/docs/docs/03-api-documentation/02-components.md/01-stack-handler.md b/docs/docs/03-api-documentation/02-components.md/01-stack-handler.md new file mode 100644 index 000000000..955deeaf6 --- /dev/null +++ b/docs/docs/03-api-documentation/02-components.md/01-stack-handler.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 1 +sidebar_class_name: starred +--- + +# StackHandler diff --git a/docs/docs/03-api-documentation/02-components.md/01-stack-provider.md b/docs/docs/03-api-documentation/02-components.md/01-stack-provider.md new file mode 100644 index 000000000..ad8348fed --- /dev/null +++ b/docs/docs/03-api-documentation/02-components.md/01-stack-provider.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 1 +sidebar_class_name: starred +--- + +# StackProvider diff --git a/docs/docs/05-nextjs-api/_category_.json b/docs/docs/03-api-documentation/02-components.md/_category_.json similarity index 52% rename from docs/docs/05-nextjs-api/_category_.json rename to docs/docs/03-api-documentation/02-components.md/_category_.json index 00ff50694..ff09c4e29 100644 --- a/docs/docs/05-nextjs-api/_category_.json +++ b/docs/docs/03-api-documentation/02-components.md/_category_.json @@ -1,7 +1,7 @@ { - "label": "Next.js API", - "position": 5, + "label": "Components", + "position": 2, "link": { "type": "generated-index" } -} \ No newline at end of file +} diff --git a/docs/docs/03-api-documentation/02-components.md/email-verification.md b/docs/docs/03-api-documentation/02-components.md/email-verification.md new file mode 100644 index 000000000..f5d98e445 --- /dev/null +++ b/docs/docs/03-api-documentation/02-components.md/email-verification.md @@ -0,0 +1,4 @@ +--- +--- + +# EmailVerification diff --git a/docs/docs/03-api-documentation/02-components.md/forgot-password.md b/docs/docs/03-api-documentation/02-components.md/forgot-password.md new file mode 100644 index 000000000..a03368acd --- /dev/null +++ b/docs/docs/03-api-documentation/02-components.md/forgot-password.md @@ -0,0 +1,4 @@ +--- +--- + +# ForgotPassword diff --git a/docs/docs/03-api-documentation/02-components.md/oauth-callback.md b/docs/docs/03-api-documentation/02-components.md/oauth-callback.md new file mode 100644 index 000000000..16103e03e --- /dev/null +++ b/docs/docs/03-api-documentation/02-components.md/oauth-callback.md @@ -0,0 +1,4 @@ +--- +--- + +# OauthCallback diff --git a/docs/docs/03-api-documentation/02-components.md/password-reset.md b/docs/docs/03-api-documentation/02-components.md/password-reset.md new file mode 100644 index 000000000..bba8b6472 --- /dev/null +++ b/docs/docs/03-api-documentation/02-components.md/password-reset.md @@ -0,0 +1,4 @@ +--- +--- + +# PasswordReset diff --git a/docs/docs/03-api-documentation/02-components.md/sign-in.md b/docs/docs/03-api-documentation/02-components.md/sign-in.md new file mode 100644 index 000000000..d9899256e --- /dev/null +++ b/docs/docs/03-api-documentation/02-components.md/sign-in.md @@ -0,0 +1,4 @@ +--- +--- + +# SignIn diff --git a/docs/docs/03-api-documentation/02-components.md/sign-up.md b/docs/docs/03-api-documentation/02-components.md/sign-up.md new file mode 100644 index 000000000..e73aac30f --- /dev/null +++ b/docs/docs/03-api-documentation/02-components.md/sign-up.md @@ -0,0 +1,4 @@ +--- +--- + +# SignUp diff --git a/docs/docs/03-api-documentation/03-standalone-hooks.md/01-use-stack-app.md b/docs/docs/03-api-documentation/03-standalone-hooks.md/01-use-stack-app.md new file mode 100644 index 000000000..23e68a537 --- /dev/null +++ b/docs/docs/03-api-documentation/03-standalone-hooks.md/01-use-stack-app.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 1 +sidebar_class_name: starred +--- + +# useStackApp diff --git a/docs/docs/03-api-documentation/03-standalone-hooks.md/_category_.json b/docs/docs/03-api-documentation/03-standalone-hooks.md/_category_.json new file mode 100644 index 000000000..da500366b --- /dev/null +++ b/docs/docs/03-api-documentation/03-standalone-hooks.md/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Standalone Hooks", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/docs/docs/03-api-documentation/03-standalone-hooks.md/use-user.md b/docs/docs/03-api-documentation/03-standalone-hooks.md/use-user.md new file mode 100644 index 000000000..3d5ad9b9e --- /dev/null +++ b/docs/docs/03-api-documentation/03-standalone-hooks.md/use-user.md @@ -0,0 +1,4 @@ +--- +--- + +# useUser diff --git a/docs/docs/03-custom-pages.md b/docs/docs/03-custom-pages.md deleted file mode 100644 index b0c5fd05b..000000000 --- a/docs/docs/03-custom-pages.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Custom Pages - -Stack handler automatically creates all the pages you need with a good default design, so you can get started very quickly without any extra setup. However, if you want to customize the look or even have some special logic, you can create your own pages and tell the handler to redirect to your pages instead. - -## Custom OAuth sign in page - -Here we show an example of how to create a simple custom OAuth sign in page. For demostration purpose, we won't style it, but you can choose your favorite UI framework and make it look good! If you want to know how to build other custome pages like credential sign in, signup, or reset password, you can find detailed information of all the pages are in the [Custom Pages](/docs/category/pages) section. - -Create a new file `app/signin/page.tsx` and add the following code: - -```tsx -'use client'; -import { useStackApp } from "stack"; - -export default function CustomOAuthSignIn() { - const app = useStackApp(); - - return
-

My Custom Sign In page

- -
; -} -``` - -Now, to let the handler know that you are going to use your custom sign in page, you need to setup the url in the `StackServerApp`, which should locate in `lib/stack.ts` if you followed the previous tutorial: - -```tsx -import { StackServerApp } from '@stack/next'; - -export const stack = new StackServerApp({ - urls: { - signIn: '/signin', - } -}); -``` - -You are now all set! If you visit the `/signin` page, you should see your custom sign in page. Also when the user goes to a protected page, stack will automatically redirect you to your custom sign in page. diff --git a/docs/docs/04-server-usage.md b/docs/docs/04-server-usage.md deleted file mode 100644 index 468bbab2e..000000000 --- a/docs/docs/04-server-usage.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Server Usage diff --git a/docs/docs/05-nextjs-api/02-auth.md b/docs/docs/05-nextjs-api/02-auth.md deleted file mode 100644 index 5f9e637b6..000000000 --- a/docs/docs/05-nextjs-api/02-auth.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Auth diff --git a/docs/docs/06-server-api/01-user.md b/docs/docs/06-server-api/01-user.md deleted file mode 100644 index 65dd77fa3..000000000 --- a/docs/docs/06-server-api/01-user.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 1 ---- - -# User diff --git a/docs/docs/06-server-api/02-auth.md b/docs/docs/06-server-api/02-auth.md deleted file mode 100644 index 5f9e637b6..000000000 --- a/docs/docs/06-server-api/02-auth.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Auth diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 5cc19779a..4c55a7266 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -13,14 +13,14 @@ const config = { favicon: "img/favicon.ico", // Set the production url of your site here - url: "https://your-docusaurus-site.example.com", + url: "https://docs.stackframe.co", // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' baseUrl: "/", // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. - organizationName: "facebook", // Usually your GitHub org/user name. + organizationName: "stackframe-projects", // Usually your GitHub org/user name. projectName: "docusaurus", // Usually your repo name. onBrokenLinks: "throw", @@ -54,9 +54,6 @@ const config = { themeConfig: /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ - prism: { - additionalLanguages: ["bash"], - }, colorMode: { defaultMode: "dark", disableSwitch: true, @@ -74,7 +71,7 @@ const config = { items: [ { type: "docSidebar", - sidebarId: "tutorialSidebar", + sidebarId: "docsSidebar", position: "left", label: "Documentation", }, @@ -88,6 +85,7 @@ const config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, + additionalLanguages: ["bash"], }, }), }; diff --git a/docs/package.json b/docs/package.json index 04ade1717..37dc93a42 100644 --- a/docs/package.json +++ b/docs/package.json @@ -17,6 +17,7 @@ "dependencies": { "@docusaurus/core": "3.1.1", "@docusaurus/preset-classic": "3.1.1", + "@docusaurus/plugin-content-docs": "3.1.1", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", "prism-react-renderer": "^2.3.0", diff --git a/docs/sidebars.js b/docs/sidebars.js index 999cd6b61..d61aa834b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -2,7 +2,35 @@ /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { - tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], + docsSidebar: [ + { + type: 'html', + value: 'Getting Started', + className: 'sidebar-title', + }, + { + type: 'autogenerated', + dirName: '01-getting-started', + }, + { + type: 'html', + value: 'Advanced Guides', + className: 'sidebar-title', + }, + { + type: 'autogenerated', + dirName: '02-advanced-guides', + }, + { + type: 'html', + value: 'API Documentation', + className: 'sidebar-title', + }, + { + type: 'autogenerated', + dirName: '03-api-documentation', + }, + ], }; export default sidebars; diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index f9e2bc80c..4b6f5f46d 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -23,3 +23,17 @@ html[data-theme='dark'] { .prism-code { background-color: rgb(15,23,42,50) !important; } + +.sidebar-title { + font-size: 0.7rem; + font-weight: bold; + opacity: 70%; + margin-top: 1.5rem; + text-transform: uppercase; +} + +.starred > a::before { + content: "★"; + color: #f0d000; + margin-right: 0.25rem; +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 17a4cf3d4..b77f133c5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -136,6 +136,9 @@ importers: '@docusaurus/core': specifier: 3.1.1 version: 3.1.1(@docusaurus/types@3.1.1)(eslint@8.30.0)(react-dom@18.2.0)(react@18.2.0)(typescript@5.3.3) + '@docusaurus/plugin-content-docs': + specifier: 3.1.1 + version: 3.1.1(eslint@8.30.0)(react-dom@18.2.0)(react@18.2.0)(typescript@5.3.3) '@docusaurus/preset-classic': specifier: 3.1.1 version: 3.1.1(@algolia/client-search@4.22.1)(@types/react@18.2.60)(eslint@8.30.0)(react-dom@18.2.0)(react@18.2.0)(search-insights@2.13.0)(typescript@5.3.3) @@ -2217,7 +2220,7 @@ packages: react-dom: 18.2.0(react@18.2.0) tslib: 2.6.2 utility-types: 3.11.0 - webpack: 5.90.1 + webpack: 5.90.3 transitivePeerDependencies: - '@parcel/css' - '@rspack/core'