Skip to main content

​
Quickstart Guide

This guide will walk you through setting up Pagosapp and creating your first payment tracking system. By the end, you’ll have a fully functional payment management dashboard.

​
Prerequisites

Before getting started, ensure you have:
  • Node.js (version 14 or higher)
  • npm or yarn package manager
  • A modern web browser (Chrome, Firefox, Safari, or Edge)
Check your Node.js version by running node --version in your terminal.

​
Installation

1

Clone the Repository

First, clone the Pagosapp repository to your local machine:
git clone https://github.com/Sagthy/appPagos.git
cd appPagos
This creates a local copy of the project and navigates into the project directory.
2

Install Dependencies

Install all required packages using npm:
npm install
This installs:
  • React 18.2 and React DOM
  • Chakra UI component library
  • date-fns for date utilities
  • react-datepicker for date selection
  • Vite for development and building
  • All other required dependencies
Installation typically takes 1-2 minutes depending on your internet connection.
3

Start the Development Server

Launch the application in development mode:
npm run dev
Vite will start the development server and display the local URL:
VITE v5.1.0  ready in 300 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
Open the displayed URL in your browser to access Pagosapp.
4

Verify Installation

You should see the Pagosapp interface with:
  • A header displaying “PAGOS PENDIENTES” (Pending Payments)
  • Three month columns showing the current and adjacent months
  • Default payment items already configured
  • Navigation buttons (“Anterior” and “Siguiente”) to browse months
If you see errors, ensure all dependencies installed correctly and that port 5173 is available.

​
Understanding the Interface

Before creating your first payment, let’s understand the main components:

​
Month View

The interface displays three months at a time, allowing you to see your payment schedule across multiple periods: 
// The app shows 3 consecutive months
const showedMonths = meses.slice(indiceInicio, indiceInicio + 3)

​
Payment Item Colors

Each payment item is color-coded for quick status recognition:
  • Green - Payment completed
  • Orange - Due within 3 days (urgent)
  • Red - Overdue
  • Gray - Not urgent or no due date set
  • Anterior (Previous) - View earlier months
  • Siguiente (Next) - View later months
  • + Button (top center) - Add new payment item
  • Reset Button (bottom) - Clear all data and start fresh

​
Creating Your First Payment

1

Open the Add Payment Modal

Click the red + button at the top of the screen to open the “Add New Item” modal:
<IconButton 
  aria-label='Add Items' 
  icon={<AddIcon />} 
  onClick={onOpen} 
/>
2

Enter Payment Details

In the modal, you’ll see two fields:Payment Name
<Input
  type='text'
  placeholder='Enter payment name'
  value={nombre}
  onChange={(e) => setName(e.target.value)}
/>
Enter a descriptive name like:
  • “Netflix Subscription”
  • “Electric Bill”
  • “Car Insurance”
  • “Property Tax”
Select MonthsClick the “Selecciona los meses” (Select Months) button to choose:
  • Mensual - For recurring monthly payments
  • Specific Months - For one-time or irregular payments
Selecting “Mensual” automatically disables individual month selection since the payment appears every month.
3

Choose Payment Type

Decide between two payment types:Monthly Recurring PaymentFor subscriptions or bills that occur every month:
{
  nombre: 'Netflix',
  mensual: true,
  meses: []  // Empty array for monthly payments
}
Specific Month PaymentFor annual or quarterly payments:
{
  nombre: 'Car Insurance',
  mensual: false,
  meses: ['Marzo', 'Septiembre']  // Twice a year
}
4

Save the Payment

Click the Guardar (Save) button. The modal validates your input:
if (!nombre.trim()) {
  setError('El nombre no puede estar vacío.')
  return
}

if (meses.length === 0) {
  setError('Debes seleccionar al menos un mes.')
  return
}
Your new payment item will appear in the appropriate month columns.

​
Setting a Due Date

1

Locate the Payment Item

Find your payment in the month view. Each payment displays:
  • Payment name
  • Status toggle switch
  • Pencil icon for date editing
2

Open the Date Picker

Click the pencil icon (📝) next to the payment name:
<button onClick={() => setOpenDatePicker(!openDatePicker)}>
  <FontAwesomeIcon icon={faPencilAlt} />
</button>
A calendar interface will appear.
3

Select the Due Date

Choose the date when the payment is due. The date picker uses react-datepicker:
<DatePickerElement
  startDate={startDate}
  handleDateChange={handleDateChange}
  openDatePicker={openDatePicker}
/>
The selected date is stored in localStorage:
localStorage.setItem(`startDate-${mes}-${pago.nombre}`, date.toISOString())
4

View Due Date Status

After setting a due date, the payment item will display:
  • Days remaining until due date
  • Color-coded status indicator
The app calculates the time difference:
export const calculateDateDifference = (startDate) => {
  const now = new Date()
  const start = new Date(startDate)
  const diffTime = start - now
  const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24))
  return diffDays
}

​
Marking Payments as Paid

1

Toggle Payment Status

Each payment item has a switch component that toggles between paid/unpaid:
<SwitchElement 
  checked={checked} 
  handleChange={handleChange} 
/>
Click the switch to mark the payment as complete. The status is immediately saved:
const handleChange = (checked) => {
  setChecked(checked)
  localStorage.setItem(`checked-${mes}-${pago.nombre}`, checked)
}
2

