Skip to main content

​
Welcome to Home Manager

This guide will walk you through creating your account, setting up your first household, and adding your initial tasks. You’ll be up and running in less than 5 minutes.
Home Manager uses Clerk for authentication, providing secure sign-up with email/password or social login options (Google, GitHub, etc.).

​
Prerequisites

All you need is:
  • A web browser (Chrome, Firefox, Safari, or Edge)
  • An email address
  • 5 minutes of your time

​
Step 1: Create Your Account

1

Navigate to Home Manager

Visit your Home Manager instance (e.g., https://your-home-manager.app or http://localhost:3000 for local development)
2

Sign Up

Click Sign up and choose your preferred method:
  • Email/Password: Enter your email and create a secure password
  • Social Login: Use Google, GitHub, or other OAuth providers
The Clerk authentication system handles all security and verification.
3

Verify Your Email

Check your inbox for a verification email and click the confirmation link. This ensures account security.
4

Complete Your Profile

Add your name and any additional profile information. This helps other household members identify you.
After signing up, you’ll be automatically redirected to the dashboard at /dashboard.

​
Step 2: Your First Household

Home Manager automatically creates your first household when you sign in. Here’s what happens behind the scenes: 
// From src/app/api/household/init/route.ts
const household = await getOrCreateHousehold(userId, email);
The system:
  1. Creates a household with your user as the Owner
  2. Sets up your household ID for all future data
  3. Initializes empty collections for chores, bills, shopping, and maintenance

​
Understanding Household Roles

Owner

Full control: manage members, edit all data, and delete the household

Member

Can view and edit household data but cannot invite or remove members

Guest

Read-only access to view household information

​
Step 3: Explore the Dashboard

Your dashboard provides an at-a-glance view of your household: 
// Real-time counts from multiple endpoints
const endpoints = {
  bills: "/api/bills/count",
  chores: "/api/chores/count",
  shopping: "/api/shopping/count",
  maintenance: "/api/maintenance/count"
};
The dashboard shows:
  • Summary Cards: Quick counts of pending bills, active chores, shopping items, and maintenance tasks
  • Monthly Bills Chart: Visual analytics of bill payments over time
  • Personalized Greeting: Dynamic welcome message based on time of day

​
Step 4: Add Your First Chore

Let’s create your first household task:
1

Navigate to Chores

Click on Chores in the navigation menu (located at /chores)
2

Create a New Chore

Click the Add Chore button and fill in the details:
{
  "name": "Vacuum living room",
  "assignee": "John Doe",
  "description": "Vacuum the main living area including under furniture",
  "recurrence": "weekly"
}
3

Assign to a Member

Select who’s responsible for this chore from the household members dropdown
4

Set Recurrence (Optional)

Choose a recurrence pattern:
  • None: One-time task
  • Daily: Repeats every day
  • Weekly: Repeats every week
  • Monthly: Repeats every month
The chore is created via the API: 
// POST /api/chores
const newChore = await prisma.choresItem.create({
  data: {
    householdId: household.id,
    name: "Vacuum living room",
    assignee: "John Doe",
    description: "Vacuum the main living area",
    position: nextPosition
  }
});

​
Step 5: Track a Bill

Never miss a payment again:
1

Go to Bills

Navigate to Bills from the main menu
2

Add Your First Bill

Click Add Bill and enter:
  • Name: e.g., “Electric Bill”
  • Amount: e.g., $125.00
  • Due Date: Select the payment due date
  • Category: Choose from Utilities, Rent, Internet, Insurance, etc.
3

View Bill Analytics

Return to the dashboard to see your monthly bill trends visualized in the chart
// POST /api/bills
await fetch('/api/bills', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Electric Bill',
    amount: 125.00,
    dueDate: '2026-03-15',
    category: 'Utilities'
  })
});

​
Step 6: Create a Shopping List

Collaborate on grocery shopping:
1

Open Shopping

Click Shopping in the navigation
2

Add Items

Add items to your list:
  • Milk (Dairy)
  • Bread (Bakery)
  • Apples (Produce)
  • Chicken (Meat)
3

Organize by Drag-and-Drop

Reorder items by dragging them. The order is saved automatically:
// POST /api/shopping with orderedIds
await fetch('/api/shopping', {
  method: 'POST',
  body: JSON.stringify({
    orderedIds: ["id1", "id2", "id3"]
  })
});
4

Check Off Items

As you shop, check off items. They’ll be marked complete for all household members in real-time.

​
Step 7: Invite Household Members

Collaborate with family or roommates:
1

Navigate to Household

Go to Household from the main menu
2

Enter Email Address

In the “Invite by Email” field, enter the email address of the person you want to invite
3

Send Invitation

Click Invite. The system will:
  1. Create a pending household member record
  2. Send an email invitation (via Clerk)
  3. Show the invite as “Pending” in your members list
4

Member Accepts

When they sign up/sign in, they’ll see an invitation banner:
// They can accept or decline
await fetch('/api/household/accept', {
  method: 'POST',
  body: JSON.stringify({ inviteId })
});
5

Assign Roles

Once accepted, you can assign them a role (Owner, Member, or Guest)
Only household Owners can invite new members. Members and Guests cannot send invitations.

​
Step 8: Track Maintenance

Log home maintenance activities:
1

Go to Maintenance

Navigate to the Maintenance section
2

Add a Maintenance Task

Example:
  • Title: “Replace HVAC filter”
  • Category: “HVAC”
  • Description: “Replace with 16x20x1 MERV 11 filter”
  • Recurrence: “Monthly”
3

Track Completion

Mark tasks as complete to maintain a history log for future reference

​
Understanding the Database Schema

Here’s how your data is organized: 
// From prisma/schema.prisma
model Household {
  id        String             @id @default(cuid())
  name      String
  members   HouseholdMember[]
  createdAt DateTime           @default(now())
}

model HouseholdMember {
  id           String     @id @default(cuid())
  householdId  String
  userId       String?
  invitedEmail String?
  role         String
  status       String?    @default("pending")
  Household    Household  @relation(fields: [householdId], references: [id])
}

model ChoresItem {
  id           String   @id @default(uuid())
  householdId  String
  name         String
  assignee     String
  description  String
  recurrence   String   @default("none")
  checked      Boolean  @default(false)
  position     Int      @default(0)
  createdAt    DateTime @default(now())
}

​
Next Steps

Explore API Routes

Learn about the available API endpoints

Self-Host Guide

Deploy your own instance of Home Manager

Customize Settings

Configure preferences like theme, language, and notifications

View Audit Logs

Track all household activities with detailed audit logs

​
Common Questions

Currently, each user can be a member of one household at a time. You can leave a household and join another, or create a new one.
Deleted items are removed from the database. Consider marking items as complete instead of deleting them to maintain history.
Currently, household names are set during creation. Contact support or modify directly in the database if self-hosting.
No, guests have read-only access. They can view all household data but cannot make changes. Upgrade them to Member role to grant edit permissions.

​
Need Help?

If you encounter any issues:
  1. Check the browser console for error messages
  2. Verify your authentication status (sign out and sign back in)
  3. Review the GitHub repository for known issues
  4. Open an issue on GitHub with detailed reproduction steps
Home Manager is under active development. Features and APIs may evolve. Check the GitHub repository for the latest updates.

Build docs developers (and LLMs) love

Get started for freeTalk to us