Documentation

Getting Started

Start with the installation flow, then move through auth, forms, API wiring, and SMTP delivery using the same polished UI shell as the rest of the site.

In this section

Follow the same recovery flow across installation, forms, auth, API wiring, and email delivery.

Structure

Keep the existing docs routes, but present them in a cleaner shell that matches the rest of the product UI.

Install commands

Add Albatroz to your app with the package manager your team already uses.

Keep installation simple, then move directly into route protection and password recovery pages.

npm i albatroz

Install the package

Albatroz is designed to drop into an existing React or Next.js codebase with a predictable forgot-password flow. Install it in the same app where you handle authentication, user records, and outbound email.

Add the package with your preferred package manager.

Connect the hooks to your own API routes instead of hard-coding transport logic in the component.

Keep validation close to the form so users get immediate feedback before the request is sent.

Baseline recovery screen

A minimal screen only needs an email input, lightweight validation, and the Albatroz forgot-password hook. This keeps the surface area small while still giving you a production-ready entry point.

Example

import React, { useState } from 'react';
import { useForgotPassword } from 'albatroz';

export default function ForgotPasswordScreen() {
  const { loading, submitHandler } = useForgotPassword();
  const [email, setEmail] = useState('');
  const [errors, setErrors] = useState<{ email?: string }>({});

  const validateEmail = (value: string) => {
    const pattern = /^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$/i;

    if (!value) return 'Please enter a valid email';
    if (!pattern.test(value)) return 'Please use a valid email format';

    return null;
  };

  const handleSubmit = (event: React.FormEvent) => {
    event.preventDefault();
    const emailError = validateEmail(email);

    if (emailError) {
      setErrors({ email: emailError });
      return;
    }

    setErrors({});
    submitHandler({ email });
  };

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">Email</label>
      <input
        id="email"
        type="email"
        value={email}
        onChange={(event) => setEmail(event.target.value)}
      />
      {errors.email && <p>{errors.email}</p>}
      <button disabled={loading}>
        {loading ? 'Processing' : 'Send recovery email'}
      </button>
    </form>
  );
}

Use this page as the handoff between your product UI and the backend reset flow. The hook handles submission, while your API is responsible for token creation and delivery.

Recommended implementation flow

The easiest way to keep the docs aligned with the codebase is to implement the recovery journey in the same order that users experience it.

Gate protected pages with session-aware auth logic.

Build the forgot-password and reset-password forms.

Create the API routes that issue and validate reset tokens.

Configure SMTP so transactional email gets delivered consistently.

Start at the top of the documentation flow.

Auth