Edge Functions

Managing dependencies

Managing packages and dependencies.


Importing dependencies

Supabase Edge Functions support several ways to import dependencies:

NPM modules

You can import npm modules using the npm: specifier:

import { createClient } from 'npm:@supabase/supabase-js@2'

Node.js built-ins

For Node.js built-in APIs, use the node: specifier:

import process from 'node:process'

Learn more about npm specifiers and Node built-in APIs in Deno's documentation.

JSR

You can import JS modules published to JSR (e.g.: Deno's standard library), using the jsr: specifier:

import path from 'jsr:@std/path@1.0.8'

Managing dependencies

Developing with Edge Functions is similar to developing with Node.js, but with a few key differences.

In the Deno ecosystem, each function should be treated as an independent project with its own set of dependencies and configurations. This "isolation by design" approach:

  • Ensures each function has explicit control over its dependencies
  • Prevents unintended side effects between functions
  • Makes deployments more predictable and maintainable
  • Allows for different versions of the same dependency across functions

For these reasons, we recommend maintaining separate configuration files (deno.json, .npmrc, or import_map.json) within each function's directory, even if it means duplicating some configurations.

There are two ways to manage your dependencies in Supabase Edge Functions:

Each function should have its own deno.json file to manage dependencies and configure Deno-specific settings. This ensures proper isolation between functions and is the recommended approach for deployment. For a complete list of supported options, see the official Deno configuration documentation.

supabase/functions/my-function/deno.json
{
"imports": {
"lodash": "https://cdn.skypack.dev/lodash"
}
}

The recommended file structure for deployment:

└── supabase
├── functions
├── function-one
│ ├── index.ts
│ ├─- deno.json # Function-specific Deno configuration
│ └── .npmrc # Function-specific npm configuration (if needed)
└── function-two
├── index.ts
├─- deno.json # Function-specific Deno configuration
└── .npmrc # Function-specific npm configuration (if needed)
└── config.toml

Using import maps (legacy)

Import Maps are a legacy way to manage dependencies, similar to a package.json file. While still supported, we recommend using deno.json. If both exist, deno.json takes precedence.

Each function should have its own import_map.json file for proper isolation:

supabase/functions/my-function/import_map.json
{
"imports": {
"lodash": "https://cdn.skypack.dev/lodash"
}
}

The recommended file structure:

└── supabase
├── functions
├── function-one
│ ├── index.ts
│ └── import_map.json # Function-specific import map
└── function-two
├── index.ts
└── import_map.json # Function-specific import map
└── config.toml

If using import maps with VSCode, update your .vscode/settings.json to point to your function-specific import map:

settings.json
{
"deno.enable": true,
"deno.unstable": [
"bare-node-builtins",
"byonm"
// ... other flags ...
],
"deno.importMap": "./supabase/functions/my-function/import_map.json"
}

You can override the default import map location using the --import-map <string> flag with serve and deploy commands, or by setting the import_map property in your config.toml file:

supabase/config.toml
[functions.my-function]
import_map = "./supabase/functions/my-function/import_map.json"

Importing from private registries

To use private npm packages, create a .npmrc file within your function directory. This ensures proper isolation and dependency management for each function.

└── supabase
└── functions
└── my-function
├── index.ts
├── deno.json
└── .npmrc # Function-specific npm configuration

Add your registry details in the .npmrc file. Follow this guide to learn more about the syntax of npmrc files.

@myorg:registry=https://npm.registryhost.com
//npm.registryhost.com/:_authToken=VALID_AUTH_TOKEN

After configuring your .npmrc, you can import the private package in your function code:

import MyPackage from 'npm:@myorg/private-package@v1.0.1'

// use MyPackage

Using a custom NPM registry

Some organizations require a custom NPM registry for security and compliance purposes. In such instances, you can specify the custom NPM registry to use via NPM_CONFIG_REGISTRY environment variable.

You can define it in the project's .env file or directly specify it when running the deploy command:

NPM_CONFIG_REGISTRY=https://custom-registry/ supabase functions deploy my-function

Importing types

If your environment is set up properly and the module you're importing is exporting types, the import will have types and autocompletion support.

Some npm packages may not ship out of the box types and you may need to import them from a separate package. You can specify their types with a @deno-types directive:

// @deno-types="npm:@types/express@^4.17"
import express from 'npm:express@^4.17'

To include types for built-in Node APIs, add the following line to the top of your imports:

/// <reference types="npm:@types/node" />
    1. We use first-party cookies to improve our services.

      Learn more