Record Payment Date

After marking a payment as paid, click on the payment item to open the details modal.In the modal, you’ll see:
  • Due date (if set)
  • Payment date field (appears when payment is marked as paid)
Click the pencil icon next to “Fecha de pago” (Payment Date) to record when you actually made the payment:
{checked && (
  <Flex gap='0.3rem'>
    <p>Fecha de pago: {paymentDate ? paymentDate.toLocaleDateString() : 'No ingresada'}</p>
    <button onClick={() => setOpenDatePicker(!openDatePicker)}>
      <FontAwesomeIcon icon={faPencilAlt} />
    </button>
  </Flex>
)}
3

Visual Confirmation

When marked as paid, the payment item turns green, providing immediate visual confirmation:
if (checked) {
  itemStyle = 'item-green'
}
Pagosapp displays three months at a time. Navigate through the year: 
const handleNextClick = () => {
  if (indiceInicio + 1 < meses.length - 2) {
    setIndiceInicio(indiceInicio + 1)
  }
}

const handlePreviousClick = () => {
  if (indiceInicio - 1 >= 0) {
    setIndiceInicio(indiceInicio - 1)
  }
}
The app starts by displaying the current month and the surrounding months, making it easy to see your immediate payment obligations.

​
Viewing Payment Details

Click any payment item to open a detailed modal showing:
  • Payment name
  • Due date (Fecha de vencimiento)
  • Payment date (Fecha de pago) - only visible when marked as paid
<PaymentModal 
  isOpen={isOpen} 
  onClose={onClose} 
  paymentInfo={pago}
  fechaVencimiento={startDate}
  mes={mes}
  checked={checked}
/>

​
Data Persistence

All your data is automatically saved to localStorage. The ItemsContext handles synchronization: 
const ItemsProvider = ({ children }) => {
  const [items, setItems] = useState(
    localStorage.getItem('items') 
      ? JSON.parse(localStorage.getItem('items')) 
      : paymentsConstants
  )

  useEffect(() => {
    localStorage.setItem('items', JSON.stringify(items))
  }, [items])
  
  // ...
}
Your payment data persists across:
  • Browser refreshes
  • Tab closures
  • Application restarts
Clearing browser data or localStorage will delete all payment information. The app will reset to default payment items.

​
Resetting the Application

If you want to start fresh:
1

Locate Reset Button

Scroll to the bottom of the page to find the red Reset button.
2

Clear All Data

Click Reset to clear all payment data:
const handleResetClick = () => {
  localStorage.clear()
  window.location.reload()
}
This removes:
  • All custom payment items
  • All due dates
  • All payment statuses
  • All payment dates
The app reloads with default payment items.
The reset action is immediate and cannot be undone. Make sure you want to delete all data before clicking.

​
Example Workflow

Here’s a complete example of tracking a monthly subscription:
1

Add Netflix Subscription

  1. Click the + button
  2. Enter “Netflix” as the payment name
  3. Select Mensual from the months menu
  4. Click Guardar
Result: Netflix appears in all month columns
2

Set Due Date

  1. Click the pencil icon on the Netflix payment
  2. Select the 15th of the month
  3. Close the date picker
Result: Netflix shows “X days” until the 15th
3

Monitor Status

As the due date approaches:
  • 4+ days away: Gray (not urgent)
  • 1-3 days away: Orange (approaching)
  • Overdue: Red (needs attention)
4

Mark as Paid

  1. Toggle the switch to mark as paid
  2. Click the payment item
  3. Set the actual payment date
  4. Close the modal
Result: Netflix turns green, indicating completion
5

Next Month

Navigate to next month using Siguiente. Netflix appears again, unmarked and ready to track.
Payment status is tracked per month, so monthly payments reset each month automatically.

​
Building for Production

When you’re ready to deploy Pagosapp: 
npm run build
This creates an optimized production build in the dist directory: 
vite build
# Output:
# dist/index.html
# dist/assets/index-[hash].js
# dist/assets/index-[hash].css
Deploy the dist folder to any static hosting service:
  • Vercel
  • Netlify
  • GitHub Pages
  • AWS S3
  • Any web server

​
Preview Production Build

Test the production build locally: 
npm run preview
This serves the built application using Vite’s preview server.

​
Troubleshooting

​
Port Already in Use

If port 5173 is occupied: 
# Vite will automatically try the next available port
# Or specify a custom port:
npm run dev -- --port 3000

​
Data Not Persisting

Check that localStorage is enabled in your browser: 
// Test localStorage availability
try {
  localStorage.setItem('test', 'test')
  localStorage.removeItem('test')
  console.log('localStorage is available')
} catch (e) {
  console.error('localStorage is not available')
}

​
Dates Not Displaying Correctly

Ensure your system date is set correctly. The app uses local system time for all date calculations.

​
Next Steps

Now that you have Pagosapp running:
  1. Add your real payments - Replace default items with your actual bills and subscriptions
  2. Set due dates - Configure when each payment is due
  3. Establish a routine - Check Pagosapp daily or weekly to stay on top of payments
  4. Customize - Explore the source code to add custom features for your needs
Consider setting Pagosapp as your browser’s new tab page or bookmarking it for quick access.

​
Support & Resources

You’re now ready to track all your payments efficiently with Pagosapp!

Build docs developers (and LLMs) love

Get started for freeTalk to us