Merge changes from source

CHANGELOG.md

@@ -1,6 +1,80 @@
 # Changelog
 
 
+## v0.2.0
+
+[compare changes](https://github.com/Atinux/nuxt-auth-utils/compare/v0.0.25...v0.2.0)
+
+### 🚀 Enhancements
+
+- ⚠️  Support hybrid rendering ([#104](https://github.com/Atinux/nuxt-auth-utils/pull/104))
+- Add steam as supported oauth provider ([c8b02d0](https://github.com/Atinux/nuxt-auth-utils/commit/c8b02d0))
+- Add paypal as supported oauth provider ([57ea01e](https://github.com/Atinux/nuxt-auth-utils/commit/57ea01e))
+- Add x(formerly twitter) as supported oauth provider ([a0be1f2](https://github.com/Atinux/nuxt-auth-utils/commit/a0be1f2))
+- Add xsuaa provider ([9afb9eb](https://github.com/Atinux/nuxt-auth-utils/commit/9afb9eb))
+
+### 💅 Refactors
+
+- Replace ofetch with $fetch ([a7df1b5](https://github.com/Atinux/nuxt-auth-utils/commit/a7df1b5))
+
+### 📖 Documentation
+
+- Fix typos ([149448a](https://github.com/Atinux/nuxt-auth-utils/commit/149448a))
+- Include SSR instructions in the README, fixes #97 ([#99](https://github.com/Atinux/nuxt-auth-utils/pull/99), [#97](https://github.com/Atinux/nuxt-auth-utils/issues/97))
+- Update readme ([7a4dcfb](https://github.com/Atinux/nuxt-auth-utils/commit/7a4dcfb))
+- Add X in readme ([b452d60](https://github.com/Atinux/nuxt-auth-utils/commit/b452d60))
+
+### 🏡 Chore
+
+- Add packageManager ([c323edc](https://github.com/Atinux/nuxt-auth-utils/commit/c323edc))
+- Add link to nuxt-authorization ([1b06908](https://github.com/Atinux/nuxt-auth-utils/commit/1b06908))
+- Update deps ([2fb5cff](https://github.com/Atinux/nuxt-auth-utils/commit/2fb5cff))
+- **release:** V0.1.0 ([6ea5685](https://github.com/Atinux/nuxt-auth-utils/commit/6ea5685))
+
+#### ⚠️ Breaking Changes
+
+- ⚠️  Support hybrid rendering ([#104](https://github.com/Atinux/nuxt-auth-utils/pull/104))
+
+### ❤️ Contributors
+
+- Jan Fröhlich ([@zanfee](http://github.com/zanfee))
+- Sébastien Chopin ([@Atinux](http://github.com/Atinux))
+- Stonegate 
+- Yizack Rangel ([@Yizack](http://github.com/Yizack))
+- Ahmed Rangel ([@ahmedrangel](http://github.com/ahmedrangel))
+- Yue JIN ([@kingyue737](http://github.com/kingyue737))
+- Paulo Queiroz ([@raggesilver](http://github.com/raggesilver))
+- Timi Omoyeni ([@Timibadass](http://github.com/Timibadass))
+
+## v0.1.0
+
+[compare changes](https://github.com/Atinux/nuxt-auth-utils/compare/v0.0.25...v0.1.0)
+
+### 🚀 Enhancements
+
+- ⚠️  Support hybrid rendering ([#104](https://github.com/Atinux/nuxt-auth-utils/pull/104))
+
+### 📖 Documentation
+
+- Fix typos ([149448a](https://github.com/Atinux/nuxt-auth-utils/commit/149448a))
+- Include SSR instructions in the README, fixes #97 ([#99](https://github.com/Atinux/nuxt-auth-utils/pull/99), [#97](https://github.com/Atinux/nuxt-auth-utils/issues/97))
+
+### 🏡 Chore
+
+- Add packageManager ([c323edc](https://github.com/Atinux/nuxt-auth-utils/commit/c323edc))
+- Add link to nuxt-authorization ([1b06908](https://github.com/Atinux/nuxt-auth-utils/commit/1b06908))
+- Update deps ([2fb5cff](https://github.com/Atinux/nuxt-auth-utils/commit/2fb5cff))
+
+#### ⚠️ Breaking Changes
+
+- ⚠️  Support hybrid rendering ([#104](https://github.com/Atinux/nuxt-auth-utils/pull/104))
+
+### ❤️ Contributors
+
+- Sébastien Chopin ([@Atinux](http://github.com/Atinux))
+- Paulo Queiroz ([@raggesilver](http://github.com/raggesilver))
+- Timi Omoyeni ([@Timibadass](http://github.com/Timibadass))
+
 ## v0.0.25
 
 [compare changes](https://github.com/Atinux/nuxt-auth-utils/compare/v0.0.24...v0.0.25)

README.md

@@ -5,7 +5,7 @@
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-Minimalist Authentication module for Nuxt exposing Vue composables and server utils.
+Add Authentication to Nuxt applications with secured & sealed cookies sessions.
 
 - [Release Notes](/CHANGELOG.md)
 - [Demo](https://github.com/atinux/nuxt-todos-edge)
@@ -14,12 +14,20 @@ Minimalist Authentication module for Nuxt exposing Vue composables and server ut
 
 ## Features
 
-- Secured & sealed cookies sessions
-- [OAuth Providers](#supported-oauth-providers)
+- [Hybrid Rendering](#hybrid-rendering) support (SSR / CSR / SWR / Prerendering)
+- [15+ OAuth Providers](#supported-oauth-providers)
+- [Vue composable](#vue-composable)
+- [Server utils](#server-utils)
+- [`<AuthState>` component](#authstate-component)
+- [Extendable with hooks](#extend-session)
 
 ## Requirements
 
-This module only works with SSR (server-side rendering) enabled as it uses server API routes. You cannot use this module with `nuxt generate`.
+This module only works with a Nuxt server running as it uses server API routes (`nuxt build`).
+
+This means that you cannot use this module with `nuxt generate`.
+
+You can anyway use [Hybrid Rendering](#hybrid-rendering) to pre-render pages of your application or disable server-side rendering completely.
 
 ## Quick Setup
 
@@ -40,7 +48,7 @@ Nuxt Auth Utils generates one for you when running Nuxt in development the first
 
 3. That's it! You can now add authentication to your Nuxt app ✨
 
-## Vue Composables
+## Vue Composable
 
 Nuxt Auth Utils automatically adds some plugins to fetch the current user session to let you access it from your Vue components.
 
@@ -152,8 +160,12 @@ It can also be set using environment variables:
 - Keycloak
 - LinkedIn
 - Microsoft
+- PayPal
 - Spotify
+- Steam
 - Twitch
+- X (Twitter)
+- XSUAA
 
 You can add your favorite provider by creating a new file in [src/runtime/server/lib/oauth/](./src/runtime/server/lib/oauth/).
 
@@ -206,6 +218,69 @@ export default defineNitroPlugin(() => {
 })
 ```
 
+## Server-Side Rendering
+
+You can make authenticated requests both from the client and the server. However, you must use `useRequestFetch()` to make authenticated requests during SSR if you are not using `useFetch()`
+
+```vue
+<script setup lang="ts">
+// When using useAsyncData
+const { data } = await useAsyncData('team', () => useRequestFetch()('/api/protected-endpoint'))
+
+// useFetch will automatically use useRequestFetch during SSR
+const { data } = await useFetch('/api/protected-endpoint')
+</script>
+```
+
+> There's [an open issue](https://github.com/nuxt/nuxt/issues/24813) to include credentials in `$fetch` in Nuxt.
+
+## Hybrid Rendering
+
+When using [Nuxt `routeRules`](https://nuxt.com/docs/guide/concepts/rendering#hybrid-rendering) to prerender or cache your pages, Nuxt Auth Utils will not fetch the user session during prerendering but instead fetch it on the client-side (after hydration).
+
+This is because the user session is stored in a secure cookie and cannot be accessed during prerendering.
+
+**This means that you should not rely on the user session during prerendering.**
+
+### `<AuthState>` component
+
+You can use the `<AuthState>` component to safely display auth-related data in your components without worrying about the rendering mode.
+
+One common use case if the Login button in the header:
+
+```vue
+<template>
+  <header>
+    <AuthState v-slot="{ loggedIn, clear }">
+      <button v-if="loggedIn" @click="clear">Logout</button>
+      <NuxtLink v-else to="/login">Login</NuxtLink>
+    </AuthState>
+  </header>
+</template>
+```
+
+If the page is cached or prerendered, nothing will be rendered until the user session is fetched on the client-side.
+
+You can use the `placeholder` slot to show a placeholder on server-side and while the user session is being fetched on client-side for the prerendered pages:
+
+```vue
+<template>
+  <header>
+    <AuthState>
+      <template #default="{ loggedIn, clear }">
+        <button v-if="loggedIn" @click="clear">Logout</button>
+        <NuxtLink v-else to="/login">Login</NuxtLink>
+      </template>
+      <template #placeholder>
+        <button disabled>Loading...</button>
+      </template>
+    </AuthState>
+  </header>
+</template>
+```
+
+If you are caching your routes with `routeRules`, please make sure to use [`nitro-nightly`](https://nitro.unjs.io/guide/nightly) or Nitro >= `2.10.0` to support the client-side fetching of the user session.
+
 ## Configuration
 
 We leverage `runtimeConfig.session` to give the defaults option to [h3 `useSession`](https://h3.unjs.io/examples/handle-session).
@@ -237,6 +312,10 @@ Our defaults are:
 
 Checkout the [`SessionConfig`](https://github.com/unjs/h3/blob/c04c458810e34eb15c1647e1369e7d7ef19f567d/src/utils/session.ts#L20) for all options.
 
+## More
+
+- [nuxt-authorization](https://github.com/barbapapazes/nuxt-authorization): Authorization module for managing permissions inside a Nuxt app, compatible with `nuxt-auth-utils`
+
 ## Development
 
 ```bash

package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-auth-utils",
-  "version": "0.0.25",
+  "version": "0.2.0",
   "description": "Minimalist Auth module for Nuxt with SSR",
   "repository": "Atinux/nuxt-auth-utils",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.11.2",
+    "@nuxt/kit": "^3.12.2",
     "defu": "^6.1.4",
     "hookable": "^5.5.3",
     "ofetch": "^1.3.4",
@@ -40,20 +40,20 @@
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {
-    "@iconify-json/simple-icons": "^1.1.99",
+    "@iconify-json/simple-icons": "^1.1.106",
     "@nuxt/devtools": "latest",
-    "@nuxt/eslint-config": "^0.3.8",
-    "@nuxt/module-builder": "^0.6.0",
-    "@nuxt/schema": "^3.11.2",
-    "@nuxt/test-utils": "^3.12.1",
-    "@nuxt/ui": "^2.15.2",
-    "@nuxt/ui-pro": "^1.1.0",
-    "@types/node": "^20.12.7",
+    "@nuxt/eslint-config": "^0.3.13",
+    "@nuxt/module-builder": "^0.7.1",
+    "@nuxt/schema": "^3.12.2",
+    "@nuxt/test-utils": "^3.13.1",
+    "@nuxt/ui": "^2.17.0",
+    "@nuxt/ui-pro": "^1.3.0",
+    "@types/node": "^20.14.4",
     "changelogen": "^0.5.5",
-    "eslint": "^9.0.0",
-    "nuxt": "^3.11.2",
+    "eslint": "^9.5.0",
+    "nuxt": "^3.12.2",
     "typescript": "^5.4.5",
-    "vitest": "^1.5.0",
-    "vue-tsc": "^2.0.13"
+    "vitest": "^1.6.0",
+    "vue-tsc": "^2.0.21"
   }
-}
+}

playground/.env.example

@@ -40,4 +40,16 @@ NUXT_OAUTH_COGNITO_CLIENT_SECRET=
 NUXT_OAUTH_COGNITO_REGION=
 # Facebook
 NUXT_OAUTH_FACEBOOK_CLIENT_ID=
-NUXT_OAUTH_FACEBOOK_CLIENT_SECRET=
+NUXT_OAUTH_FACEBOOK_CLIENT_SECRET=
+# PayPal
+NUXT_OAUTH_PAYPAL_CLIENT_ID=
+NUXT_OAUTH_PAYPAL_CLIENT_SECRET=
+# Steam
+NUXT_OAUTH_STEAM_API_KEY=
+# X
+NUXT_OAUTH_X_CLIENT_ID=
+NUXT_OAUTH_X_CLIENT_SECRET=
+# XSUAA
+NUXT_OAUTH_XSUAA_CLIENT_ID=
+NUXT_OAUTH_XSUAA_CLIENT_SECRET=
+NUXT_OAUTH_XSUAA_DOMAIN=