Feature Flags Guide

This document explains how to use feature flags to configure your Gully Sports application.

Overview

Feature flags allow you to enable or disable specific features of the application without changing code. This is useful for:

• Running the app in different modes (e.g., shop-only)
• A/B testing features
• Gradually rolling out new functionality
• Creating specialized deployments for different business needs

Configuration

Feature flags are configured using environment variables in your .env.local file.

Lane Rental Feature

Environment Variable: NEXT_PUBLIC_ENABLE_LANE_RENTAL

Default Value: false (disabled)

Description: Controls all lane rental and booking functionality throughout the application.

To Enable Lane Rentals:

NEXT_PUBLIC_ENABLE_LANE_RENTAL=true

To Disable Lane Rentals (Shop-Only Mode):

NEXT_PUBLIC_ENABLE_LANE_RENTAL=false

Or simply omit the variable from your .env.local file.

Application Modes

1. Shop-Only Mode (Default)

Configuration:

# Lane rental disabled (default)
# NEXT_PUBLIC_ENABLE_LANE_RENTAL=false

Features Available:

• ✅ Product shop
• ✅ Shopping cart
• ✅ Order management
• ✅ Inventory management (admin)
• ❌ Lane bookings
• ❌ Lane management (admin)

Perfect For:

• Retail-only businesses
• E-commerce focused deployments
• Sports equipment stores without facilities

2. Full Sports Facility Mode

Configuration:

NEXT_PUBLIC_ENABLE_LANE_RENTAL=true

Features Available:

• ✅ Product shop
• ✅ Shopping cart
• ✅ Order management
• ✅ Inventory management (admin)
• ✅ Lane bookings
• ✅ Lane management (admin)

Perfect For:

• Sports facilities with both rentals and shop
• Cricket grounds with equipment sales
• Multi-service sports businesses

What Changes When Features Are Toggled

When Lane Rental is Disabled

Homepage Changes:

• App title becomes "Gully Sports Shop"
• Description focuses on equipment and refreshments only
• "Book a Lane" button is hidden
• "Shop Equipment" becomes the primary CTA
• Lane rental feature card is hidden

Navigation Changes:

• "Book Lanes" link removed from header
• Mobile menu updated accordingly

Admin Dashboard Changes:

• "Bookings" section hidden
• "Lane Management" section hidden
• Simplified navigation for shop management only

When Lane Rental is Enabled

• Full feature set is available
• All navigation items visible
• Complete admin dashboard with lane and booking management

Implementation Details

Feature Flag System

The feature flag system is centralized in /src/utils/featureFlags.ts:

export const FEATURES = {
  LANE_RENTAL: process.env.NEXT_PUBLIC_ENABLE_LANE_RENTAL === "true",
  SHOP: process.env.NEXT_PUBLIC_ENABLE_SHOP !== "false",
} as const;

Helper Functions

isFeatureEnabled(feature) Check if a specific feature is enabled:

import { isFeatureEnabled } from "@/utils/featureFlags";

if (isFeatureEnabled("LANE_RENTAL")) {
  // Show lane rental features
}

getPaymentProvider() Get the current payment provider:

import { getPaymentProvider } from "@/utils/featureFlags";

const provider = getPaymentProvider(); // 'intuit' or 'square'

isPayPalEnabled() Check if PayPal payment method is enabled:

import { isPayPalEnabled } from "@/utils/featureFlags";

if (isPayPalEnabled()) {
  // PayPal is available (Intuit only)
}

isVenmoEnabled() Check if Venmo payment method is enabled:

import { isVenmoEnabled } from "@/utils/featureFlags";

if (isVenmoEnabled()) {
  // Venmo is available (Intuit only)
}

isPayPalVenmoEnabled() (Deprecated) Check if PayPal OR Venmo payment methods are enabled:

import { isPayPalVenmoEnabled } from "@/utils/featureFlags";

