Manage function dependencies

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

Your functions can use packages such as @sanity/client installed either at the project level, next to sanity.blueprint.ts, or at the function level, in the function's own directory.

This article explains the different approaches to using dependency packages in your functions. For guidance on file structures for the Blueprints configuration that Functions rely on in different project layouts and monorepo contexts, see Project layout and monorepos.

Prerequisites:

• Complete the Functions quick start, or be comfortable writing and deploying a Sanity Function.
• The latest version of the sanity CLI (sanity@latest) is recommended to interact with Blueprints and Functions as shown in this guide. 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 lets you 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 its 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 use their own, co-located dependencies. Other functions use the project-level dependency system.

Functions don't 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. When the CLI bundles a TypeScript function (in a pnpm workspace, or when you deploy with --fn-installer pnpm), imports missing from the function-level install can still resolve from a node_modules directory higher in the project. Don't rely on this: declare every package the function imports in its own package.json.

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.blueprint.ts file.

• To choose a repository layout, control which package manager the CLI uses, or turn off bundling and dependency resolution per function with transpile: false and autoResolveDeps: false, see Project layout and monorepos.
• To query and update content from a function, see Configure @sanity/client in Functions.