Source: ocean/docs/adr/021-edge-function-dependency-management.md | ✏️ Edit on GitHub

ADR-021: Edge Function Dependency Management

Date: 2024-08-20

Status

Accepted

Context

Our Edge Functions failed due to inconsistent dependency management:

1. Different functions using different Sentry import patterns (legacy vs npm)
2. Missing dependencies in deno.json files
3. No centralized dependency version management
4. Functions using deprecated or incompatible APIs

This caused runtime errors that were difficult to debug because functions would fail to start without clear error messages.

Decision

We will standardize Edge Function dependency management:

1. Use NPM imports exclusively for third-party dependencies
2. Centralize dependency versions where possible
3. Explicit dependency declaration in deno.json for each function
4. Regular dependency audits to catch deprecated APIs

Standards

1. Import Pattern:

   // ✅ Good - NPM import with version
   import * as Sentry from 'npm:@sentry/deno@7.119.2'
   
   // ❌ Bad - Legacy Deno import
   import * as Sentry from 'https://deno.land/x/sentry/index.mjs'

2. Deno.json Structure:

   {
     "imports": {
       "@supabase/supabase-js": "npm:@supabase/supabase-js@2.54.0",
       "@sentry/deno": "npm:@sentry/deno@7.119.2",
       "stripe": "npm:stripe@18.4.0"
     }
   }

3. Shared Dependencies:

   • Create _shared/deps.ts for common versions
   • Import from shared file in individual functions

4. Version Pinning:

   • Always pin to specific versions, not ranges
   • Document reason for version choices
   • Update all functions together

Consequences

Positive

• Consistent behavior across all Edge Functions
• Easier to debug dependency issues
• Prevents version mismatch bugs
• Clearer dependency tree

Negative

• More verbose import declarations
• Need to update multiple files for version changes
• Potential for larger bundle sizes if not careful

Migration Path

1. Audit all Edge Functions for import patterns
2. Create deno.json for functions missing it
3. Update all imports to use npm pattern
4. Test each function after updates
5. Document any API changes needed