Integrations

Third-party tools and APIs can speed up development, but adding too many external dependencies can create security risks, increase bundle size, and make maintenance more difficult. We follow strict patterns to integrate services cleanly.

Integration Principles

When adding third-party integrations, keep these rules in mind:

• Environment-First Config: All API credentials, keys, and endpoint paths must be validated at startup through the central environment schema. Never hardcode strings in component files.
• Modular Wrappers: Wrap external clients in a local module or utility file (e.g. src/shared/lib/analytics) to isolate vendor-specific APIs. If you switch vendors later, you will only need to update this wrapper.
• Fail-Safe Code: Wrap API integrations in try/catch blocks to prevent external service downtime from breaking your core application.

Common Categories

The edd Starter is pre-wired to support popular developer services:

• Authentication: Setup for Clerk/Better-Auth out-of-the-box. Provides page middleware and pre-configured callback endpoints.
• Database & Storage: Integrated with PostgreSQL databases via Drizzle ORM. Local storage adapters can be swapped for AWS S3, Cloudflare R2, or Supabase Storage.
• AI Models: Unified schemas to switch between cloud models (OpenAI, Anthropic) and local development models (Ollama, LM Studio).
• Payments (Upcoming): Structured billing handlers designed for Stripe and LemonSqueezy subscription setups.

Implementation Notes

To add a new integration (e.g., PostHog for analytics):

1. Install the client library: pnpm add posthog-js.
2. Define the environment variables in .env and add validation to your environment schema.
3. Create a client provider file: src/shared/lib/analytics.ts.
4. Wrap your root application component in the provider (located in src/routes/-root-components.tsx) to initialize the client.