Authentication/guides/Sessions & Login

Sessions & Local Preview

Follow user state from local preview to an exported WordPress theme.

On This Page

Sessions and local preview

A session is the state that lets a site recognize a person after signing in. Use useWpUser() to display the current user and useWpAuth() to submit actions or show their progress.

Read the state

Table · 2 columns


Hook result	Meaning
`useWpUser()`	Current user profile, or `null`
`useWpAuth().initializing`	Whether initial session setup is in progress
`useWpAuth().loading`	Whether an account action is in progress
`useWpAuth().error`	Current action error text, or `null`
`useWpAuth().loginField`	Effective login identifier policy
`useWpAuth().emailVerificationEnabled`	Whether verification is enabled in the current Auth state

initializing and loading are separate. A person may already be signed in while a new action runs. Use initializing for initial account UI and loading to disable controls during an operation.

Reading state during an action

Table · 3 columns


Situation	User state	Interface response
Signed out and idle	null	Offer login
Login request is running	Current state remains available	Disable repeated submissions using loading
Login is rejected	No new session is established	Render error and allow another attempt
Cookie logout succeeds	Local user is cleared	Reload to obtain the server's signed-out page
Cookie logout fails	Current user is retained	Render error and offer retry

A spinner is not a session check

initializing describes initial setup; loading describes an action. Read useWpUser() to choose the signed-in or signed-out content.

Registration notices and errors

useWpAuth().notice contains account-created feedback, including verification delivery instructions. error describes an action failure. Render both in a custom registration interface so a mail problem does not look like failed account creation.

Local preview

In Vite development, Auth can read mock users and roles from the development runtime. Its simulated login matches a mock username or email and accepts a password of at least three characters; it does not check a WordPress password hash. Verification settings can also affect whether a mock user can sign in.

The preview session is stored under forgewp_auth_session in browser local storage. Signing out clears that preview session. This storage belongs to the preview; it is not evidence of a server-authorized WordPress login.

Installing the package alone does not populate mock users. Use an Auth-enabled scaffold or inspect the theme's mock-user and role configuration before testing a preview login. Preview account and mail-log workflows will be covered separately from real delivery.

Exported WordPress theme

The generated theme exposes a forgewp-session JSON script containing the current user and policy values, with window.forgeWpHydration as a supported fallback. The provider reads this session data when it initializes.

Cookie-mode login and logout call the generated /wp-json/forgewp/v1/auth/ endpoints. The provider's production login normally navigates or reloads after success, and production logout reloads when running in the theme. This lets WordPress render the next page using the updated server session.

Cookie handling, nonce requirements, origin policy, page caching, and session expiry belong to the deployed server workflow. A nonce is a request token used for a particular action; it is not a replacement for authenticating a user or checking their permissions. This guide does not promise automatic nonce refresh or uninterrupted sessions.

Provider and standalone hooks

Use a shared provider for your account interface. useWpAuth() and useWpUser() also contain standalone behavior for hydrated components outside a provider, backed by shared module state and server session data. Standalone behavior is not a second independent WordPress account system.

Ready-made forms such as WpLoginForm require a provider. Use the provider for the form workflows in these guides so the forms, user display, and actions share one state source.

Optional JWT deployments

JWT mode uses a token under forgewp_jwt_token and a separately supplied JWT backend. The provider calls that backend's token-validation endpoint during restoration. Reading a JWT payload supplies display information; the backend must validate the token and authorize protected requests.

Start with WordPress cookie mode unless your frontend is deliberately hosted separately. Verify token issuance, validation, expiration, logout, and cross-origin requests against your chosen backend before using that deployment.