Development guide for Nekometrics dashboard - Next.js metrics aggregation app with OAuth integrations
Development instructions for Nekometrics, a Next.js application that centralizes metrics and KPIs from multiple external services (Google Analytics, Facebook/Instagram, Twitter, Mailchimp, WooCommerce, EDD) into customizable dashboards.
When working with this codebase, use these commands:
```bash
pnpm dev
pnpm build
pnpm start
pnpm start-stg
pnpm analyze
```
Before making changes, understand these core architectural components:
Each external service (Google Analytics, Facebook, Twitter, etc.) has its own module handling:
The `Services` class (`libs/services.js`) acts as the central registry, mapping widget types to their data fetching functions.
**WidgetsFactory** (`components/widgets/WidgetsFactory.js`):
**WidgetsRepository** (`components/widgets/WidgetsRepository.js`):
- Display component (e.g., `google/AnalyticsVisits.js`)
- Settings component (e.g., `google/AnalyticsVisitsSettings.js`)
Key endpoints:
1. Widgets fetch data via `/api/metrics/[widgetId]`
2. API routes use the Services layer to call external APIs
3. Data is cached in MongoDB with configurable refresh intervals
4. Widgets auto-refresh at randomized intervals to prevent simultaneous requests
Custom authentication system:
Create `.env.local` from `.env` template with:
```bash
DATABASE_URL=mongodb://...
SMTP_HOST=...
SMTP_PORT=...
SMTP_USER=...
SMTP_PASS=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
FACEBOOK_APP_ID=...
FACEBOOK_APP_SECRET=...
TWITTER_API_KEY=...
TWITTER_API_SECRET=...
MAILCHIMP_CLIENT_ID=...
MAILCHIMP_CLIENT_SECRET=...
SECRET=...
```
MongoDB collections:
1. Create service module in `libs/services/[serviceName]/`
2. Implement OAuth flow in `pages/api/oauth/[serviceName].js`
3. Add data fetching functions
4. Register service in `Services` class (`libs/services.js`)
5. Create widget components in `components/widgets/[serviceName]/`
6. Register widgets in `WidgetsRepository.js`
1. Create widget component in appropriate service directory
2. Create corresponding settings component
3. Register in `WidgetsRepository.js` with:
- Widget component
- Settings component
- Default configuration
4. Add metrics endpoint handler if needed
1. Check widget component for API endpoint used
2. Trace API route in `pages/api/metrics/[widgetId].js`
3. Follow to Services layer method
4. Check external service module for actual API call
5. Verify MongoDB caching logic
**Refresh intervals**: Configured per-widget in settings, stored in Widget document
**OAuth tokens**: Stored in Service collection, automatically refreshed by service modules
**Cache invalidation**: Handled by refresh job (`pages/api/job/refresh.js`)
**Error handling**: Widget components display error states; API routes return standardized error responses
Configured for Coolify deployment:
All configurable via environment variables.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/nekometrics-development/raw