Skip to main content

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
  • "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
}

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.

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:

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