if (isPayPalVenmoEnabled()) {
  // Either PayPal or Venmo are available (Intuit only)
}

Deprecated

Use isPayPalEnabled() and isVenmoEnabled() instead for more granular control.

getIntuitEnabledPaymentMethods() Get array of enabled payment methods for Intuit provider:

import { getIntuitEnabledPaymentMethods } from "@/utils/featureFlags";

const methods = getIntuitEnabledPaymentMethods();
// Returns array based on enabled features:
// - ['card', 'bank', 'applePay'] - if both PayPal and Venmo are disabled
// - ['card', 'bank', 'applePay', 'payPal'] - if only PayPal is enabled
// - ['card', 'bank', 'applePay', 'venmo'] - if only Venmo is enabled
// - ['card', 'bank', 'applePay', 'payPal', 'venmo'] - if both are enabled

getAppName() Get the application name based on enabled features:

import { getAppName } from "@/utils/featureFlags";

const appName = getAppName(); // "Gully Sports" or "Gully Sports Shop"

getAppDescription() Get the application description based on enabled features:

import { getAppDescription } from "@/utils/featureFlags";

const description = getAppDescription();

Modified Components

The following components have been updated to support feature flags:

1. /src/components/Header.tsx

   • Conditionally shows navigation items based on features
   • Filters admin navigation based on enabled features

2. /src/app/page.tsx

   • Dynamic homepage content based on enabled features
   • Adaptive metadata and SEO

3. /src/components/AdminLayout.tsx

   • Conditional sidebar navigation
   • Feature-specific admin sections

Testing Different Modes

Test Shop-Only Mode

1. Edit your .env.local:

   NEXT_PUBLIC_ENABLE_LANE_RENTAL=false

2. Restart your development server:

   npm run dev

3. Visit http://localhost:3000 and verify:

   • No "Book Lanes" link in navigation
   • Homepage shows shop-focused content
   • Admin dashboard only shows inventory and orders

Test Full Mode

1. Edit your .env.local:

   NEXT_PUBLIC_ENABLE_LANE_RENTAL=true

2. Restart your development server

3. Verify all features are available

Deployment

Vercel

Add the environment variable in your Vercel project settings:

1. Go to your project settings
2. Navigate to "Environment Variables"
3. Add NEXT_PUBLIC_ENABLE_LANE_RENTAL with value true or false
4. Redeploy your application

Other Platforms

Set the environment variable according to your platform's documentation:

• Netlify: Site settings → Environment variables
• Railway: Project settings → Variables
• DigitalOcean: App settings → Environment variables

Payment Provider Configuration

Payment Provider Selection

Environment Variable: NEXT_PUBLIC_PAYMENT_PROVIDER

Default Value: intuit

Description: Controls which payment provider is used for processing payments.

Available Options:

• intuit - Use Intuit QuickBooks Payments (supports cards, ACH, PayPal, Venmo, Apple Pay)
• square - Use Square Payments (supports cards, Apple Pay, Google Pay, gift cards)

To Use Square Payments:

NEXT_PUBLIC_PAYMENT_PROVIDER=square

To Use Intuit Payments:

NEXT_PUBLIC_PAYMENT_PROVIDER=intuit

Or simply omit the variable to default to Intuit.

Documentation: See Square Setup Guide for detailed Square setup instructions.

PayPal and Venmo Feature Flags (Intuit Only)

Environment Variables:

• NEXT_PUBLIC_ENABLE_PAYPAL
• NEXT_PUBLIC_ENABLE_VENMO

Default Value: false (disabled for both)

Description: Controls whether PayPal and Venmo payment methods are available in the Intuit checkout form. These flags work independently and only apply when using the Intuit payment provider.

note

These feature flags are useful for:

• Enabling/disabling PayPal and Venmo independently
• Troubleshooting specific payment method integration issues
• Gradually rolling out PayPal or Venmo support separately
• Running A/B tests with different payment methods
• Offering different payment options based on deployment environment

