First Customization

Let’s make your first change to KiviCare and watch Hot Module Replacement (HMR) in action.

What You’ll Learn

• Edit a React component
• See live changes using HMR
• Build the project for production
• Understand the development workflow

Prerequisites

Make sure:

• Dev server is running → npm run dev
• KiviCare dashboard is open in the browser
• Your code editor is ready

Step 1: Find a Component to Edit

We’ll modify the Dashboard homepage.

File:
app/dashboard/views/dashboard/Dashboard.jsx

1. Open your code editor
2. Go to app/dashboard/views/dashboard/
3. Open Dashboard.jsx

Step 2: Make a Simple Change

Locate the main heading and update it.

Before

<h1>Dashboard</h1>

After

<h1>Dashboard - Custom Extended Version</h1>
<p>Welcome to my customized KiviCare installation!</p>

Step 3: See HMR in Action

1. Save the file
2. Switch to your browser
3. Watch the update appear instantly

What happened behind the scenes?

• Vite detected the file change
• It pushed the update through WebSocket
• React hot-reloaded the component
• No full page reload
• No state loss

This is the power of Hot Module Replacement.

Step 4: Add Custom Styling

Now let’s style the section.

File:
app/dashboard/assets/scss/custom.scss

Add:

.custom-welcome {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  padding: 2rem;
  border-radius: 12px;
  margin-bottom: 2rem;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1);

  h1 {
    color: white;
    margin-bottom: 0.5rem;
  }

  p {
    color: rgba(255, 255, 255, 0.9);
    font-size: 1.1rem;
  }
}

Step 5: Apply the Styling

Update your JSX:

<div>
  <h1>Dashboard - Custom Extended Version</h1>
  <p>Welcome to my customized KiviCare installation!</p>
</div>

Save and view the styled result instantly.

Step 6: Add Interactivity

Let’s add a button with a toast message.

import React, { useState } from 'react';
import { Button } from 'react-bootstrap';
import { toast } from 'react-toastify';

const handleWelcome = () => {
  toast.success('Welcome to KiviCare Extended Version!');
};

return (
  <div>
    <h1>Dashboard - Custom Extended Version</h1>
    <p>Welcome to my customized KiviCare installation!</p>
    <Button>
      Click to Welcome yourself!
    </Button>
  </div>
);

Save and click the button to test.

Step 7: Build for Production

1. Stop the dev server → Ctrl + C
2. Run:

npm run build

This generates optimized files inside dist/.

Step 8: Test the Production Build

With the dev server stopped:

1. Refresh your WordPress site
2. Your changes should still appear
3. Open DevTools → Network
4. Confirm assets load from dist/ (not localhost:8080)

Understanding the Workflow

Development Mode

npm run dev

• Dev server runs
• HMR enabled
• Fast rebuilds
• Debug-friendly

Production Mode

npm run build

• Code minified
• Optimized assets
• Files stored in dist/
• Ready for deployment

Best Practices

• Use __() for translatable strings
• Prefer react-bootstrap components
• Follow React hooks rules
• Keep components small
• Always test production builds

Troubleshooting

Changes not visible?

• Ensure dev server is running
• Hard refresh browser
• Check console for errors
• Confirm file path

HMR not working?

• Restart dev server
• Check vite.config.js
• Clear cache

Build failing?

• Fix syntax errors
• Verify imports
• Run npm run lint

Congratulations 🎉

You’ve now:

• Made your first customization
• Used HMR
• Added custom styles
• Built for production
• Learned the dev workflow