diff --git a/pages/docs/quickstarts/nextjs.mdx b/pages/docs/quickstarts/nextjs.mdx index abc0a87..43f8b36 100644 --- a/pages/docs/quickstarts/nextjs.mdx +++ b/pages/docs/quickstarts/nextjs.mdx @@ -33,22 +33,34 @@ npm i @hellocoop/nextjs ### Run Quickstart -```sh -npx @hellocoop/quickstart@latest --nextjs - ``` + + + ```sh + npx @hellocoop/quickstart@latest --nextjs_app_router + ``` + + + ```sh + npx @hellocoop/quickstart@latest --nextjs_pages_router + ``` + + + Quickstart will prompt you to: -- download the `@hellocoop/quickstart` package -- log in to Quickstart with Hellō -- create an application, or select an existing one +1. Download the `@hellocoop/quickstart` package +2. Log in to Quickstart with Hellō +3. Create an application, or select an existing one Quickstart will then: -- create a `hello.config.js` file containing your app's `client_id` -- mount the Hellō endpoint by creating the `./pages/api/hellocoop.js` file -- generate a random `HELLO_COOKIE_SECRET` and add it to `.env.local` +1. Create a `hello.config.js` file containing your app's `client_id` +2. Mount the Hellō endpoint by creating one of the following files, depending on your router setup: +- `./app/api/hellocoop/route.js` (App Router) +- `./pages/api/hellocoop.js` (Pages Router) +3. Generate a random `HELLO_COOKIE_SECRET` and add it to `.env.local` > If you created a new application, no more configuration is needed for local development. You can add a light and dark themed logo, and URLs for terms of service and your privacy policy when you are ready at the [Hellō Developer Console](https://console.hello.coop) -Your server should now be fully configured to work with Hellõ locally. +Your server should now be fully configured to work with Hellō locally. ### Test Your Server @@ -92,7 +104,110 @@ You have configured your server to use Hellō! ### Add Hellō Test Page -Copy the following code and save it to `hello-test.jsx` in your `pages` folder: + + + Copy the following code and save it to `page.jsx` in your `app/hello-test` folder: + +```jsx filename="./app/hello-test/page.jsx" +import Head from 'next/head' +import Link from 'next/link' +import { + LoggedOut, + LoggedIn, + ContinueButton, + useAuth, + getLogOutRoute +} from '@hellocoop/nextjs/react' + +export default async function HelloTest() { + const status = auth(); + const { auth: {name, picture, email} } = status; + + return ( + <> + + Hellō Test Page + + +
+
+ + + + +
+ {name} +

{name}

+

{email}

