ForgeWP

Installation & First Login

Install Auth and connect a login interface to its provider and hooks.

Installation and your first login interface

Begin with a working ForgeWP React theme. Run commands from the folder containing its wp.config.ts and package.json.

Terminal
pnpm add @forgewp/auth

The Auth package uses React and @forgewp/react from your theme. Installing it as a theme dependency allows the compiler to detect Auth when generating WordPress output. An explicit auth configuration also enables Auth generation.

Where to install

Add Auth to the theme package that you export. Installing it only in an unrelated workspace package does not declare Auth as that theme's dependency.

Wrap related components in one provider

A provider shares state with the components inside it. Put the login form, user display, and logout button under the same WpAuthProvider so they use the same state.

src/components/MemberAccess.tsx
1import {
2  WpAuthProvider,
3  WpLoginForm,
4  useWpAuth,
5  useWpUser,
6} from "@forgewp/auth"
7
8function MemberAccessContent() {
9  const user = useWpUser()
10  const { initializing, loading, error, logout } = useWpAuth()
11
12  if (initializing) return <p role="status">Loading your account…</p>
13
14  if (!user) {
15    return <WpLoginForm />
16  }
17
18  return (
19    <section>
20      <p>Welcome, {user.displayName}.</p>
21      <button type="button" disabled={loading} onClick={() => void logout()}>
22        Sign out
23      </button>
24      {error && <p role="alert">{error}</p>}
25    </section>
26  )
27}
28
29export default function MemberAccess() {
30  return (
31    <WpAuthProvider>
32      <MemberAccessContent />
33    </WpAuthProvider>
34  )
35}

Import MemberAccess into a page or layout. Keep the provider above the components that read its state. useWpAuth() does not return a user or isAuthenticated property; use useWpUser() and check whether its result is null.

The compiler detects Auth hooks and components when building interactive islands. Use the normal ForgeWP page/layout and hydration workflow; verify the exported interface as well as its local preview.

What you should see

Table · 2 columns
Starting state
Expected interface
Session setup is in progress
The loading-account message
No current user
The login form
Current user is available
Their display name and a sign-out button
An action reports an error
An alert when the example renders that error
Put the provider above the hook

The component calling a hook must be inside the provider. That is why the example uses a separate MemberAccessContent component rather than calling the hooks in the component that creates the provider.

Choose which login identifier to accept

WpAuthProvider accepts a loginField prop: usernameOnly, emailOnly, or usernameAndEmail (the default). A password is still required. In WordPress, generated session data and settings can supply the effective login policy; the provider prop does not override the server's rules.

Developers can set initial server defaults under auth in wp.config.ts. For example, the loginField setting uses those same three values. Auth configuration is separate from native contact-form configuration.

Manage the installed theme

After exporting and activating the theme, an administrator with manage_options can open Settings → ForgeWP Auth. The generated settings include login identifier policy, registration, verification, auto-login, the default role, and verification/password-reset email text.

Inspect the installed settings when testing an existing site: saved WordPress options take priority over source defaults. Confirm account creation and real email delivery in WordPress; the local preview exercises mock behavior.

Next: Sessions & Local Preview.