Benin Contact Updater

Benin Contact Updater is a lightweight utility built to address a practical problem caused by Benin's transition to a 10-digit telephone numbering system. Updating an entire address book manually can be tedious, especially for users with hundreds of saved contacts.

I developed this application to automate the migration process through a simple browser-based workflow: import an existing contact file, process the phone numbers, preview the contacts, and export the updated address book.

Source code: github.com/aploon/benin-contact-updater

How it works

The application follows a straightforward contact-migration workflow:

Import contacts: Load an existing .vcf (vCard) file containing contact information.
Normalize phone numbers: Add the 01 prefix to eligible Beninese phone numbers when it is missing.
Preview the results: Review contact information before exporting the updated file.
Export contacts: Download the processed contacts in VCF format for use with compatible contact management applications.

This approach turns a repetitive manual task into a single file-processing operation while preserving the convenience of the standard vCard format.

Technical implementation

The application is built with React, TypeScript, Vite, and Tailwind CSS, providing a lightweight frontend architecture with a clear separation between the user interface and contact-processing logic.

The source code is organized into focused components and utility modules:

Component or module	Responsibility
`App.tsx`	Main application interface and workflow
`FileDropzone.tsx`	Contact file selection and import interface
`ContactPreview.tsx`	Displaying contacts before export
`DownloadButton.tsx`	Triggering the download of processed contacts
`ErrorMessage.tsx`	Presenting errors to the user
`phoneUtils.ts`	Phone number processing and normalization
`vcfUtils.ts`	VCF-related processing
`fileUtils.ts`	File-handling utilities
`Contact.ts`	TypeScript contact data definitions

Separating file handling, phone number processing, and VCF operations into dedicated utilities makes the code easier to understand, test, and maintain independently of the presentation layer.

Engineering considerations

Phone number normalization

The core business rule is to add the 01 prefix to eligible Beninese phone numbers when it is missing. This operation needs to distinguish numbers that require updating from those that already follow the expected format.

For a contact migration utility, normalization must also account for differences in how phone numbers are represented, such as whitespace, separators, and international prefixes. These are important edge cases to consider when extending or validating the implementation.

VCF compatibility

VCF, also known as vCard, is a widely used format for exchanging contact information between devices and applications. Using it as both the import and export format allows users to work with their existing address books without requiring a proprietary contact database.

The dedicated vcfUtils.ts module isolates format-specific processing from the rest of the application.

User experience

The interface is organized around a task that users can complete without technical knowledge. File import, contact preview, error feedback, and downloading are represented by dedicated components, helping keep the workflow understandable and focused.

Development and tooling

The project uses Vite for the development server and production build, TypeScript for static type checking, and Tailwind CSS for styling.

Available commands:

npm install
npm run dev
npm run build
npm run lint

The project is open source under the MIT License, allowing others to use, adapt, and contribute to the tool.

What this project demonstrates

Practical problem-solving: Turning a nationwide telephone numbering change into a simple, usable migration tool.
Frontend engineering: Building a component-based React application with TypeScript.
Data transformation: Processing structured contact files and applying phone number normalization rules.
Separation of concerns: Isolating file operations, VCF handling, and phone number utilities from UI components.
Open-source development: Publishing a reusable tool and welcoming contributions through issues and pull requests.