A professional, secure, and highly decoupled TypeScript wrapper around the Google Maps JavaScript API.
This project demonstrates advanced Object-Oriented Programming (OOP) principles, especially Inversion of Control (IoC) through TypeScript Interfaces, resulting in clean, maintainable, and loosely coupled code.
- ✅ Decoupled architecture using a
Mappableinterface - ✅ Type-safe development with
@types/google.maps - ✅ Secure API key management using Parcel environment variables
- ✅ Dynamic Google Maps script loading
- ✅ Automatic InfoWindow handling
- ✅ Easy extension with any custom domain model (
User,Company,Store, etc.) - ✅ Uses Faker.js for generating realistic mock data
This project started as a learning implementation while exploring TypeScript, Object-Oriented Programming, and software design principles.
During this process, I built a reusable wrapper around the Google Maps JavaScript API using concepts like Interfaces, Inversion of Control (IoC), and clean architecture.
After completing the implementation, I decided to open-source this project because I believe this wrapper can be useful for other developers who want a simple, reusable, and maintainable way to integrate Google Maps into their applications.
The goal of this project is to provide a practical solution that developers can use, customize, and extend according to their own requirements.
Feel free to use it, modify it, and contribute to make it better.
.
├── src/
│ ├── CustomMap.ts
│ └── index.ts
├── .env
├── .env.example
├── .gitignore
├── package.json
└── README.md
This is the core of the project.
It contains:
- The
Mappableinterface - The
CustomMapwrapper class - Marker creation logic
- InfoWindow handling
The map does not depend on any specific application class. It only depends on the Mappable contract.
Application entry point.
Responsibilities:
- Loading Google Maps dynamically
- Reading environment variables
- Creating example implementations
- Adding markers to the map
Stores your local Google Maps API key.
Example:
PARCEL_GOOGLE_MAPS_API_KEY=YOUR_GOOGLE_MAPS_API_KEYExample configuration file for contributors.
PARCEL_GOOGLE_MAPS_API_KEY=git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git
cd YOUR_REPOSITORYnpm installCreate a .env file in the root directory.
PARCEL_GOOGLE_MAPS_API_KEY=YOUR_GOOGLE_MAPS_API_KEYnpx parcel index.htmlOpen:
http://localhost:1234
The heart of this project is the CustomMap.ts file.
Instead of creating separate logic for every entity, the map follows a contract using the Mappable interface.
export interface Mappable {
location:{
lat:number;
lng:number;
};
markerContent():string;
}Any class implementing this interface can be added to the map.
Examples:
- User
- Company
- Restaurant
- Hotel
- Store
export class CustomMap {
private googleMap:google.maps.Map;
constructor(divId:string){
this.googleMap = new google.maps.Map(
document.getElementById(divId) as HTMLElement,
{
zoom:1,
center:{
lat:0,
lng:0
}
});
}
addMarker(mappable:Mappable):void{
const marker = new google.maps.Marker({
map:this.googleMap,
position:{
lat:mappable.location.lat,
lng:mappable.location.lng
}
});
marker.addListener("click",()=>{
const infoWindow = new google.maps.InfoWindow({
content:mappable.markerContent()
});
infoWindow.open(
this.googleMap,
marker
);
});
}
}This project demonstrates:
- Object-Oriented Programming (OOP)
- Interfaces
- Inversion of Control (IoC)
- Dependency Inversion Principle (DIP)
- Loose Coupling
- Separation of Concerns
- Reusable Components
- Type Safety
Google Maps API keys are not hardcoded.
Instead, Parcel loads them from environment variables.
const apiKey = process.env.PARCEL_GOOGLE_MAPS_API_KEY;Benefits:
- API keys remain private
.envstays local- Safer GitHub repositories
- Easier deployment
The Google Maps script is loaded dynamically instead of directly adding it to HTML.
Benefits:
- Prevents
google is not definederrors - Cleaner application startup
- Better control over loading process
Each marker click creates an InfoWindow containing custom content.
This allows every model implementing Mappable to control its own marker information.
This repository does not include an index.html file by default to keep the project flexible.
You can create your own HTML file according to your application requirements.
Example:
<!DOCTYPE html>
<html>
<head>
<title>Custom Mappable Map</title>
</head>
<body>
<div id="map" style="height:100vh;width:100%">
</div>
<script src="./src/index.ts" type="module"></script>
</body>
</html>Create a Google Maps API key:
https://developers.google.com/maps/documentation/javascript/get-api-key
Add it to your .env:
PARCEL_GOOGLE_MAPS_API_KEY=YOUR_GOOGLE_MAPS_API_KEYThe application will load Google Maps automatically:
const script=document.createElement("script");
script.src=
`https://maps.googleapis.com/maps/api/js?key=${apiKey}`;
script.async=true;
script.defer=true;
document.head.appendChild(script);- TypeScript
- Google Maps JavaScript API
- Parcel
- Node.js
- Faker.js
Used for:
- Interactive maps
- Markers
- Events
- InfoWindows
https://developers.google.com/maps/documentation/javascript
Used to generate realistic fake data such as:
- Names
- Locations
- Companies
- Random mock information
Special thanks to all open-source contributors who make these tools available for developers.
This project is created for educational and demonstration purposes.
I do not take responsibility for:
- Incorrect configuration or usage
- Third-party API costs or limitations
- Data accuracy from external services
- Modifications made after forking this project
Users are responsible for:
- Managing their own API keys
- Following third-party service policies
- Reviewing and adapting the code for their own requirements
Use this project at your own discretion.
This project is licensed under the MIT License.
See the LICENSE file for more information.
⭐ If this project helped you understand TypeScript architecture or Google Maps integration, consider giving it a star!