Skip to main content
Convex backends can be configured through convex.json and runtime options. This document covers the available configuration options for controlling backend behavior.

​
Project configuration (convex.json)

The convex.json file in your project root controls how your Convex backend is built and deployed.

​
Basic structure

{
  "functions": "convex/",
  "node": {
    "externalPackages": [],
    "nodeVersion": "18"
  },
  "generateCommonJSApi": false,
  "codegen": {
    "staticApi": true,
    "staticDataModel": true
  }
}

​
Configuration options

​
functions
string
default:"convex/"
Directory containing your Convex functions.Relative to your project root. Must end with a trailing slash.
​
node.externalPackages
string[]
default:[]
List of npm packages to bundle as external dependencies.Packages listed here are loaded at runtime rather than bundled. This is required for packages that use Node.js native modules or dynamic imports.Example:
{
  "node": {
    "externalPackages": ["sharp", "@node-rs/argon2"]
  }
}
​
node.nodeVersion
string
Node.js version to use in the runtime environment.Supported versions: "18", "20"If not specified, uses the latest LTS version.
​
generateCommonJSApi
boolean
default:false
Whether to generate a CommonJS API in convex/_generated/.Set to true if you need to import generated code from CommonJS modules.
​
codegen.staticApi
boolean
default:true
Generate static type-safe API helpers in convex/_generated/api.ts.Provides auto-completion and type-checking for function references.
​
codegen.staticDataModel
boolean
default:true
Generate static type definitions for your data model in convex/_generated/dataModel.d.ts.Infers types from your schema definition.
​
codegen.fileType
string
default:"ts"
File type for generated code.Choices: "ts", "js/dts"
  • "ts" - Generate TypeScript files
  • "js/dts" - Generate JavaScript with separate type definition files
​
bundler.includeSourcesContent
boolean
default:false
Include source code content in generated source maps.Useful for debugging in production, but increases bundle size.
​
typescriptCompiler
string
TypeScript compiler to use for checking component implementations.Choices: "tsc", "swc"

​
WorkOS AuthKit configuration

​
authKit
object
Configuration for WorkOS AuthKit integration.Example:
{
  "authKit": {
    "dev": {
      "configure": {
        "redirectUris": ["http://localhost:3000/auth/callback"],
        "appHomepageUrl": "http://localhost:3000"
      }
    },
    "prod": {
      "configure": {
        "redirectUris": ["https://example.com/auth/callback"],
        "appHomepageUrl": "https://example.com"
      }
    }
  }
}

​
Environment-specific configuration

Configure different settings for development, preview, and production environments.

​
Development environment

Configuration for local development and dev deployments: 
{
  "authKit": {
    "dev": {
      "environmentType": "development",
      "configure": {
        "redirectUris": ["http://localhost:3000/callback"],
        "corsOrigins": ["http://localhost:3000"]
      }
    }
  }
}

​
Preview environment

Configuration for preview deployments: 
{
  "authKit": {
    "preview": {
      "environmentType": "staging",
      "configure": {
        "redirectUris": ["https://preview.example.com/callback"]
      }
    }
  }
}

​
Production environment

Configuration for production deployments: 
{
  "authKit": {
    "prod": {
      "environmentType": "production",
      "configure": {
        "redirectUris": ["https://example.com/callback"],
        "appHomepageUrl": "https://example.com"
      }
    }
  }
}

​
Runtime environment variables

Access environment variables in your Convex functions using process.env: 
// In a Convex function
export const myQuery = query(async (ctx) => {
  const apiKey = process.env.API_KEY;
  // Use the API key...
});
Set environment variables using the CLI: 
npx convex env set API_KEY "your-api-key"
See the env command documentation for more details.

​
Node.js external packages

Some npm packages require special handling:

​
Native modules

Packages with native Node.js modules must be marked as external: 
{
  "node": {
    "externalPackages": ["sharp", "@node-rs/bcrypt"]
  }
}

​
Dynamic imports

Packages that use dynamic imports at runtime: 
{
  "node": {
    "externalPackages": ["openai", "@langchain/core"]
  }
}

​
Best practices

  1. Version control - Commit convex.json to version control
  2. Minimal externals - Only mark packages as external when necessary
  3. Type safety - Keep staticApi and staticDataModel enabled
  4. Node version - Explicitly specify nodeVersion for consistency
  5. Environment separation - Use different configurations for dev, preview, and prod

​
Validation

The CLI validates convex.json on each deployment. Common errors:
  • Invalid JSON syntax
  • Unknown configuration keys
  • Invalid values for known keys
  • Missing required fields
Run npx convex dev --once to validate your configuration without deploying.

Build docs developers (and LLMs) love

Get started for freeTalk to us