Added docs

This commit is contained in:
Zai Shi 2024-02-28 16:53:11 +01:00
parent d3a0349600
commit 160a459649
26 changed files with 9540 additions and 0 deletions

2
docs/.gitignore vendored Normal file
View File

@ -0,0 +1,2 @@
.docusaurus
/build

41
docs/README.md Normal file
View File

@ -0,0 +1,41 @@
# Website
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
### Installation
```
$ yarn
```
### Local Development
```
$ yarn start
```
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
### Build
```
$ yarn build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
### Deployment
Using SSH:
```
$ USE_SSH=true yarn deploy
```
Not using SSH:
```
$ GIT_USER=<Your GitHub username> yarn deploy
```
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

3
docs/babel.config.js Normal file
View File

@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

83
docs/docs/01-setup.md Normal file
View File

@ -0,0 +1,83 @@
---
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_WEBLIT_PROJECT_ID=<your-project-id>
NEXT_PUBLIC_WEBLIT_PUBLISHABLE_CLIENT_KEY=<your-publishable-client-key>
WEBLIT_SECRET_SERVER_KEY=<your-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 <StackHandler app={stackServerApp} {...props} />;
}
```
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 (
<html lang="en">
<body>
<StackProvider app={stack}>
{children}
</StackProvider>
</body>
</html>
);
}
```
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.

View File

@ -0,0 +1,110 @@
---
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.
<Tabs>
<TabItem value="client" label="Client Component" default>
```tsx
'use client';
import { useUser, redirectToSignIn, redirectToSignUp, signOut } from '@stack/next';
export default function Home() {
const user = useUser();
return (
<div>
<h1>Home</h1>
{user ? (
<div>
<p>Welcome, {user.displayName}</p>
<button onClick={signOut}>Sign Out</button>
</div>
) : (
<div>
<p>You are not logged in</p>
<button onClick={redirectToSignIn}>Sign in</button>
<button onClick={redirectToSignUp}>Sign up</button>
</div>
)}
</div>
);
}
```
</TabItem>
<TabItem value="server" label="Server Component">
```tsx
import { stack } from '../lib/stack';
export default function Page() {
const user = await stack.getUser();
return (
<div>
<h1>Home</h1>
{user ? (
<div>
<p>Welcome, {user.displayName}</p>
<a href={stack.signOutUrl}>Sign Out</a>
</div>
) : (
<div>
<p>You are not logged in</p>
<a href={stack.signInUrl}>Sign in</a>
<a href={stack.signUpUrl}>Sign up</a>
</div>
)}
</div>
);
}
```
</TabItem>
</Tabs>
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:
<Tabs>
<TabItem value="client" label="Client Component" default>
```tsx
'use client';
import { useUser, redirectToSignIn } from '@stack/next';
export default function Protected() {
useUser({ or: 'redirect' });
return <h1>You can only see this if you are logged in</h1>
}
```
</TabItem>
<TabItem value="server" label="Server Component">
```tsx
import { stack } from '../lib/stack';
export default function Protected() {
await stack.getUser({ or: 'redirect' });
return <h1>You can only see this if you are logged in</h1>
}
```
</TabItem>
</Tabs>
## 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.

View File

@ -0,0 +1,41 @@
---
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 <div>
<h1>My Custom Sign In page</h1>
<button onClick={async () => await app.signInWithOauth('google')}>Sign In with Google</button>
</div>;
}
```
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.

View File

@ -0,0 +1,5 @@
---
sidebar_position: 4
---
# Server Usage

View File

@ -0,0 +1,5 @@
---
sidebar_position: 1
---
# User

View File

@ -0,0 +1,5 @@
---
sidebar_position: 1
---
# Auth

View File

@ -0,0 +1,7 @@
{
"label": "Next.js API",
"position": 5,
"link": {
"type": "generated-index"
}
}

View File

@ -0,0 +1,5 @@
---
sidebar_position: 1
---
# User

View File

@ -0,0 +1,5 @@
---
sidebar_position: 1
---
# Auth

View File

@ -0,0 +1,7 @@
{
"label": "Server API",
"position": 6,
"link": {
"type": "generated-index"
}
}

View File

