Environment Configuration

Relevant source files

• .env.development
• .env.production
• packages/excalidraw/vite-env.d.ts

Purpose and Scope

This document describes the environment configuration system used by the Excalidraw application, focusing on the .env.development and .env.production files and the VITE_APP_* environment variables that control backend service URLs, feature flags, and debugging options. This configuration applies specifically to the excalidraw-app hosted application.

For backend service integration details, see Backend Service Configuration. For analytics-specific configuration, see Analytics and Monitoring. For PWA configuration, see PWA and Offline Support.

Environment File Structure

Excalidraw uses Vite's environment variable system with separate configuration files for different deployment contexts. The environment files are located at the repository root and follow Vite's standard naming conventions.

Sources: .env.development1-56 .env.production1-35

File Loading Order

Vite loads environment files in the following priority order (highest priority first):

1. .env.[mode].local (e.g., .env.development.local) - gitignored
2. .env.local - gitignored for all modes except test
3. .env.[mode] (e.g., .env.development)
4. .env - base configuration (not used in Excalidraw)

Variables defined in files with higher priority override those in lower priority files. The .env.local files are explicitly gitignored to prevent committing sensitive configuration.

Sources: .env.development19-20

Variable Naming Convention

All environment variables accessible in the application must be prefixed with VITE_APP_ to be embedded in the client-side bundle. This is a Vite security feature that prevents accidentally exposing server-side environment variables to the client.

Sources: .env.development3-15 packages/excalidraw/vite-env.d.ts5-56

Environment Variable Categories

Backend Service URLs

These variables configure the URLs for external backend services used by the application.

Variable	Development Value	Production Value	Purpose
VITE_APP_BACKEND_V2_GET_URL	https://json-dev.excalidraw.com/api/v2/	https://json.excalidraw.com/api/v2/	Scene retrieval endpoint
VITE_APP_BACKEND_V2_POST_URL	https://json-dev.excalidraw.com/api/v2/post/	https://json.excalidraw.com/api/v2/post/	Scene persistence endpoint
VITE_APP_LIBRARY_URL	https://libraries.excalidraw.com	https://libraries.excalidraw.com	Public library frontend
VITE_APP_LIBRARY_BACKEND	https://us-central1-excalidraw-room-persistence.cloudfunctions.net/libraries	(same)	Library API endpoint
VITE_APP_WS_SERVER_URL	http://localhost:3002	https://oss-collab.excalidraw.com	WebSocket server for collaboration
VITE_APP_AI_BACKEND	http://localhost:3015	https://oss-ai.excalidraw.com	AI feature backend

Sources: .env.development3-15 .env.production3-15

Excalidraw Plus Integration

These variables configure integration with the Excalidraw Plus premium service.

Variable	Development Value	Production Value	Purpose
VITE_APP_PLUS_LP	https://plus.excalidraw.com	https://plus.excalidraw.com	Plus landing page
VITE_APP_PLUS_APP	http://localhost:3000	https://app.excalidraw.com	Plus application URL
VITE_APP_PLUS_EXPORT_PUBLIC_KEY	(RSA public key)	(RSA public key)	Public key for export encryption

Sources: .env.development12-52 .env.production9-27

Firebase Configuration

Firebase configuration is provided as a JSON string containing the Firebase project credentials.

• Development: Uses excalidraw-oss-dev project
• Production: Uses excalidraw-room-persistence project

Sources: .env.development17 .env.production17

Development-Specific Settings

These variables control development server behavior and debugging features.

Variable	Default Value	Purpose
VITE_APP_PORT	3000	Development server port
VITE_APP_DEV_DISABLE_LIVE_RELOAD	(empty)	Disable HMR/live reload (useful for debugging Service Workers)
FAST_REFRESH	false	React Fast Refresh setting
VITE_APP_ENABLE_ESLINT	true (dev), false (prod)	Enable ESLint in dev server
VITE_APP_ENABLE_PWA	false	Enable PWA in development mode

Sources: .env.development22-44 .env.production32-33

Debug Flags

Debug flags enable additional debugging features during development.

Variable	Default Value	Purpose
VITE_APP_DEBUG_ENABLE_TEXT_CONTAINER_BOUNDING_BOX	(empty)	Show bounding boxes for text containers
VITE_APP_COLLAPSE_OVERLAY	true (dev), false (prod)	Collapse the debug overlay by default
VITE_APP_DISABLE_PREVENT_UNLOAD	(empty)	Disable the "unsaved changes" dialog

Sources: .env.development34-55 .env.production30-31

Feature Flags

Feature flags control the availability of application features.

Variable	Default Value	Purpose
VITE_APP_ENABLE_TRACKING	true (dev), false (prod)	Enable analytics tracking

Sources: .env.development25 .env.production19

TypeScript Type Definitions

The ImportMetaEnv interface in packages/excalidraw/vite-env.d.ts5-56 provides TypeScript type definitions for all environment variables, enabling type-safe access throughout the codebase.

Sources: packages/excalidraw/vite-env.d.ts5-60

Key Type Definitions

All environment variables are typed as string in the ImportMetaEnv interface. Notable type definitions include:

• Backend URLs: VITE_APP_BACKEND_V2_GET_URL, VITE_APP_BACKEND_V2_POST_URL, VITE_APP_WS_SERVER_URL, VITE_APP_AI_BACKEND
• Firebase: VITE_APP_FIREBASE_CONFIG (JSON string)
• Debug flags: VITE_APP_DEBUG_ENABLE_TEXT_CONTAINER_BOUNDING_BOX, VITE_APP_COLLAPSE_OVERLAY
• Build metadata: PKG_NAME, PKG_VERSION, MODE, DEV, PROD

Sources: packages/excalidraw/vite-env.d.ts6-56

Accessing Environment Variables in Code

Environment variables are accessed via import.meta.env throughout the application:

The TypeScript compiler ensures type safety by validating all environment variable accesses against the ImportMetaEnv interface.

Sources: packages/excalidraw/vite-env.d.ts58-60

Local Configuration Overrides

Developers can create .env.local or .env.development.local files to override default values without modifying tracked files. Common use cases include:

1. Pointing to local backend services:

2. Disabling features during debugging:

3. Enabling debug features:

These files are gitignored and should never be committed to version control.

Sources: .env.development19-55

Environment-Specific Configuration Matrix

The following table summarizes key differences between development and production configurations:

Aspect	Development	Production	Rationale
Backend V2 URL	json-dev.excalidraw.com	json.excalidraw.com	Separate dev/prod data stores
WebSocket Server	localhost:3002	oss-collab.excalidraw.com	Local server for development
AI Backend	localhost:3015	oss-ai.excalidraw.com	Local AI service for testing
Plus App URL	localhost:3000	app.excalidraw.com	Local dev environment
Firebase Project	excalidraw-oss-dev	excalidraw-room-persistence	Separate dev/prod databases
Tracking	true	false	Analytics enabled in dev for testing
ESLint	true	false	Development-time linting only
Debug Flags	Enabled	false	Debugging features in development only

Sources: .env.development3-44 .env.production3-33

Mode Variable

The MODE variable explicitly identifies the environment context:

• .env.development: MODE="development"
• .env.production: MODE="production"

This variable is used throughout the build process and can be accessed via import.meta.env.MODE at runtime to conditionally enable environment-specific behavior.

Sources: .env.development1 .env.production1