+
+
+ + log out + +
+ +
+
+ 
+            {JSON.stringify(status, null, 4)}
+
+
+ + + + ) +} +``` + + + Copy the following code and save it to `hello-test.jsx` in your `pages` folder: ```jsx filename="./pages/hello-test.jsx" import Head from 'next/head' @@ -191,6 +306,8 @@ export default function HelloTest() { ) } ``` + + ### Test Your Client diff --git a/pages/docs/sdks/express.mdx b/pages/docs/sdks/express.mdx index fbce099..971e9c3 100644 --- a/pages/docs/sdks/express.mdx +++ b/pages/docs/sdks/express.mdx @@ -21,7 +21,7 @@ npm i @hellocoop/express > Hellō Quickstart will perform steps 2 - 4 for you > ```sh -> npx @hellocoop/quickstart@latest --nextjs +> npx @hellocoop/quickstart@latest --express > ``` ### 2. `HELLO_COOKIE_SECRET` diff --git a/pages/docs/sdks/fastify.mdx b/pages/docs/sdks/fastify.mdx index 9485559..ae2095a 100644 --- a/pages/docs/sdks/fastify.mdx +++ b/pages/docs/sdks/fastify.mdx @@ -21,7 +21,7 @@ npm i @hellocoop/fastify > Hellō Quickstart will perform steps 2 - 4 for you > ```sh -> npx @hellocoop/quickstart@latest --nextjs +> npx @hellocoop/quickstart@latest --fastify > ``` ### 2. `HELLO_COOKIE_SECRET` diff --git a/pages/docs/sdks/nextjs.mdx b/pages/docs/sdks/nextjs.mdx index 99e897d..b17eb39 100644 --- a/pages/docs/sdks/nextjs.mdx +++ b/pages/docs/sdks/nextjs.mdx @@ -22,10 +22,19 @@ Following are the steps required to setup this package: npm i @hellocoop/nextjs ``` -> Hellō Quickstart will perform steps 2 - 5 for you -> ```sh -> npx @hellocoop/quickstart@latest --nextjs -> ``` +Hellō Quickstart will perform steps 2 - 5 for you + + + ```sh + npx @hellocoop/quickstart@latest --nextjs_app_router + ``` + + + ```sh + npx @hellocoop/quickstart@latest --nextjs_pages_router + ``` + + ### 2. `HELLO_COOKIE_SECRET` @@ -63,31 +72,83 @@ See [hello.config.js](./config) for additional configuration. The default route is `/api/hellocoop`, which should not conflict with any existing route. There is one endpoint for all functionality. Query parameters (`login`,`logout`,`auth`) are used for routing within the package. With configuration at the project root in `hello.config.js`, the API route is handled by: -```javascript filename="./pages/api/hellocoop.js" -import config from '../../hello.config' -import { pageAuth } from '@hellocoop/nextjs' -export default pageAuth(config) -``` + + + ```javascript filename="./app/api/hellocoop/route.js" + import config from '../../../hello.config' + import { appAuth } from '@hellocoop/nextjs' + export const { GET } = appAuth(config) + ``` + + + ```javascript filename="./pages/api/hellocoop.js" + import config from '../../hello.config' + import { pageAuth } from '@hellocoop/nextjs' + export default pageAuth(config) + ``` + + ### 6. Image Component Config To use the [`Image Component`](https://nextjs.org/docs/pages/api-reference/components/image) to display profile pictures add the Hellō and Gravatar `domains` to the `images` section of your `next.config.js` file: -```js {4-6} filename="next.config.js" +```js {4-15} filename="next.config.js" const nextConfig = { images: { - domains: [ - 'cdn.hello.coop', - 'pictures.hello.coop', - 'www.gravatar.com' - ] + remotePatterns: [ + { + protocol: 'https', + hostname: 'cdn.hello.coop' + }, + { + protocol: 'https', + hostname: 'pictures.hello.coop' + }, + { + protocol: 'https', + hostname: 'gravatar.com' + } + ] } } ``` ### 7. Hellō Button Stylesheet -To provide the styling for Hellō buttons, add the below code to the `` section of your `_document.tsx` or `_document.jsx` file in the `pages` directory: + + + To provide the styling for Hellō buttons, add the below code to the `` section of your `_document.tsx` or `_document.jsx` file in the `pages` directory: + + +```jsx {5} filename="app/layout.js or app/layout.ts" +export default function RootLayout({ children }) { + return ( + + + + + + ); +} +``` + +Here is a summary of setup: + +``` +project-directory/ +├─ .env.local 2. HELLO_COOKIE_SECRET +├─ hello.config.js 3. client_id +├─ next.config.js 6. Image Component Config +└─ app/ + ├─ layout.js 7. Hellō Button Stylesheet + └─ api/ + └─ hellocoop + └─ route.js 5. API Route +``` + + + To provide the styling for Hellō buttons, add the below code to the `` section of your `_document.tsx` or `_document.jsx` file in the `pages` directory: ```jsx {7} filename="pages/_document.tsx or pages/_document.jsx" @@ -120,31 +181,21 @@ project-directory/ └─ api/ └─ hellocoop.js 5. API Route ``` + + ## Buttons The following buttons are available: - - - ```typescript - import { - ContinueButton, - LoginButton, - UpdateProfileButton - } from '@hellocoop/nextjs/react' - ``` - - - ```javascript - const { - ContinueButton, - LoginButton, - UpdateProfileButton - } = require('@hellocoop/nextjs/react') - ``` - - +```javascript +import { + ContinueButton, + LoginButton, + UpdateProfileButton +} from '@hellocoop/nextjs/react' +``` + > Note they are in `@hellocoop/nextjs/react` See the [SDK Reference | React](./react/) for details. @@ -153,26 +204,14 @@ See the [SDK Reference | React](./react/) for details. The following React components are available: - - - ```typescript - import { - HelloProvider, - LoggedIn, - LoggedOut, - } from '@hellocoop/nextjs/react' - ``` - - - ```javascript - const { - HelloProvider, - LoggedIn, - LoggedOut, - } = require('@hellocoop/nextjs/react') - ``` - - + +```javascript +import { + HelloProvider, + LoggedIn, + LoggedOut, +} from '@hellocoop/nextjs/react' +``` > Note they are in `@hellocoop/nextjs/react` See the [SDK Reference | React](./) for details. @@ -181,8 +220,8 @@ See the [SDK Reference | React](./) for details. ### `useAuth()` -```typescript -import { useAuth } from '@hellocoop/nextjs' +```javascript +import { useAuth } from '@hellocoop/nextjs/react' const { isLoading, // useSWR response, true if still loading call to @@ -211,11 +250,27 @@ import { logOut, logOutRoute } from '@hellocoop/nextjs' `logOutRoute` - provides route to logout ## Server APIs + + + ### `auth()` -> We are still working on Server APIs for Server Components that work with the App Router - -### `getAuth( req )` ( Page Router ) +```typescript +import { auth } from '@hellocoop/nextjs' +// returns same shape as useAuth().auth +const { + isLoggedIn, // always returned + iat, // returned if isLoggedIn == true + sub, // use as user identifier - returned if isLoggedIn == true + // additional properties set in auth cookie - following are defaults + name, + email, + picture +} = await auth() +``` + + +### `getAuth( req )` ```typescript import { getAuth } from '@hellocoop/nextjs' @@ -257,8 +312,6 @@ export default function MyPage = ({auth}) { // This a convenience wrapper around `getAuth()` export { getServerSideProps } from '@hellocoop/nextjs' ``` - - ### `loginSync()` `loginSync( LoginSyncParams ): LoginSyncResponse` @@ -295,3 +348,6 @@ export default async loggedInCallback ({ auth: { email, name, picture, role } } } +``` + + diff --git a/pages/docs/sdks/quickstart.mdx b/pages/docs/sdks/quickstart.mdx index 719e3e8..d5eea6e 100644 --- a/pages/docs/sdks/quickstart.mdx +++ b/pages/docs/sdks/quickstart.mdx @@ -29,7 +29,8 @@ This will open up a browser window, where you will need to login with Hellō, an - --suffix (-x) - suffix to add to generated app name - --integration (-i) - integration name shown in console - --wildcard (-w) - boolean to set the wildcard domain Development Redirect URI -- --nextjs - boolean to configure a Next.js app +- --nextjs_app_router - boolean to configure a Next.js app for App router +- --nextjs_pages_router - boolean to configure a Next.js app for Pages router - --express - boolean to configure an Express app - --fastify - boolean to configure a Fastify app