@ -0,0 +1,43 @@
---
sidebar_position: 1
---
# Sign In
## Default Sign In Component
```tsx
'use client';
import { useStackApp, SignIn } from "stack";
export default function DefaultSignIn() {
const app = useStackApp();
return <SignIn fullPage redirectUrl={app.urls.userHome}/>;
}
```
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.
## Custom OAuth Sign In
```tsx
'use client';
import { useStackApp } from "stack";
export default function CustomOAuthSignIn() {
const app = useStackApp();
return <div>
<button onClick={async () => await app.signInWithOauth({
provider: 'google',
redirectUrl: app.urls.userHome
})}>Sign In with Google</button>
</div>;
}
```
## Custom Credential Sign In
```tsx

View File

@ -0,0 +1,5 @@
---
sidebar_position: 1
---
# Sign Up

View File

@ -0,0 +1,7 @@
{
"label": "Pages",
"position": 7,
"link": {
"type": "generated-index"
}
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 138 KiB

94
docs/docusaurus.config.js Normal file
View File

@ -0,0 +1,94 @@
// @ts-check
// `@type` JSDoc annotations allow editor autocompletion and type checking
// (when paired with `@ts-check`).
// There are various equivalent ways to declare your Docusaurus config.
// See: https://docusaurus.io/docs/api/docusaurus-config
import { themes as prismThemes } from "prism-react-renderer";
/** @type {import('@docusaurus/types').Config} */
const config = {
title: "My Site",
tagline: "Dinosaurs are cool",
favicon: "img/favicon.ico",
// Set the production url of your site here
url: "https://your-docusaurus-site.example.com",
// Set the /<baseUrl>/ pathname under which your site is served
// For GitHub pages deployment, it is often '/<projectName>/'
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.
projectName: "docusaurus", // Usually your repo name.
onBrokenLinks: "throw",
onBrokenMarkdownLinks: "warn",
// Even if you don't use internationalization, you can use this field to set
// useful metadata like html lang. For example, if your site is Chinese, you
// may want to replace "en" with "zh-Hans".
i18n: {
defaultLocale: "en",
locales: ["en"],
},
presets: [
[
"classic",
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: "./sidebars.js",
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
},
theme: {
customCss: "./src/css/custom.css",
},
}),
],
],
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
prism: {
additionalLanguages: ["bash"],
},
colorMode: {
defaultMode: "dark",
disableSwitch: true,
respectPrefersColorScheme: false,
},
// Replace with your project's social card
image: "img/docusaurus-social-card.jpg",
navbar: {
// title: "My Site",
logo: {
alt: "Stack",
src: "img/logo.svg",
},
items: [
{
type: "docSidebar",
sidebarId: "tutorialSidebar",
position: "left",
label: "Documentation",
},
{
href: "https://github.com/facebook/docusaurus",
label: "GitHub",
position: "right",
},
],
},
prism: {
theme: prismThemes.github,
darkTheme: prismThemes.dracula,
},
}),
};
export default config;

45
docs/package.json Normal file
View File

@ -0,0 +1,45 @@
{
"name": "stack-docs",
"version": "0.0.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"dev": "pnpm start",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "3.1.1",
"@docusaurus/preset-classic": "3.1.1",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"prism-react-renderer": "^2.3.0",
"react": "^18.0.0",
"react-dom": "^18.0.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.1.1",
"@docusaurus/types": "3.1.1"
},
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 3 chrome version",
"last 3 firefox version",
"last 5 safari version"
]
},
"engines": {
"node": ">=18.0"
}
}

8944
docs/pnpm-lock.yaml Normal file

File diff suppressed because it is too large Load Diff

33
docs/sidebars.js Normal file
View File

@ -0,0 +1,33 @@
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation
The sidebars can be generated from the filesystem, or explicitly defined here.
Create as many sidebars as you want.
*/
// @ts-check
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
// By default, Docusaurus generates a sidebar from the docs folder structure
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
// But you can create a sidebar manually
/*
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],
*/
};
export default sidebars;

32
docs/src/css/custom.css Normal file
View File

@ -0,0 +1,32 @@
html[data-theme='dark'] {
--ifm-background-color: #030712;
--ifm-background-surface-color: #030712;
}
.navbar {
border-bottom: 1px solid #151515;
}
.menu {
border-right: 1px solid #151515;
}
.table-of-contents {
border-left: 1px solid #151515;
}
.navbar__logo img {
height: 80%;
margin-top: 4px;
}
.prism-code {
background-color: rgb(15,23,42,50) !important;
}
/* .navbar {
border-bottom: 1px solid #151515;
padding: 0px;
height: 0px;
visibility: hidden;
} */

14
docs/src/pages/index.js Normal file
View File

@ -0,0 +1,14 @@
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import Layout from "@theme/Layout";
export default function Home() {
const { siteConfig } = useDocusaurusContext();
return (
<Layout
title={`Hello from ${siteConfig.title}`}
description="Description will go into a meta tag in <head />"
>
<main>Stack Documentation</main>
</Layout>
);
}

0
docs/static/.nojekyll vendored Normal file
View File

BIN
docs/static/img/favicon.ico vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

4
docs/static/img/logo.svg vendored Normal file
View File

@ -0,0 +1,4 @@
<svg width="851" height="242" viewBox="0 0 851 242" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M282.965 156.631V151.631C282.965 148.131 284.715 146.381 288.215 146.381H309.465C312.965 146.381 314.715 148.131 314.715 151.631V153.631C314.715 159.965 315.965 164.298 318.465 166.631C320.965 168.965 325.548 170.131 332.215 170.131H343.965C350.465 170.131 354.965 168.881 357.465 166.381C360.132 163.881 361.465 159.215 361.465 152.381V149.381C361.465 144.548 359.465 140.881 355.465 138.381C351.632 135.715 346.798 134.131 340.965 133.631C335.132 133.131 328.798 132.215 321.965 130.881C315.298 129.381 309.048 127.548 303.215 125.381C297.382 123.048 292.465 118.631 288.465 112.131C284.632 105.465 282.715 96.9647 282.715 86.6313V77.8813C282.715 64.8813 286.382 54.798 293.715 47.6313C301.048 40.4647 311.215 36.8813 324.215 36.8813H349.215C362.382 36.8813 372.632 40.4647 379.965 47.6313C387.298 54.798 390.965 64.8813 390.965 77.8813V82.6313C390.965 86.1313 389.215 87.8813 385.715 87.8813H364.465C360.965 87.8813 359.215 86.1313 359.215 82.6313V81.1313C359.215 74.6313 357.965 70.2147 355.465 67.8813C352.965 65.548 348.382 64.3813 341.715 64.3813H331.965C325.132 64.3813 320.465 65.7147 317.965 68.3813C315.632 70.8813 314.465 75.8813 314.465 83.3813V88.1313C314.465 95.9647 321.298 100.465 334.965 101.631C349.132 102.798 361.715 105.631 372.715 110.131C378.548 112.631 383.382 117.131 387.215 123.631C391.215 129.965 393.215 138.131 393.215 148.131V156.631C393.215 169.631 389.548 179.715 382.215 186.881C374.882 194.048 364.715 197.631 351.715 197.631H324.465C311.465 197.631 301.298 194.048 293.965 186.881C286.632 179.715 282.965 169.631 282.965 156.631ZM421.98 97.6313H411.98C409.98 97.6313 408.564 97.298 407.73 96.6313C407.064 95.9647 406.73 94.6313 406.73 92.6313V75.3813C406.73 71.8813 408.48 70.1313 411.98 70.1313H421.98C423.814 70.1313 424.73 69.2147 424.73 67.3813V43.6313C424.73 40.1313 426.564 38.3813 430.23 38.3813H451.23C454.73 38.3813 456.48 40.1313 456.48 43.6313V67.3813C456.48 69.2147 457.48 70.1313 459.48 70.1313H478.98C482.48 70.1313 484.23 71.8813 484.23 75.3813V92.6313C484.23 94.4647 483.814 95.798 482.98 96.6313C482.314 97.298 480.98 97.6313 478.98 97.6313H459.48C457.48 97.6313 456.48 98.548 456.48 100.381V155.631C456.48 160.798 457.647 164.548 459.98 166.881C462.314 169.048 466.147 170.131 471.48 170.131H481.48C484.98 170.131 486.73 171.881 486.73 175.381V192.631C486.73 194.465 486.314 195.798 485.48 196.631C484.814 197.298 483.48 197.631 481.48 197.631H466.23C453.064 197.631 442.814 194.131 435.48 187.131C428.314 180.131 424.73 170.131 424.73 157.131V100.381C424.73 98.548 423.814 97.6313 421.98 97.6313ZM552.115 197.631H546.115C532.949 197.631 522.782 194.131 515.615 187.131C508.449 180.131 504.865 170.048 504.865 156.881V110.881C504.865 97.7147 508.449 87.6313 515.615 80.6313C522.782 73.6313 532.949 70.1313 546.115 70.1313H603.865C607.532 70.1313 609.365 71.8813 609.365 75.3813V192.381C609.365 195.881 607.532 197.631 603.865 197.631H582.865C579.365 197.631 577.615 195.881 577.615 192.381V184.131H576.615C574.782 188.631 571.532 192.048 566.865 194.381C562.199 196.548 557.282 197.631 552.115 197.631ZM577.615 151.131V100.381C577.615 98.548 576.615 97.6313 574.615 97.6313H551.115C545.782 97.6313 542.032 98.798 539.865 101.131C537.699 103.298 536.615 107.048 536.615 112.381V155.381C536.615 160.715 537.699 164.548 539.865 166.881C542.032 169.048 545.782 170.131 551.115 170.131H560.365C571.865 170.131 577.615 163.798 577.615 151.131ZM718.01 175.381V192.631C718.01 194.465 717.593 195.798 716.76 196.631C716.093 197.298 714.76 197.631 712.76 197.631H675.51C662.343 197.631 652.176 194.131 645.01 187.131C637.843 180.131 634.26 170.048 634.26 156.881V110.881C634.26 97.7147 637.843 87.6313 645.01 80.6313C652.176 73.6313 662.343 70.1313 675.51 70.1313H712.76C716.26 70.1313 718.01 71.8813 718.01 75.3813V92.6313C718.01 94.4647 717.593 95.798 716.76 96.6313C716.093 97.298 714.76 97.6313 712.76 97.6313H680.51C675.343 97.6313 671.593 98.798 669.26 101.131C667.093 103.298 666.01 107.048 666.01 112.381V155.381C666.01 160.715 667.093 164.548 669.26 166.881C671.593 169.048 675.343 170.131 680.51 170.131H712.76C716.26 170.131 718.01 171.881 718.01 175.381ZM812.543 70.1313H836.793C838.793 70.1313 840.126 70.7147 840.793 71.8813C841.46 73.048 841.21 74.548 840.043 76.3813L806.793 131.131V132.131L841.543 191.381C842.543 193.048 842.626 194.548 841.793 195.881C840.96 197.048 839.46 197.631 837.293 197.631H815.793C812.96 197.631 810.876 197.298 809.543 196.631C808.376 195.965 807.126 194.548 805.793 192.381L774.043 136.631C772.543 133.965 772.543 131.215 774.043 128.381L804.043 75.1313C805.876 71.798 808.71 70.1313 812.543 70.1313ZM766.043 197.631H744.793C741.293 197.631 739.543 195.881 739.543 192.381V27.1313C739.543 23.6313 741.293 21.8813 744.793 21.8813H766.043C769.543 21.8813 771.293 23.6313 771.293 27.1313V192.381C771.293 195.881 769.543 197.631 766.043 197.631Z" fill="#D9D9D9"/>
<path d="M103.504 1.81227C101.251 0.68679 98.6002 0.687576 96.3483 1.81439L4.4201 47.8136C1.71103 49.1692 0 51.9387 0 54.968V130.55C0 133.581 1.7123 136.351 4.42292 137.706L96.4204 183.695C98.6725 184.82 101.323 184.82 103.575 183.694L168.422 151.271C173.742 148.611 180 152.479 180 158.426V168.879C180 171.91 178.288 174.68 175.578 176.035L103.577 212.036C101.325 213.162 98.6745 213.162 96.4224 212.036L11.5771 169.623C6.25791 166.964 0 170.832 0 176.779V187.073C0 190.107 1.71689 192.881 4.43309 194.234L96.5051 240.096C98.7529 241.216 101.396 241.215 103.643 240.094L195.571 194.235C198.285 192.881 200 190.109 200 187.076V119.512C200 113.565 193.741 109.697 188.422 112.356L131.578 140.778C126.258 143.438 120 139.57 120 133.623V123.17C120 120.14 121.712 117.37 124.422 116.014L195.578 80.4368C198.288 79.0817 200 76.3116 200 73.2814V54.9713C200 51.9402 198.287 49.1695 195.576 47.8148L103.504 1.81227Z" fill="#D9D9D9"/>
</svg>

After

Width:  |  Height:  |  Size: 5.8 KiB