To Enable Both PayPal and Venmo:

NEXT_PUBLIC_PAYMENT_PROVIDER=intuit
NEXT_PUBLIC_ENABLE_PAYPAL=true
NEXT_PUBLIC_ENABLE_VENMO=true

To Enable Only PayPal:

NEXT_PUBLIC_PAYMENT_PROVIDER=intuit
NEXT_PUBLIC_ENABLE_PAYPAL=true
NEXT_PUBLIC_ENABLE_VENMO=false  # or omit

To Enable Only Venmo:

NEXT_PUBLIC_PAYMENT_PROVIDER=intuit
NEXT_PUBLIC_ENABLE_PAYPAL=false  # or omit
NEXT_PUBLIC_ENABLE_VENMO=true

To Disable Both (Cards, ACH, and Apple Pay only):

NEXT_PUBLIC_PAYMENT_PROVIDER=intuit
# Omit both variables or set to false
NEXT_PUBLIC_ENABLE_PAYPAL=false
NEXT_PUBLIC_ENABLE_VENMO=false

Available Payment Methods by Configuration:

When Both PayPal and Venmo are ENABLED:

• ✅ Credit/Debit Cards
• ✅ ACH Bank Transfer
• ✅ Apple Pay
• ✅ PayPal
• ✅ Venmo

When Only PayPal is ENABLED:

• ✅ Credit/Debit Cards
• ✅ ACH Bank Transfer
• ✅ Apple Pay
• ✅ PayPal
• ❌ Venmo

When Only Venmo is ENABLED:

• ✅ Credit/Debit Cards
• ✅ ACH Bank Transfer
• ✅ Apple Pay
• ❌ PayPal
• ✅ Venmo

When Both are DISABLED:

• ✅ Credit/Debit Cards
• ✅ ACH Bank Transfer
• ✅ Apple Pay
• ❌ PayPal
• ❌ Venmo

warning

These flags have no effect when NEXT_PUBLIC_PAYMENT_PROVIDER=square. PayPal and Venmo are only available through Intuit.

What Changes When You Switch Providers

The application automatically adapts:

• ✅ Checkout Form - Loads the appropriate payment SDK (Intuit or Square)
• ✅ Payment Methods - Shows available methods for the selected provider
• ✅ API Endpoints - Routes payments to the correct processor
• ✅ Branding - Updates "Powered by" text and logos
• ✅ Backend Processing - Uses the appropriate payment API

Note: All environment variables and credentials must be configured for the selected provider. See respective documentation:

• Intuit: OAuth Setup Guide
• Square: Square Setup Guide

Future Feature Flags

Shop Feature (Planned)

Environment Variable: NEXT_PUBLIC_ENABLE_SHOP

Description: Will control shop and e-commerce functionality.

Current Status: Always enabled (default behavior)

This will allow for a "booking-only" mode in the future.

Best Practices

1. Always restart your development server after changing environment variables
2. Document feature flags in your deployment configurations
3. Test both modes before deploying to production
4. Keep feature flags simple - avoid complex combinations
5. Use feature flags for major features - not for minor UI tweaks

Troubleshooting

Feature flag not working

1. Verify the environment variable is set correctly in .env.local
2. Restart your development server (npm run dev)
3. Check that you're using the correct variable name (must start with NEXT_PUBLIC_)
4. Clear Next.js cache: rm -rf .next

Features showing when they shouldn't

1. Check the environment variable value is exactly "true" (string)
2. Verify there are no extra spaces or quotes in .env.local
3. Check browser cache - do a hard refresh (Cmd+Shift+R or Ctrl+Shift+R)

Admin dashboard showing wrong sections

• Ensure the FEATURES object is properly imported in AdminLayout.tsx
• Verify the conditional rendering logic in the component

Support

For issues or questions about feature flags:

• Create an issue in the repository
• Check the main README.md for general setup instructions
• Review the code in /src/utils/featureFlags.ts