How to Use Environment Variables with Remotion: A Complete Guide

Access environment variables in Remotion using process.env.VAR_NAME from Node.js, with support for .env files in development and platform-specific injection in production.

Remotion, the React-based video creation framework by remotion-dev/remotion, relies on standard Node.js environment variable patterns to manage secrets, API keys, and configuration flags across local development and cloud deployments. Understanding how to use environment variables with Remotion ensures your video pipelines remain secure and portable between your machine and serverless platforms like Vercel or AWS Lambda.

How Remotion Reads Environment Variables

Remotion follows the conventional Node.js architecture where all environment variables flow through process.env. The framework does not use a custom configuration layer; instead, it reads values directly from the Node.js process at runtime.

According to the source code, Remotion core modules access process.env in several key locations:

• packages/studio/src/helpers/use-keybinding.ts – Reads KEYBOARD_SHORTCUTS_ENABLED to toggle UI features
• packages/renderer/src/set-props-and-env.ts – Handles default ports and Node environment detection
• packages/renderer/src/can-use-parallel-encoding.ts – Checks REMOTION_PARTITIONED_RENDERING for performance optimizations
• packages/serverless/src/handlers/renderer.ts – Accesses AWS credentials and runtime configuration in Lambda environments

All values arrive as strings, so the codebase consistently coerces booleans by comparing against 'true' or 'false' rather than parsing JSON.

Accessing Environment Variables in Remotion Code

Required Secrets and API Keys

When your Remotion composition requires external services like OpenAI, validate the variable early to provide clear error messages:

// packages/template-prompt-to-video/cli/cli.ts
const openAiKey = process.env.OPENAI_API_KEY;

if (!openAiKey) {
  throw new Error('Please set OPENAI_API_KEY in your environment.');
}

This pattern appears in the template-prompt-to-video CLI entry point, ensuring developers receive immediate feedback during local development rather than obscure runtime failures during rendering.

Optional Feature Toggles

Remotion uses environment variables to enable or disable features without code changes. The Studio's keyboard shortcuts demonstrate boolean coercion:

// packages/studio/src/helpers/use-keybinding.ts
export const areKeyboardShortcutsEnabled = () => {
  // undefined → true by default, set to "false" to disable
  return process.env.KEYBOARD_SHORTCUTS_ENABLED !== 'false';
};

This approach allows developers to disable shortcuts by setting KEYBOARD_SHORTCUTS_ENABLED=false while maintaining backward compatibility when the variable is undefined.

Platform-Specific Tokens

When deploying to Vercel using the official template, access the Blob store token:

// packages/template-vercel/src/app/api/render/render.ts
const token = process.env.BLOB_READ_WRITE_TOKEN;

if (!token) {
  // When running locally, copy the token from your Vercel dashboard
  console.warn('BLOB_READ_WRITE_TOKEN not set');
}

The template-vercel project expects this variable for serverless rendering workflows that persist frames to Vercel Blob storage.

Providing Defaults for Local Development

Always fall back to sensible defaults to ensure the application runs without configuration:

// packages/renderer/src/set-props-and-env.ts
const port = process.env.PORT ?? 3000;
const nodeEnv = process.env.NODE_ENV ?? 'development';

This pattern from the renderer package allows remotion studio to start on port 3000 automatically while respecting platform-assigned ports in production containers.

Configuring Environment Variables for Different Environments

Local Development with .env Files

Remotion template projects include .env.example files that document required variables. To configure local development:

1. Copy the example file to .env:

   cp packages/template-vercel/.env.example .env

2. Add your actual values to .env:

   BLOB_READ_WRITE_TOKEN=your_vercel_blob_token
   OPENAI_API_KEY=sk-your_openai_key

3. Ensure .env is ignored in .gitignore (already configured in Remotion templates).

The Remotion CLI automatically loads .env files via dotenv. For custom scripts, import the package at the top of your entry point:

import 'dotenv/config';

Production Deployment on Vercel, Netlify, and AWS Lambda

When deploying Remotion to serverless platforms, inject variables through the provider's dashboard rather than committing them:

• Vercel: Add BLOB_READ_WRITE_TOKEN and API keys in Project Settings → Environment Variables. The template-vercel handler automatically picks these up via process.env.

• Netlify: Configure variables in Site settings → Environment variables. Access them in Netlify Functions using the same process.env pattern.

