mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-04 21:04:37 +08:00
Improve documentation with minor enhancements and fixes (#466)
This commit is contained in:
devin-ai-integration[bot]
GitHub
parent
61a27c40ea
commit
625c0abcb7
@ -2,9 +2,9 @@
|
||||
slug: customization/custom-pages
|
||||
---
|
||||
|
||||
If you want to have full control over the layout and logic flow, you can build your own pages using our built-in components or low-level functions.
|
||||
Custom pages allow you to take full control over the layout and logic flow of authentication pages in your application. Instead of using the default pages provided by Stack Auth, you can build your own using our built-in components or low-level functions.
|
||||
|
||||
By default, `StackHandler` creates all pages you need, however, you can replace them with your own pages.
|
||||
By default, `StackHandler` creates all authentication pages you need, however, you can replace them with your own custom implementations for a more tailored user experience.
|
||||
|
||||
## Simple Example
|
||||
|
||||
@ -35,12 +35,14 @@ export const stackServerApp = new StackServerApp({
|
||||
});
|
||||
```
|
||||
|
||||
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/sign-in` URL, they will be redirected to your new sign-in page.
|
||||
You are now all set! If you visit the `/signin` page, you should see your custom sign in page. When users attempt to access a protected page or navigate to the default `/handler/sign-in` URL, they will automatically be redirected to your new custom sign-in page.
|
||||
|
||||
For more examples, please refer to the [Examples](../customization/custom-pages.mdx).
|
||||
|
||||
|
||||
## From scratch
|
||||
## Building From Scratch
|
||||
|
||||
While the simple approach above lets you customize the layout while using Stack's pre-built components, sometimes you need complete control over both the UI and authentication logic.
|
||||
|
||||
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`:
|
||||
|
||||
@ -55,7 +57,7 @@ export default function CustomOAuthSignIn() {
|
||||
<div>
|
||||
<h1>My Custom Sign In page</h1>
|
||||
<button onClick={async () => {
|
||||
// this will redirect to the OAuth provider's login page
|
||||
// This will redirect to the OAuth provider's login page.
|
||||
await app.signInWithOAuth('google');
|
||||
}}>
|
||||
Sign In with Google
|
||||
|
||||
@ -2,37 +2,37 @@
|
||||
slug: customization/custom-styles
|
||||
---
|
||||
|
||||
If you want to spend minimal time on styling but still want to align with your brand, you can customize the colors of the Stack app. Colors are stored in React context and can be easily overridden.
|
||||
Customizing the styles of your Stack Auth components allows you to maintain your brand identity while leveraging the pre-built functionality. This approach is ideal when you want to quickly align the authentication UI with your application's design system without building custom components from scratch. Stack's theming system uses a React context to store colors and styling variables that can be easily overridden.
|
||||
|
||||
There are some color variables that you can customize:
|
||||
You can customize the following color variables to match your brand:
|
||||
|
||||
- `background`
|
||||
- `foreground`
|
||||
- `card`
|
||||
- `cardForeground`
|
||||
- `popover`
|
||||
- `popoverForeground`
|
||||
- `primary`
|
||||
- `primaryForeground`
|
||||
- `secondary`
|
||||
- `secondaryForeground`
|
||||
- `muted`
|
||||
- `mutedForeground`
|
||||
- `accent`
|
||||
- `accentForeground`
|
||||
- `destructive`
|
||||
- `destructiveForeground`
|
||||
- `border`
|
||||
- `input`
|
||||
- `ring`
|
||||
- `background`: Main background color of the application
|
||||
- `foreground`: Main text color on the background
|
||||
- `card`: Background color for card elements
|
||||
- `cardForeground`: Text color for card elements
|
||||
- `popover`: Background color for popover elements like dropdowns
|
||||
- `popoverForeground`: Text color for popover elements
|
||||
- `primary`: Primary brand color, used for buttons and important elements
|
||||
- `primaryForeground`: Text color on primary-colored elements
|
||||
- `secondary`: Secondary color for less prominent elements
|
||||
- `secondaryForeground`: Text color on secondary-colored elements
|
||||
- `muted`: Color for muted or disabled elements
|
||||
- `mutedForeground`: Text color for muted elements
|
||||
- `accent`: Accent color for highlights and emphasis
|
||||
- `accentForeground`: Text color on accent-colored elements
|
||||
- `destructive`: Color for destructive actions like delete buttons
|
||||
- `destructiveForeground`: Text color on destructive elements
|
||||
- `border`: Color used for borders
|
||||
- `input`: Border color for input fields
|
||||
- `ring`: Focus ring color for interactive elements
|
||||
|
||||
And some other variables:
|
||||
|
||||
- `radius`: border radius of components like buttons, inputs, etc.
|
||||
|
||||
These variables are css variables so you can use the syntax like `hsl(0, 0%, 0%)`, `black`, `#fff`, etc.
|
||||
These variables are CSS variables so you can use any valid CSS color syntax like `hsl(0, 0%, 0%)`, `black`, `#fff`, `rgb(255, 0, 0)`, etc.
|
||||
|
||||
The colors can be different for light and dark mode. You can pass these into the `StackTheme` component (in your `layout.tsx` file if you followed the Getting Started guide) as follows:
|
||||
The colors can be different for light and dark mode, allowing you to create a cohesive experience across both themes. You can pass these into the `StackTheme` component (in your `layout.tsx` file if you followed the Getting Started guide) as follows:
|
||||
|
||||
```jsx title="app/layout.tsx"
|
||||
const theme = {
|
||||
|
||||
@ -2,7 +2,9 @@
|
||||
slug: customization/dark-mode
|
||||
---
|
||||
|
||||
Stack components support light and dark mode out of the box. You can switch between light and dark mode using [next-themes](https://github.com/pacocoursey/next-themes) (or any other library that changes the `data-theme` or `class` to `dark` or `light` attribute of the `html` element).
|
||||
Stack components support light and dark mode out of the box. All UI components automatically adapt their colors, shadows, and contrast levels based on the selected theme.
|
||||
|
||||
You can switch between light and dark mode using [next-themes](https://github.com/pacocoursey/next-themes) (or any other library that changes the `data-theme` or `class` to `dark` or `light` attribute of the `html` element).
|
||||
|
||||
Here is an example of how to set up next-themes with Stack (find more details in the [next-themes documentation](https://github.com/pacocoursey/next-themes)):
|
||||
|
||||
@ -19,7 +21,13 @@ Here is an example of how to set up next-themes with Stack (find more details in
|
||||
|
||||
export default function Layout({ children }) {
|
||||
return (
|
||||
<ThemeProvider>
|
||||
{/*
|
||||
ThemeProvider enables theme switching throughout the application.
|
||||
defaultTheme="system" uses the user's system preference as the default.
|
||||
attribute="class" applies the theme by changing the class on the html element.
|
||||
*/}
|
||||
<ThemeProvider defaultTheme="system" attribute="class">
|
||||
{/* StackTheme ensures Stack components adapt to the current theme */}
|
||||
<StackTheme>
|
||||
{children}
|
||||
</StackTheme>
|
||||
@ -35,10 +43,16 @@ Here is an example of how to set up next-themes with Stack (find more details in
|
||||
import { useTheme } from 'next-themes'
|
||||
|
||||
export default function ColorModeSwitcher() {
|
||||
// useTheme hook provides the current theme and a function to change it
|
||||
const { theme, setTheme } = useTheme()
|
||||
|
||||
return (
|
||||
<button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
|
||||
Toggle theme
|
||||
<button
|
||||
onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}
|
||||
aria-label="Toggle dark mode"
|
||||
>
|
||||
{/* Display different text based on current theme */}
|
||||
{theme === 'light' ? 'Switch to dark mode' : 'Switch to light mode'}
|
||||
</button>
|
||||
)
|
||||
}
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
slug: customization/internationalization
|
||||
---
|
||||
|
||||
Internationalization (i18n) allows your application to support multiple languages, making it accessible to users worldwide. Stack Auth provides built-in internationalization support for its components, enabling you to offer a localized authentication experience with minimal effort.
|
||||
|
||||
## Setup
|
||||
|
||||
Internationalization with Stack is very straightforward. Simply pass the `lang` prop to the `StackProvider` component, and all the pages will be translated to the specified language.
|
||||
@ -16,7 +18,7 @@ Internationalization with Stack is very straightforward. Simply pass the `lang`
|
||||
|
||||
By default, if no language is provided, it will be set to `en-US`.
|
||||
|
||||
You can choose which languages to use by employing your own methods, such as storing the language in `localStorage` or using the user's browser language.
|
||||
You can choose which languages to use by employing your own methods, such as storing the language in `localStorage` or using the user's browser language.
|
||||
|
||||
## Supported languages
|
||||
|
||||
@ -28,4 +30,4 @@ You can choose which languages to use by employing your own methods, such as sto
|
||||
- `fr-FR`: French (France)
|
||||
- `it-IT`: Italian (Italy)
|
||||
- `pt-BR`: Portuguese (Brazil)
|
||||
- `pt-PT`: Portuguese (Portugal)
|
||||
- `pt-PT`: Portuguese (Portugal)
|
||||
|
||||
@ -2,20 +2,44 @@
|
||||
slug: customization/page-examples/forgot-password
|
||||
---
|
||||
|
||||
This page provides examples of how to create custom "forgot password" pages for your application. The forgot password functionality allows users to request a password reset email when they can't remember their current password.
|
||||
|
||||
## Custom page with `ForgotPassword` component
|
||||
|
||||
The `ForgotPassword` component provides a complete form for users to request a password reset email. When a user submits their email, Stack Auth will send them an email with a link to reset their password.
|
||||
|
||||
```tsx
|
||||
'use client';
|
||||
import { ForgotPassword } from "@stackframe/stack";
|
||||
|
||||
export default function DefaultPasswordReset() {
|
||||
export default function DefaultForgotPassword() {
|
||||
return <ForgotPassword />;
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with Application Routing
|
||||
|
||||
To integrate the forgot password page with your application's routing:
|
||||
|
||||
1. Create a route for your forgot password page (e.g., `/forgot-password`)
|
||||
2. Configure Stack Auth to use your custom route in your `stack.ts` file:
|
||||
|
||||
```tsx
|
||||
export const stackServerApp = new StackServerApp({
|
||||
// ...
|
||||
urls: {
|
||||
forgotPassword: '/forgot-password',
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
This ensures that links to the forgot password page will direct users to your custom implementation. When a user submits their email, Stack Auth will send them an email with a link to the password reset page configured in your application.
|
||||
|
||||
|
||||
## Custom forgot password form
|
||||
|
||||
If you need more control over the forgot password process, you can build your own form. This approach allows you to customize the UI and error handling to match your application's design.
|
||||
|
||||
```tsx
|
||||
'use client';
|
||||
|
||||
@ -29,11 +53,25 @@ export default function CustomForgotPasswordForm() {
|
||||
const app = useStackApp();
|
||||
|
||||
const onSubmit = async () => {
|
||||
if (!email) {
|
||||
setError('Please enter your email address');
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
await app.sendForgotPasswordEmail(email);
|
||||
setMessage('Password reset email sent! Please check your inbox.');
|
||||
const result = await app.sendForgotPasswordEmail(email);
|
||||
if (result?.status === 'error') {
|
||||
if (result.error.code === 'user_not_found') {
|
||||
// For security reasons, don't reveal if a user exists or not
|
||||
setMessage('If an account exists with this email, a password reset link has been sent.');
|
||||
} else {
|
||||
setError(`Error: ${result.error.message}`);
|
||||
}
|
||||
} else {
|
||||
setMessage('Password reset email sent! Please check your inbox.');
|
||||
}
|
||||
} catch (err) {
|
||||
setError(err.message);
|
||||
setError(`An unexpected error occurred: ${err.message}`);
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
@ -2,8 +2,12 @@
|
||||
slug: customization/page-examples/password-reset
|
||||
---
|
||||
|
||||
This page provides examples of how to create custom password reset pages for your application. Password reset functionality allows users to securely create a new password when they've forgotten their current one.
|
||||
|
||||
## Custom page with `PasswordReset` component
|
||||
|
||||
The `PasswordReset` component provides a complete password reset form with built-in validation and error handling. This is the simplest way to add password reset functionality to your application.
|
||||
|
||||
```tsx
|
||||
'use client';
|
||||
import { PasswordReset } from "@stackframe/stack";
|
||||
@ -13,9 +17,32 @@ export default function DefaultPasswordReset() {
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with Application Routing
|
||||
|
||||
To integrate the password reset page with your application's routing:
|
||||
|
||||
1. Create a route handler that extracts the reset code from the URL (e.g., `/reset-password?code=xyz123`)
|
||||
2. Pass the code to your password reset component
|
||||
3. Configure Stack Auth to use your custom route in your `stack.ts` file:
|
||||
|
||||
```tsx
|
||||
export const stackServerApp = new StackServerApp({
|
||||
// ...
|
||||
urls: {
|
||||
passwordReset: '/reset-password',
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
This ensures that password reset links in emails will direct users to your custom page.
|
||||
|
||||
|
||||
## Custom password reset form
|
||||
|
||||
If you need more control over the password reset process, you can build your own form using the Stack Auth API. This approach allows you to customize the UI and error handling to match your application's design.
|
||||
|
||||
The `code` parameter used below is typically extracted from the URL query parameters. This code is sent to the user's email when they request a password reset and is required to validate the reset request.
|
||||
|
||||
```tsx
|
||||
'use client';
|
||||
|
||||
@ -43,7 +70,7 @@ export default function CustomPasswordResetForm({ code }: { code: string }) {
|
||||
}
|
||||
setSuccess(true);
|
||||
} catch (err) {
|
||||
setError(err.message);
|
||||
setError(`An unexpected error occurred: ${err.message}`);
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
@ -1,7 +1,11 @@
|
||||
---
|
||||
slug: customization/page-examples/signin
|
||||
slug: customization/page-examples/sign-in
|
||||
---
|
||||
|
||||
# Sign-In Page Examples
|
||||
|
||||
This page provides examples of how to create custom sign-in pages for your application using Stack Auth components and functions.
|
||||
|
||||
## Custom page with `SignIn` component
|
||||
|
||||
```tsx
|
||||
@ -16,16 +20,16 @@ export default function DefaultSignIn() {
|
||||
}
|
||||
```
|
||||
|
||||
You can also use `useUser` at the beginning of the sign in page to check if wether the user is already signed in and redirect them to some other page if they are.
|
||||
You can also use `useUser` at the beginning of the sign-in page to check whether the user is already signed in and redirect them to another page if they are.
|
||||
|
||||
|
||||
## Other useful components
|
||||
|
||||
`CredentialSignIn`: A component that contains a form for signing in with email and password.
|
||||
`CredentialSignIn`: A component that renders a complete form for signing in with email and password. It handles validation, error states, and submission automatically.
|
||||
|
||||
`OAuthGroup`: A list of available OAuth provider signin buttons components. The available provider list is fetched from the server.
|
||||
`OAuthGroup`: A component that displays a list of available OAuth provider sign-in buttons. The available provider list is automatically fetched from the server based on your project configuration.
|
||||
|
||||
`OAuthButton`: A single OAuth sign in button.
|
||||
`OAuthButton`: A component that renders a single OAuth sign-in button for a specific provider. Use this when you only want to offer specific OAuth providers.
|
||||
|
||||
|
||||
## Custom OAuth Sign In
|
||||
@ -41,7 +45,7 @@ export default function CustomOAuthSignIn() {
|
||||
<div>
|
||||
<h1>My Custom Sign In page</h1>
|
||||
<button onClick={async () => {
|
||||
// this will redirect to the OAuth provider's login page
|
||||
// This will redirect to the OAuth provider's login page.
|
||||
await app.signInWithOAuth('google');
|
||||
}}>
|
||||
Sign In with Google
|
||||
@ -69,9 +73,11 @@ export default function CustomCredentialSignIn() {
|
||||
setError('Please enter your password');
|
||||
return;
|
||||
}
|
||||
// this will redirect to app.urls.afterSignIn if successful, you can customize it in the StackServerApp constructor
|
||||
// This will redirect to app.urls.afterSignIn if successful.
|
||||
// You can customize the redirect URL in the StackServerApp constructor.
|
||||
const result = await app.signInWithCredential({ email, password });
|
||||
// It is better to handle each error code separately, but we will just show the error code directly for simplicity here
|
||||
// It's better to handle each error code separately, but for simplicity,
|
||||
// we'll just display the error message directly here.
|
||||
if (result.status === 'error') {
|
||||
setError(result.error.message);
|
||||
}
|
||||
@ -96,16 +102,23 @@ export default function CustomCredentialSignIn() {
|
||||
import { useStackApp } from "@stackframe/stack";
|
||||
import { useState } from "react";
|
||||
|
||||
export default function CustomCredentialSignIn() {
|
||||
export default function CustomMagicLinkSignIn() {
|
||||
const [email, setEmail] = useState('');
|
||||
const [error, setError] = useState('');
|
||||
const [message, setMessage] = useState('');
|
||||
const app = useStackApp();
|
||||
|
||||
const onSubmit = async () => {
|
||||
// this will redirect to app.urls.afterSignIn if successful, you can customize it in the StackServerApp constructor
|
||||
if (!email) {
|
||||
setError('Please enter your email address');
|
||||
return;
|
||||
}
|
||||
|
||||
// This will send a magic link email to the user's email address.
|
||||
// When they click the link, they will be redirected to your application.
|
||||
const result = await app.sendMagicLinkEmail(email);
|
||||
// It is better to handle each error code separately, but we will just show the error code directly for simplicity here
|
||||
// It's better to handle each error code separately, but for simplicity,
|
||||
// we'll just display the error message directly here.
|
||||
if (result.status === 'error') {
|
||||
setError(result.error.message);
|
||||
} else {
|
||||
@ -125,4 +138,4 @@ export default function CustomCredentialSignIn() {
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
@ -1,7 +1,11 @@
|
||||
---
|
||||
slug: customization/page-examples/signup
|
||||
slug: customization/page-examples/sign-up
|
||||
---
|
||||
|
||||
# Custom Sign-Up Page Examples
|
||||
|
||||
This page provides examples of how to create custom sign-up pages for your application using Stack Auth components and functions.
|
||||
|
||||
## Custom page with `SignUp` component
|
||||
|
||||
```tsx
|
||||
@ -16,19 +20,19 @@ export default function DefaultSignUp() {
|
||||
}
|
||||
```
|
||||
|
||||
You can also use `useUser` at the beginning of the sign in page to check if wether the user is already signed in and redirect them to some other page if they are.
|
||||
You can also use `useUser` at the beginning of the sign-up page to check whether the user is already signed in and redirect them to another page if they are.
|
||||
|
||||
## Other useful components
|
||||
|
||||
`CredentialSignUp`: A component that contains a form for signing in with email and password.
|
||||
`CredentialSignUp`: A component that renders a complete form for signing up with email and password. It handles validation, error states, and submission automatically.
|
||||
|
||||
`OAuthGroup`: A list of available OAuth provider sign-up buttons components. The available provider list is fetched from the server.
|
||||
`OAuthGroup`: A component that displays a list of available OAuth provider sign-up buttons. The available provider list is automatically fetched from the server based on your project configuration.
|
||||
|
||||
`OAuthButton`: A single OAuth sign-up button.
|
||||
`OAuthButton`: A component that renders a single OAuth sign-up button for a specific provider. Use this when you only want to offer specific OAuth providers.
|
||||
|
||||
## Custom OAuth Sign Up
|
||||
|
||||
OAuth sign-in and sign-up shares the same function. Check out the [Sign In example](/customization/page-examples/signin#custom-oauth-sign-in) for more information.
|
||||
OAuth sign-in and sign-up share the same function. Check out the [Sign In example](/customization/page-examples/sign-in#custom-oauth-sign-in) for more information.
|
||||
|
||||
## Custom Credential Sign Up
|
||||
|
||||
@ -49,9 +53,11 @@ export default function CustomCredentialSignUp() {
|
||||
setError('Please enter your password');
|
||||
return;
|
||||
}
|
||||
// this will redirect to app.urls.afterSignUp if successful, you can customize it in the StackServerApp constructor
|
||||
// This will redirect to app.urls.afterSignUp if successful.
|
||||
// You can customize the redirect URL in the StackServerApp constructor.
|
||||
const result = await app.signUpWithCredential({ email, password });
|
||||
// It is better to handle each error code separately, but we will just show the error code directly for simplicity here
|
||||
// It's better to handle each error code separately, but for simplicity,
|
||||
// we'll just display the error message directly here.
|
||||
if (result.status === 'error') {
|
||||
setError(result.error.message);
|
||||
}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: overview
|
||||
subtitle: Welcome to Stack Auth, the open-source authentication platform!
|
||||
subtitle: Welcome to Stack Auth, the developer-friendly open-source authentication platform that gets you started in minutes!
|
||||
---
|
||||
|
||||
You can get started in five minutes with our [setup guide](./getting-started/setup.mdx), or jump straight into the documentation.
|
||||
@ -44,7 +44,7 @@ Still have questions? Check out our [FAQ](/faq) or [join our Discord](https://di
|
||||
|
||||
Authentication is inherently difficult. Few things are more sensitive than user data and more complex than cryptography. Not surprisingly, many online businesses struggle to get it right.
|
||||
|
||||
The optimal authentication solution should be secure, yet approachable. If a developer has to worry about JWTs, OAuth flows, or password hashing, then we have failed. If an authentication solution uses closed-source, unauditable code for the most critical parts of your application, then we have failed.
|
||||
The optimal authentication solution should be secure, yet approachable. If developers need to worry about JWTs, OAuth flows, or password hashing, then the authentication solution has failed its purpose. If an authentication solution uses closed-source, unauditable code for the most critical parts of your application, then we have failed.
|
||||
|
||||
In truth, the authentication services industry has collectively failed. It's dominated by proprietary giants with predatory "bait-and-switch" pricing, providing no transparency into their codebase and delivering a subpar developer experience — because they know enterprises will pay more if setting up auth systems is painful.
|
||||
|
||||
@ -79,7 +79,7 @@ You also get pages and components for the authentication flow out-of-the-box. Th
|
||||
<img src="./imgs/sign-in.png" alt="SignIn" className="stack-350h" />
|
||||
</div>
|
||||
|
||||
Notice, there's no branding on our components. We believe we should grow by building the best product, not by forcing our brand onto your users. This means we **rely on you to spread the word about Stack**. If you like what you're reading, please take a moment to tell one or two of your friends about us.
|
||||
Notice, there's no branding on our components. We believe we should grow by building the best product, not by forcing our brand onto your users. This means **we depend on your help to spread the word about Stack**. If you like what you're reading, please take a moment to tell one or two of your friends about us.
|
||||
|
||||
If you prefer a fully customized UI, you can use our low-level functions like `signInWithOAuth` or `signInWithCredential` to build your own sign-in page:
|
||||
|
||||
@ -104,6 +104,6 @@ Best of all, Stack is **100% open-source**. This means the client, server, dashb
|
||||
|
||||
This is just a glimpse of what Stack can do. Stack also handles many other tasks like backend integration, data storage, emails, teams, permissions, and more, which you will learn about later in the documentation.
|
||||
|
||||
If this sounds interesting, [get started](./getting-started/setup.mdx) with our interactive setup wizard, or join [our Discord community](https://discord.stack-auth.com) to ask questions and get help from our team.
|
||||
If this sounds interesting, [get started](/getting-started/setup) with our interactive setup wizard, or join [our Discord community](https://discord.stack-auth.com) to ask questions and get help from our team.
|
||||
|
||||
We're excited to have you on board! 🚀
|
||||
|
||||
Loading…
Reference in New Issue
Block a user