Environment Configuration

Environment Configuration

This guide explains how to configure different environments for development, testing, and production in your jsPsych experiment. Understanding environment configuration helps you maintain a smooth workflow from development to deployment.

Environment Overview

The template supports three primary environments:

1. Development: Local development with mock database
2. Testing: Using real Firebase services but in debug mode
3. Production: Live experiment collecting real participant data

Configuration Options

The template uses several mechanisms to control environment behavior:

1. AppConfig Settings

The main configuration is in hosting/src/appConfig.ts:

// Enable detailed logging and debug features
export const debuggingMode: boolean = true

// Use mock database instead of Firestore
export const simulateMockDatabase: boolean = true

// Your contact information
export const contactInfo: Record<'name' | 'email', string> = {
  name: 'YOUR NAME',
  email: 'YOUR@EMAIL',
}

These settings determine:

• Whether to show debug information in the console
• Whether to use the mock database or real Firestore
• Contact information displayed to participants

2. URL Parameters

The application can be controlled via URL parameters, which override the settings in appConfig.ts:

• ?debug=true or ?debug=false - Override debug setting
• ?mock=true or ?mock=false - Override mock database setting

For example:

• http://localhost:5173/?debug=true&mock=false - Enable debugging but use real Firestore
• https://your-app.web.app/?debug=false - Disable debugging on a deployed app

3. Build Modes

The template provides different build commands for development and production:

# Development build with minimal optimization
yarn build:dev

# Production build with full optimization and checks
yarn build:prod

These affect:

• Code optimization level
• Source maps
• Type checking strictness
• Error handling

4. NODE_ENV Variable

The NODE_ENV environment variable is set automatically by the build scripts:

• NODE_ENV=development for development
• NODE_ENV=production for production

This affects:

• Bundler behavior
• Library optimizations
• React's behavior (if you add React)

Environment Setup Guide

Development Environment

Optimal for active development with rapid iteration:

1. Configure appConfig.ts:

   export const debuggingMode = true
   export const simulateMockDatabase = true

2. Use the development server:

   yarn dev

3. Work with mock database:

   • Data is stored in memory
   • View data in Debug Panel
   • No Firebase configuration needed yet

Testing Environment

For testing with real Firebase services:

1. Complete the Firebase setup as described in Firebase Setup

2. Configure appConfig.ts or use URL parameters:

   export const debuggingMode = true
   export const simulateMockDatabase = false

3. Run the development server:

   yarn dev

4. How it works:

   • Data is stored in the -dbug collections (e.g., exptData-dbug)
   • Debug Panel is still available
   • Detailed logging in console

Production Environment

For collecting real participant data:

1. Ensure Firebase is fully configured

2. For final deployment, build and deploy:

   yarn release

3. The release script:

   • Increases version number
   • Creates a git commit
   • Builds with NODE_ENV=production
   • Sets debuggingMode = false for the build
   • Deploys to Firebase

4. How it works:

   • Data is stored in main collections (e.g., exptData)
   • No debugging information is visible to participants
   • Optimized for performance

Database Collections by Environment

The template automatically uses different Firestore collections depending on the environment:

Collection Name	Environment	Description
exptData	Production	Participant data in production
exptData-dbug	Development/Testing	Test data with debugging enabled
sharedData	Production	Shared experiment configuration
sharedData-dbug	Development/Testing	Test shared configuration

This separation ensures that:

• Development data doesn't contaminate production data
• You can freely test without affecting real participants
• You can easily identify which data came from which environment

Environment Detection

The application uses several mechanisms to detect the current environment:

From URL

// From globalVariables.ts
function emulator(): boolean {
  /* Returns true if web app is running locally */
  return globalThis.location.hostname === 'localhost'
}

From Debug Mode

// From globalVariables.ts
export function debugging(): boolean {
  if (definitelyLive()) {
    return false
  }

  const urlParameters = getURLParams()

  if (Object.hasOwn(urlParameters, 'debug')) {
    try {
      const val = urlParameters.debug.toLowerCase()
      if (val === 'false') {
        return false
      }
    } catch (error) {
      console.error('debugging() :: urlParameters["debug"]', error)
    }
    return true
  }
  // ... more conditions
  return debug
}

Determining Collection Names

// From globalVariables.ts
export function getDocStr(docId: string): string {
  /* Appends "-dbug" to the FireStore docId if in debugging mode */
  const redirect = sandbox() || debugging()
  const dbstring = redirect ? '-dbug' : ''
  return `${docId}${dbstring}`
}

Multiple Firebase Projects

For more complex research projects, you might want separate Firebase projects for development and production:

Setting Up Multiple Projects

1. Create separate Firebase projects (e.g., "my-experiment-dev" and "my-experiment-prod")

2. Initialize multiple targets in .firebaserc:

   {
     "projects": {
       "default": "my-experiment-prod",
       "dev": "my-experiment-dev",
       "prod": "my-experiment-prod"
     }
   }

3. Create environment-specific credential files:

   • creds.dev.ts
   • creds.prod.ts

4. Use environment variables or build-time substitution to select the right credentials

Switching Between Projects

Use Firebase CLI to switch projects:

# Switch to development project
yarn firebase use dev

# Deploy to development
yarn deploy

# Switch to production project
yarn firebase use prod

# Deploy to production
yarn deploy

URL Parameter Reference

Parameter	Type	Description
debug	boolean	Enable/disable debug mode
mock	boolean	Use mock database instead of Firestore
PROLIFIC_PID	string	Prolific participant ID
STUDY_ID	string	Prolific study ID
SESSION_ID	string	Prolific session ID

Best Practices

1. Develop Locally First:

   • Use simulateMockDatabase = true while building your experiment
   • Only switch to Firestore when your experiment is stable

2. Test in All Environments:

   • Test with the mock database
   • Test with Firestore in debug mode
   • Test the production build before final deployment

3. Use Version Control:

   • Commit changes between major environment transitions
   • Use the release script for production deployments
   • Tag important releases in git

4. Guard Sensitive Operations:

   • Use environment checks for sensitive operations
   • Never expose admin credentials in the client
   • Use Firestore security rules as a defense in depth

5. Monitor Environment Variables:

   • Be aware of how URL parameters affect your experiment
   • Check console output to confirm the correct environment
   • Verify database connections in each environment