• AWS Lambda: Set environment variables in the Lambda function configuration or via the Remotion Lambda CLI. The serverless handler in packages/serverless/src/handlers/renderer.ts reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and Remotion-specific configuration from the runtime environment.

Key Environment Variables in Remotion

The Remotion codebase recognizes several specific variables that control framework behavior:

Variable	Purpose	Default	Source Location
KEYBOARD_SHORTCUTS_ENABLED	Toggles Studio keyboard shortcuts	true (enabled)	packages/studio/src/helpers/use-keybinding.ts
REMOTION_PARTITIONED_RENDERING	Enables parallel encoding for faster renders	false	packages/renderer/src/can-use-parallel-encoding.ts
PORT	Development server port	3000	packages/renderer/src/set-props-and-env.ts
NODE_ENV	Build mode detection	development	packages/renderer/src/set-props-and-env.ts
BLOB_READ_WRITE_TOKEN	Vercel Blob storage access	Required for template	packages/template-vercel/src/app/api/render/render.ts
OPENAI_API_KEY	OpenAI API access for AI videos	Required for template	packages/template-prompt-to-video/cli/cli.ts
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	AWS credentials for Lambda/S3	Required for serverless	packages/serverless/src/handlers/renderer.ts

Best Practices for Managing Remotion Environment Variables

Follow these patterns established in the Remotion codebase to keep your video projects secure and maintainable:

• Never commit real secrets – Keep sensitive values out of Git by using .env.example as a template and ensuring .env is in .gitignore. The Remotion templates already configure this exclusion.

• Provide sensible defaults – Use the nullish coalescing operator (??) to fall back to safe values when variables are undefined, as seen in packages/renderer/src/set-props-and-env.ts with process.env.PORT ?? 3000.

• Validate required variables early – Throw explicit errors during application startup if critical secrets are missing. The template-prompt-to-video CLI demonstrates this by checking OPENAI_API_KEY before attempting API calls.

• Document every variable – Include descriptions in your project's README or .env.example file. The official Remotion templates provide inline comments showing exactly which services each key corresponds to.

• Use boolean string coercion – Store feature flags as strings ('true' or 'false') and compare them directly in code rather than parsing JSON, following the pattern in packages/studio/src/helpers/use-keybinding.ts.

Summary

• Remotion uses standard Node.js process.env to access environment variables, with no custom configuration layer.
• The framework automatically loads .env files in development, while production deployments rely on platform-specific injection via Vercel, Netlify, or AWS Lambda dashboards.
• Key implementation files include packages/renderer/src/set-props-and-env.ts for defaults and packages/studio/src/helpers/use-keybinding.ts for feature toggles.
• Always validate required secrets early, provide defaults for optional variables, and never commit sensitive values to source control.

Frequently Asked Questions

How do I load a .env file in Remotion?

The Remotion CLI automatically loads .env files using dotenv when you run commands like remotion render or remotion studio. If you are writing a custom Node.js script outside the CLI, import dotenv/config at the top of your entry file:

import 'dotenv/config';

This ensures process.env contains your variables before Remotion components execute.

Can I use environment variables in the Remotion Studio?

Yes. When you run npx remotion studio, the CLI loads your .env file into the Node.js process. Your React components can access these values via process.env during the server-side rendering phase. However, remember that environment variables are not automatically exposed to the browser bundle unless you explicitly pass them as props to your compositions or access them during the render lifecycle.

How do I handle sensitive API keys in Remotion Lambda?

When deploying to AWS Lambda using Remotion's serverless packages, set sensitive keys like AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the Lambda function's environment configuration via the AWS Console or Infrastructure-as-Code tools. The serverless handler in packages/serverless/src/handlers/renderer.ts reads these directly from process.env. Never commit these credentials to your Git repository; instead, inject them during deployment or use IAM roles where possible.

What is the REMOTION_PARTITIONED_RENDERING variable used for?

REMOTION_PARTITIONED_RENDERING is a performance optimization flag that enables parallel encoding during video rendering. When set to 'true', Remotion splits the rendering process across multiple CPU cores to speed up exports, as implemented in packages/renderer/src/can-use-parallel-encoding.ts. This is particularly useful for high-resolution or long-duration videos, though it requires sufficient system resources. By default, this feature is disabled (false) to ensure compatibility with resource-constrained environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}