@fyit/crouton-maps

> Map integration layer for Nuxt Crouton with Mapbox support

Add interactive maps to your Nuxt Crouton applications with this powerful, easy-to-use layer built on Mapbox GL JS.

Features

- 🗺️ Mapbox GL JS Integration - Beautiful, performant vector maps
- 🎯 Easy Geocoding - Convert addresses to coordinates and vice versa
- 📍 Marker Management - Simple marker and popup components
- 🔐 Secure API Keys - Runtime config for safe key management
- 🎨 Nuxt UI 4 Styling - Seamless integration with Crouton design system
- 📦 TypeScript First - Full type safety out of the box
- 🔌 Extensible - Built for future provider support (Google Maps, Leaflet, etc.)

Installation

``bash
pnpm add @fyit/crouton-maps
`

Setup

$3

`typescript
// nuxt.config.ts
export default defineNuxtConfig({
extends: [
'@fyit/crouton',
'@fyit/crouton-maps'
],

runtimeConfig: {
public: {
mapbox: {
accessToken: process.env.MAPBOX_TOKEN,
// Optional defaults
style: 'mapbox://styles/mapbox/streets-v12',
center: [-122.4194, 37.7749], // [lng, lat]
zoom: 12
}
}
}
})
`

$3

Create a .env file:

`bash
MAPBOX_TOKEN=pk.eyJ1IjoieW91ciIsImEiOiJ0b2tlbiJ9...
`

Get a free Mapbox token: https://account.mapbox.com/access-tokens/

Usage

$3

`vue



`

$3

`vue



`

$3

`vue



`

$3

`vue



`

Components

$3

Main map container component.

Props:
- id - Map container ID (auto-generated)
- center - Initial center coordinates [lng, lat]
- zoom - Initial zoom level (default: 12)
- style - Mapbox style URL
- height - Container height (default: '400px')
- width - Container width (default: '100%')
- class - Additional CSS classes

Events:
- @load - Emitted when map loads, receives map instance
- @error - Emitted on error, receives error message

Slots:
- default - Scoped slot with { map } for adding markers/popups

$3

Map marker component.

Props:
- map - Map instance (required)
- position - Marker position [lng, lat] (required)
- color - Marker color
- options - Mapbox MarkerOptions
- popupContent - HTML content for popup

Events:
- @click - Marker clicked
- @dragStart - Drag started
- @drag - Dragging
- @dragEnd - Drag ended

$3

Popup component.

Props:
- map - Map instance (required)
- position - Popup position [lng, lat] (required)
- closeButton - Show close button (default: true)
- closeOnClick - Close on map click (default: true)
- maxWidth - Max width (default: '240px')

Events:
- @open - Popup opened
- @close - Popup closed

Slots:
- default - Popup content

Composables

$3

Core map management composable.

`typescript
const { map, isLoaded, error, initialize, destroy, resize } = useMap()

await initialize({
container: 'map-container',
center: [-122.4194, 37.7749],
zoom: 12
})
`

$3

Marker management composable.

`typescript
const { marker, addMarker, removeMarker, setPosition, togglePopup } = useMarker()

addMarker({
map: mapInstance,
position: [-122.4194, 37.7749],
popup: { content: '

Hello

' }
})
`

$3

Geocoding composable.

`typescript
const { geocode, reverseGeocode, loading, error } = useGeocode()

// Address → Coordinates
const result = await geocode('1600 Amphitheatre Parkway')

// Coordinates → Address
const result = await reverseGeocode([-122.0840575, 37.4220656])
`

$3

Access map configuration.

`typescript
const { accessToken, style, center, zoom } = useMapConfig()
`

Mapbox Styles

$3

The package provides convenient presets for all Mapbox default styles:

`vue



`

$3

- standard - New Mapbox Standard style (recommended) - fully customizable 3D
- streets - Classic streets style (default)
- outdoors - Topographic with hiking trails
- light - Minimalist light theme
- dark - Dark theme for night mode
- satellite - Satellite imagery only
- satelliteStreets - Satellite with street labels
- navigationDay - Optimized for daytime navigation
- navigationNight - Optimized for nighttime navigation

$3

You can also use custom styles from Mapbox Studio:

`vue
style="mapbox://styles/your-username/your-custom-style-id"
/>
`

$3

Set a default style for your entire app in nuxt.config.ts:

`typescript
export default defineNuxtConfig({
runtimeConfig: {
public: {
mapbox: {
accessToken: process.env.MAPBOX_TOKEN,
style: 'mapbox://styles/mapbox/dark-v11' // or use MAPBOX_STYLES constant
}
}
}
})
`

API Limits

Mapbox Free Tier:
- 50,000 map loads/month
- 100,000 geocoding requests/month
- Unlimited static maps

For higher limits, see: https://www.mapbox.com/pricing/

TypeScript Support

All components and composables are fully typed. Import types from the package:

`typescript
import type {
MapConfig,
MapInstance,
MarkerInstance,
GeocodeResult,
UseMapOptions
} from '@fyit/crouton-maps'
``

Future Roadmap

- 🗺️ Additional map providers (Google Maps, Leaflet, MapLibre)
- 🎨 Custom marker components
- 📊 Heatmap support
- 🛣️ Route visualization
- 🌍 Clustering for large datasets
- 🔍 Advanced search with autocomplete

License

MIT

Contributing

Issues and PRs welcome at https://github.com/pmcp/nuxt-crouton

---

Built with ❤️ by FYIT