You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Adjusted docs to match new origin env system
* Began writing upgrade guide for 0.10.0
* added external backend section back to docs
* Finished 0.10.0 upgrade guide
* Added 0.10.0 release bannner
* Added version tag to hero
* fix: lint
* Apply suggestions from code review
* docs: write a dedicated guide for path logic
* docs: minor adjustment
---------
Co-authored-by: Marsel Shaikhin <[email protected]>
Co-authored-by: Marsel Shaikhin <[email protected]>
This page is here to clarify how the pathing logic works in `@sidebase/nuxt-auth`.
4
+
You can find a full overview of how URLs are handled [in the issue comment](https://github.com/sidebase/nuxt-auth/pull/913#issuecomment-2359137989) and in spec files for [`authjs` provider](https://github.com/sidebase/nuxt-auth/blob/main/tests/authjs.url.spec.ts) and [`local` provider](https://github.com/sidebase/nuxt-auth/blob/main/tests/local.url.spec.ts).
5
+
6
+
## `baseURL` is a prefix
7
+
8
+
It will be prepended to a path before making a call. For example,
9
+
10
+
```ts
11
+
exportdefaultdefineNuxtConfig({
12
+
auth: {
13
+
baseURL: 'https://example.com/api/auth',
14
+
15
+
provider: {
16
+
type: 'local',
17
+
endpoints: {
18
+
// The call would be made to `https://example.com/api/auth/login`
19
+
signIn: { path: '/login', method: 'post' },
20
+
}
21
+
}
22
+
}
23
+
})
24
+
```
25
+
26
+
## Use URL provided in `endpoints` if it is fully specified
27
+
28
+
If you provide a full URL to `endpoints`, it will be used when making calls to an endpoint:
29
+
30
+
```ts {9}
31
+
exportdefaultdefineNuxtConfig({
32
+
auth: {
33
+
baseURL: 'https://your.website/api',
34
+
35
+
provider: {
36
+
type: 'local',
37
+
endpoints: {
38
+
// This will call `https://example.com/user`
39
+
getSession: { path: 'https://example.com/user' },
40
+
41
+
// This will call `https://your.website/api/login`
42
+
signIn: { path: '/login', method: 'post' },
43
+
},
44
+
}
45
+
}
46
+
})
47
+
```
48
+
49
+
## `runtimeConfig`
50
+
51
+
Value of `baseURL` is always located at `runtimeConfig.public.auth.baseURL`. You cannot change it directly as of the moment of writing, but you can read the value in your application:
52
+
53
+
```ts
54
+
const runtimeConfig =useRuntimeConfig()
55
+
const baseURL =runtimeConfig.public.auth.baseURL
56
+
```
57
+
58
+
This value is generally the [source of truth](https://github.com/sidebase/nuxt-auth/blob/b5af548c1fc390ae00496e19ad7a91d308af9b12/src/runtime/utils/url.ts#L37-L38). It is being [set in the plugin](https://github.com/sidebase/nuxt-auth/blob/b5af548c1fc390ae00496e19ad7a91d308af9b12/src/runtime/plugin.ts#L20-L24) to also be available on the client.
59
+
60
+
## Changing `baseURL`
61
+
62
+
Read next to understand how it can be changed.
63
+
64
+
### 1. Environment variables
65
+
66
+
You have multiple ways of changing the `baseURL` via env variables:
67
+
- use `NUXT_PUBLIC_AUTH_BASE_URL`;
68
+
- use `AUTH_ORIGIN` if `originEnvKey` is not set;
69
+
- use the environment variable name set in [`originEnvKey`](/guide/application-side/configuration#originenvkey)
70
+
71
+
Environment variables should work in both build-time and runtime.
72
+
73
+
### 2. `baseURL`
74
+
75
+
If you didn't set an environment variable, NuxtAuth will look for [`auth.baseURL`](/guide/application-side/configuration#baseurl) inside the `nuxt.config.ts`.
76
+
77
+
Note that this variable is always **static**, will only be set during runtime and can still be overriden in runtime using env variables.
78
+
79
+
Not setting `baseURL` will default to `/api/auth`.
80
+
81
+
### 3. `authjs` only: determine origin automatically from the incoming `HTTP` request
82
+
83
+
When the server is running in **development mode**, NuxtAuth can automatically infer `baseURL` from the incoming request.
84
+
85
+
---
86
+
87
+
We recommend the following setup to configure your `AUTH_ORIGIN` or `baseURL`:
You can read additional information on `origin` determining [here](/resources/error-reference#auth-no-origin).
54
+
You can read additional information on `origin`and `baseURL`determining [here](/resources/error-reference#auth-no-origin).
55
55
56
56
## `disableServerSideAuth`
57
57
@@ -63,33 +63,13 @@ Forces your server to send a "loading" authentication status on all requests, th
63
63
## `baseURL`
64
64
65
65
-**Type**: `string | undefined`
66
-
-**Default**:
67
-
- AuthJS Provider:
68
-
-_Development_: `http://localhost:3000/api/auth`
69
-
-_Production_: `undefined`
70
-
- Local / Refresh Provider: `/api/auth`
71
66
72
-
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:
67
+
The full URL at which the app will run combined with the path to authentication. You should only use `baseURL` if you want to set it statically for your application.
73
68
74
-
-`authjs`: You must set the full URL, with origin and path in production. You can leave this empty in development
75
-
-`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.
69
+
You can read additional information on `origin` and `baseURL` determining [here](/resources/error-reference#auth-no-origin).
76
70
77
-
### `authjs` Provider
78
-
79
-
`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:
-**port**: _empty_ (implies `:80` for http and `:443` for https), :3000, :8888
83
-
-**path**: the path that directs to the location of your `NuxtAuthHandler` e.g. `/api/auth`
84
-
85
-
### `local` Provider
86
-
87
-
Defaults to `/api/auth` for both development and production. Setting this is optional, if you set it you can set it to either:
88
-
- just a path: Will lead to `nuxt-auth` using `baseURL` as a relative path appended to the origin you deploy to. Example: `/backend/auth`
89
-
- 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`
90
-
91
-
:::warning
92
-
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.
71
+
::: tip
72
+
If you would like to overwrite the `baseURL` at the runtime you can use the [`originEnvKey`](#originenvkey).
Copy file name to clipboardExpand all lines: docs/guide/local/quick-start.md
+23-38Lines changed: 23 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,10 +2,6 @@
2
2
3
3
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`.
4
4
5
-
:::warning Breaking change
6
-
In `v0.9.0` the `refresh` provider was integrated into the `local` provider. Read the [upgrade guide](/upgrade/version-0.9.0).
7
-
:::
8
-
9
5
## Configuration
10
6
11
7
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.
14
10
exportdefaultdefineNuxtConfig({
15
11
modules: ['@sidebase/nuxt-auth'],
16
12
auth: {
17
-
baseURL: '/api/auth',
18
13
provider: {
19
14
type: 'local'
20
15
}
21
16
}
22
17
})
23
18
```
24
19
25
-
:::tip
26
-
Ensure that your `baseURL` is properly configured to match your backend API. Read more [here](/guide/application-side/configuration#local-and-refresh).
27
-
:::
28
-
29
20
## API endpoints
30
21
31
22
Afterwards, you can define the endpoints to which the authentication requests will be made:
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.
52
46
53
-
In the example above requests would be made to the following URLs:
47
+
In the example above, we define a [runtime config](https://nuxt.com/docs/guide/going-further/runtime-config) value with the `baseURL` using the `originEnvKey`, which results in requests being made to the following URLs:
54
48
55
49
-**Sign in:**`/api/auth/login` (POST)
56
50
-**Sign out**`/api/auth/logout` (POST)
57
51
-**Sign up:**`/api/auth/register` (POST)
58
52
-**Get Session:**`/api/auth/session` (GET)
59
53
60
-
:::info
61
-
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).
62
-
:::
63
-
64
54
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.
65
55
66
-
```ts{7}
56
+
```ts{6}
67
57
export default defineNuxtConfig({
68
58
auth: {
69
-
baseURL: '/api/auth',
70
59
provider: {
71
60
type: 'local',
72
61
endpoints: {
@@ -83,33 +72,29 @@ You cannot disable the `getSession` endpoint, as NuxtAuth internally uses it to
83
72
84
73
### Using an external backend
85
74
86
-
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.
75
+
You can also set your endpoints to query an external backend:
87
76
88
-
To ensure that the module can properly identify that your endpoints point to an external URL, please ensure the following:
89
-
90
-
1.`auth.baseURL`**includes** a trailing `/` at the end
91
-
2.`auth.endpoints`**do not** include a leading `/` at the start
You can read more about the path resolving logic in `@sidebase/nuxt-auth`[here](https://github.com/sidebase/nuxt-auth/issues/782#issuecomment-2223861422).
112
-
113
98
## Token
114
99
115
100
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`.
0 commit comments