Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking β€œSign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: adjust docs for the 0.10.0 release #963

Merged
merged 11 commits into from
Dec 19, 2024
6 changes: 5 additions & 1 deletion docs/.vitepress/routes/navbar.ts
Original file line number Diff line number Diff line change
@@ -44,8 +44,12 @@ export const routes: DefaultTheme.Config['nav'] = [
],
},
{
text: '0.9.4',
text: '0.10.0',
items: [
{
text: '0.9.4',
link: 'https://github.com/sidebase/nuxt-auth/tree/0.9.4/docs',
},
{
text: '0.8.2',
link: 'https://github.com/sidebase/nuxt-auth/tree/0.8.2/docs',
4 changes: 4 additions & 0 deletions docs/.vitepress/routes/sidebar/upgrade.ts
Original file line number Diff line number Diff line change
@@ -5,6 +5,10 @@ export const routes: DefaultTheme.SidebarItem[] = [
text: 'Versions',
base: '/upgrade',
items: [
{
text: 'Version 0.10.0',
link: '/version-0.10.0'
},
{
text: 'Version 0.9.0',
link: '/version-0.9.0'
13 changes: 10 additions & 3 deletions docs/.vitepress/theme/components/Layout.vue
Original file line number Diff line number Diff line change
@@ -2,16 +2,17 @@
import DefaultTheme from 'vitepress/theme'
import GithubStarsButton from './GithubStarsButton.vue'
import Banner from './Banner.vue'
import Tag from './Tag.vue'
const { Layout } = DefaultTheme
// Banner Configuration
const isBannerEnabled = false
const isBannerEnabled = true
const bannerConfig = {
// Leave text empty to disable the banner
text: 'πŸš€ NuxtAuth v0.9.0 has been released!',
text: 'πŸš€ NuxtAuth v0.10.0 has been released!',
button: {
href: '/upgrade/version-0.9.0',
href: '/upgrade/version-0.10.0',
text: 'View upgrade guide',
},
}
@@ -26,5 +27,11 @@ const bannerConfig = {
<template v-if="isBannerEnabled" #home-hero-before>
<Banner v-bind="bannerConfig" />
</template>

<template #home-hero-info-before>
<a href="/upgrade/version-0.10.0">
<Tag text="Version 0.10.0" />
</a>
</template>
</Layout>
</template>
30 changes: 5 additions & 25 deletions docs/guide/application-side/configuration.md
Original file line number Diff line number Diff line change
@@ -51,7 +51,7 @@ export default defineNuxtConfig({
```
:::

You can read additional information on `origin` determining [here](/resources/error-reference#auth-no-origin).
You can read additional information on `origin` and `baseURL` determining [here](/resources/error-reference#auth-no-origin).

## `disableServerSideAuth`

@@ -63,33 +63,13 @@ Forces your server to send a "loading" authentication status on all requests, th
## `baseURL`

- **Type**: `string | undefined`
- **Default**:
- AuthJS Provider:
- _Development_: `http://localhost:3000/api/auth`
- _Production_: `undefined`
- Local / Refresh Provider: `/api/auth`

The full url at which the app will run combined with the path to authentication. You can set this differently depending on your selected authentication-provider:
The full url at which the app will run combined with the path to authentication. You should only use `baseURL` if you want to staticlly set a baseURL for your application.
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved

- `authjs`: You must set the full URL, with origin and path in production. You can leave this empty in development
- `local`: You can set a full URL, but can also leave this empty to fallback to the default value of `/api/auth` or set only the path.
You can read additional information on `origin` and `baseURL` determining [here](/resources/error-reference#auth-no-origin).

### `authjs` Provider

`baseURL` can be `undefined` during development but _must_ be set to the combination of origin + path that points to your `NuxtAuthHandler` for production. The origin consists out of:
- **scheme**: http / https
- **host**: e.g., localhost, example.org, google.com
- **port**: _empty_ (implies `:80` for http and `:443` for https), :3000, :8888
- **path**: the path that directs to the location of your `NuxtAuthHandler` e.g. `/api/auth`

### `local` Provider

Defaults to `/api/auth` for both development and production. Setting this is optional, if you set it you can set it to either:
- just a path: Will lead to `nuxt-auth` using `baseURL` as a relative path appended to the origin you deploy to. Example: `/backend/auth`
- an origin and a path: Will lead to `nuxt-auth` using `baseURL` as an absolute request path to perform requests to. Example: `https://example.com/auth`

:::warning
If you point to a different origin than the one you deploy to you likely have to take care of CORS: Allowing cross origin requests.
::: tip
If you would like to overwrite the `baseURL` at the runtime you can use the [`originEnvKey`](#originenvkey).
:::

## `provider`
59 changes: 22 additions & 37 deletions docs/guide/local/quick-start.md
Original file line number Diff line number Diff line change
@@ -2,10 +2,6 @@

This guide is for setting up `@sidebase/nuxt-auth` with the Local Provider, which is best suited for when you already have a backend that accepts username + password as a login or want to build a static application. The Local Provider also supports refresh tokens since `v0.9.0`.

:::warning Breaking change
In `v0.9.0` the `refresh` provider was integrated into the `local` provider. Read the [upgrade guide](/upgrade/version-0.9.0).
:::

## Configuration

The entire configuration for the `local` provider is contained inside the `nuxt.config.ts`. Inside the `auth` options, set your provider to `local`.
@@ -14,27 +10,25 @@ The entire configuration for the `local` provider is contained inside the `nuxt.
export default defineNuxtConfig({
modules: ['@sidebase/nuxt-auth'],
auth: {
baseURL: '/api/auth',
provider: {
type: 'local'
}
}
})
```

:::tip
Ensure that your `baseURL` is properly configured to match your backend API. Read more [here](/guide/application-side/configuration#local-and-refresh).
:::

## API endpoints

Afterwards, you can define the endpoints to which the authentication requests will be made:

```ts
export default defineNuxtConfig({
// ...Previous configuration
runtimeConfig: {
baseURL: '/api/auth'
},
auth: {
baseURL: '/api/auth',
originEnvKey: 'NUXT_BASE_URL',
provider: {
type: 'local',
endpoints: {
@@ -50,23 +44,18 @@ export default defineNuxtConfig({

Each endpoint, consists of an object, with a `path` and `method`. When a user triggers an action inside your application a request will be made to each endpoint. When a request is made to the `getSession` endpoint, a token will be sent as a header. You can configure the headers and token below.

In the example above requests would be made to the following URLs:
In the example above, we define a runtimeConfig value with the `baseURl` using the originEnvKey, which results in requests being made to the following urls:
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved

- **Sign in:** `/api/auth/login` (POST)
- **Sign out** `/api/auth/logout` (POST)
- **Sign up:** `/api/auth/register` (POST)
- **Get Session:** `/api/auth/session` (GET)

:::info
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved
Relative paths starting with a `/` (e.g. `/login`) will be treated as a part of your Nuxt application. If you want to use an external backend, please provide fully-specified URLs instead. Read more [here](#using-an-external-backend).
:::

You can customize each endpoint to fit your needs or disable it by setting it to `false`. For example you may want to disable the `signUp` endpoint.

```ts{7}
export default defineNuxtConfig({
auth: {
baseURL: '/api/auth',
provider: {
type: 'local',
endpoints: {
@@ -83,33 +72,29 @@ You cannot disable the `getSession` endpoint, as NuxtAuth internally uses it to

### Using an external backend

When using the `local` provider to access an external backend, please consider that the module will attempt to resolve the API endpoints by using internal Nuxt 3 relative URLs or an external call.
You can also set your endpoints to query an external backend:

To ensure that the module can properly identify that your endpoints point to an external URL, please ensure the following:

1. `auth.baseURL` **includes** a trailing `/` at the end
2. `auth.endpoints` **do not** include a leading `/` at the start

```ts{7}
```ts
export default defineNuxtConfig({
auth: {
baseURL: 'https://external-api.com', // [!code --]
baseURL: 'https://external-api.com/', // [!code ++]
provider: {
type: 'local',
endpoints: {
signIn: { path: '/login', method: 'post' }, // [!code --]
signIn: { path: 'login', method: 'post' }, // [!code ++]
getSession: { path: '/session', method: 'get' }, // [!code --]
getSession: { path: 'session', method: 'get' }, // [!code ++]
}
}
// ...Previous configuration
runtimeConfig: {
baseURL: 'https://example-api.com'
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved
},
auth: {
originEnvKey: 'NUXT_BASE_URL',
provider: {
type: 'local',
endpoints: {
signIn: { path: '/auth/login', method: 'post' },
signOut: { path: '/auth/logout', method: 'post' },
signUp: { path: '/auth/register', method: 'post' },
getSession: { path: '/user/session', method: 'get' },
}
}
}
})
```

You can read more about the path resolving logic in `@sidebase/nuxt-auth` [here](https://github.com/sidebase/nuxt-auth/issues/782#issuecomment-2223861422).

## Token

The `local` and `refresh` providers are both based on exchanging access tokens with your backend. NuxtAuth expects an access token to be provided by the `signIn` endpoint, which will then be saved into the session to authenticate further requests to e.g. `getSession`.
2 changes: 1 addition & 1 deletion docs/upgrade/index.md
Original file line number Diff line number Diff line change
@@ -3,4 +3,4 @@ title: 'Redirecting'
editLink: false
---

<meta http-equiv="refresh" content="0;URL='/upgrade/version-0.9.0'" />
<meta http-equiv="refresh" content="0;URL='/upgrade/version-0.10.0'" />
123 changes: 123 additions & 0 deletions docs/upgrade/version-0.10.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
# Upgrade to 0.10.0

> This release contains breaking changes for the default middleware and the configuration of `baseURL` and `AUTH_ORIGIN`

## Installation

::: code-group

```bash [npm]
npm i -D @sidebase/nuxt-auth@^0.10.0
```

```bash [pnpm]
pnpm i -D @sidebase/nuxt-auth^0.10.0
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved
```

```bash [yarn]
yarn add --dev @sidebase/nuxt-auth^0.10.0
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved
```

:::

## Breaking Changes

### Renaming of default middleware

In 0.10.0 we renamed the included middleware from `auth` to `sidebase-auth`. This is a quality of life change to allow developers to create their own custom middleware named `auth.global.ts` without conflicting with the provided middleware.

If you use the auth middleware inline on any of your pages you will need to rename it:

```vue diff
<script lang="ts" setup>
definePageMeta({
middleware: 'auth', // [!code --]
middleware: 'sidebase-auth', // [!code ++]
})
</script>

<template>
Only I am protected!
</template>
```

### Adjustments to the computation of `baseURL` and `AUTH_ORIGIN`

In 0.10.0 we spent a considerable amount of time reworking how `@sidebase/nuxt-auth` determine which endpoints to make requests to. If you would like to view the full PR and discussion, you can find it [here](https://github.com/sidebase/nuxt-auth/pull/913).

As a quick overview, `@sidebase/nuxt-auth` will now use the following logic to determine where to make requests to:

#### 1. Environment variable and `runtimeConfig`

Use the `AUTH_ORIGIN` environment variable or `runtimeConfig.authOrigin` if set. Name can be customized, refer to [`originEnvKey`](/guide/application-side/configuration#originenvkey).

#### 2. `baseURL`

Use the static [`baseURL`](/guide/application-side/configuration#baseurl) inside the `nuxt.config.ts` if set.

#### 3. Automatically from the incoming `HTTP` request

When the server is running in **development mode**, NuxtAuth can automatically infer it from the incoming request.

---

Therefore as of version 0.10.0, we recommend the following setup to set your `AUTH_ORIGIN` or `baseURL`:

::: code-group

```ts diff [nuxt.config.ts]
export default defineNuxtConfig({
// ...Previous configuration
runtimeConfig: { // [!code ++]
baseURL: '/api/auth' // [!code ++]
}, // [!code ++]
auth: {
baseUrl: 'https://my-backend.com/api/auth', // [!code --]
originEnvKey: 'NUXT_BASE_URL', // [!code ++]
}
})
```

```env diff [.env]
NUXT_BASE_URL="https://my-backend.com/api/auth" // [!code ++]
```

:::

### Adjustments when using an external backend for the `local`-provider

In previous versions of `@sidebase/nuxt-auth` a very specific setup was needed to ensure that external backends could properly be used for the `local`-provider. In 0.10.0 we reworked the internal handling or urls to make it more consistent across providers and configurations.
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved

If you were previously using an external backend you can now make the following adjustments:
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved

```ts diff
export default defineNuxtConfig({
auth: {
provider: {
type: 'local',
endpoints: {
signIn: { path: 'login', method: 'post' }, // [!code --]
signIn: { path: '/login', method: 'post' }, // [!code ++]
getSession: { path: 'session', method: 'get' }, // [!code --]
getSession: { path: '/session', method: 'get' }, // [!code ++]
}
}
}
})
```

You can find a full overview of how `@sidebase/nuxt-auth`handles urls [here](https://github.com/sidebase/nuxt-auth/pull/913#issuecomment-2359137989).
phoenix-ru marked this conversation as resolved.
Show resolved Hide resolved

## Changelog

* docs(fix): use correct process env variable for baseUrl by @felixranesberger in https://github.com/sidebase/nuxt-auth/pull/940
* enh(#895): Custom refresh response token pointer by @Rizzato95 in https://github.com/sidebase/nuxt-auth/pull/910
* feat(#797, #878): set `baseURL` via environment variables and improve internal url detection by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/913
* chore(#892): rename middleware to avoid conflicts by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/957
* enh(#935): allow external login page by @Thomas-Philippot in https://github.com/sidebase/nuxt-auth/pull/936
* release: 0.10.0-rc.1 by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/958
* chore: upgrade to nitro 2.10, preparing for nitropack ecosystem switch from `nitropack` to `nitro` by @BracketJohn in https://github.com/sidebase/nuxt-auth/pull/942
* fix(#927): fix the warnings produced by Nuxt when awaiting runtime config by @phoenix-ru in https://github.com/sidebase/nuxt-auth/pull/959
* release: 0.10.0-rc.2 by @zoey-kaiser in https://github.com/sidebase/nuxt-auth/pull/960

**Full Changelog**: https://github.com/sidebase/nuxt-auth/compare/0.9.4...0.10.0