Manage function dependencies

Functions can be self-contained, or part of a larger ecosystem. Learn how to manage function dependencies in your projects.

Once you go beyond the basics of creating your first Function, you'll likely need to add dependencies (like the @sanity/client). Functions use a dependency management system that tries to match how you'd like to work, while still remaining efficient.

This article explains the different approaches to using dependency packages in your functions.

Prerequisites:

• Complete the Functions quick start, or be comfortable writing and deploying a Sanity Function.
• sanity CLI v3.96.0 or higher is recommended to interact with Blueprints and Functions. You can always run the latest CLI commands with npx sanity@latest.

You have a few options for where to place a dependency, or package, as part of your function code.

Project-level dependencies are positioned alongside the sanity.blueprint.ts file and often defined at the root of the project. If you've initialized the blueprint with a TypeScript/JavaScript configuration, you already have a package.json at this level.

marketing_site/
├─ studio/
├─ next-app/
├─ functions/
│  ├─ my-function/
│  │  ├─ index.ts
├─ sanity.blueprint.ts
├─ package.json <-- Install dependencies here, alongside the blueprint configuration file
├─ node_modules/

This allows you to manage your function dependencies alongside any project-wide dependencies, like developer dependencies, and share them across functions.

Sometimes it makes sense to keep a function and all of it's dependencies contained in a single directory, separate from the concerns of the greater project.

To do this, navigate to the individual function's directory and initialize a new package.json with npm init or similar, and then add dependencies directly to the function.

marketing_site/
├─ studio/
├─ next-app/
├─ functions/
│  ├─ my-function/
│  │  ├─ index.ts
│  │  ├─ package.json <-- Install dependencies here, alongside the function code
│  │  ├─ node_modules/
├─ sanity.blueprint.ts

You may have instances where some functions use the function-level system, and others use the project-level system.

In this scenario, those using the function-level structure will use their own, co-located dependencies. Other functions will use the project-level dependency system.

Functions will not use or mix both sources. If you'd like a function using the function-level system to use a dependency from the project-level, you must also install it as a dependency at the function level.

marketing_site/
├─ studio/
├─ next-app/
├─ functions/
│  ├─ my-function/
│  │  ├─ index.ts
│  │  ├─ package.json <-- This is used for my-function
│  │  ├─ node_modules/
│  ├─ log-event/
│  │  ├─ index.ts
├─ sanity.blueprint.ts
├─ package.json <-- This is used for log-event
├─ node_modules/

If you have an existing function that's set up with the function-level system, you can migrate it to project-level in the following steps:

• Add the function dependencies to the project-level package manifest. Either by using npm install <package name(s)> or by adding the packages to the file manually and running npm install.
• Remove the package.json file and node_modules directory from the function folder.

The process is similar going in the other direction. To move from the project-level system to function-level for an individual function:

• Navigate to the function's directory and initialize a package.json with npm init or similar.
• Install any packages at this level, alongside your function code with npm i <package name>.
• If the dependency is no longer required by other functions, remove the packages from the project-level package.json manually or by running npm uninstall <package name> in the same directory as your sanity.blueprints.ts file.