Query Parameters and External Values in GraphQL Loaders

Simple Parameter Handling (Using params)

When your query only needs values from params, use direct parameter definition in routes.json:

{
  "queries": {
    "GetFilteredProjects": "{filter: {id: params.id, orgName: params.orgName}}",
    "GetTeamMembers": "{teamId: params.teamId, pageSize: 10}"
  }
}

Query Parameter Generator

Use Query Parameter Generator when you need to incorporate values from external sources, imports, or complex computations.

When to Use Query Parameter Generator

1. External Configuration Values

import { dimensions } from './dimension.js';
import { DEFAULT_PAGE_SIZE } from './constants';
import { calculateDateRange } from './utils';

export const queryParamsGenerator = (params) => ({
    teamSearch: {
        filters: {
            teamId: params.teamId,
            dimensions: dimensions, // From import
            pageSize: DEFAULT_PAGE_SIZE, // From constants
            dateRange: calculateDateRange(params.period) // From utility function
        }
    }
});

2. Environment-Specific Values

import { environmentConfig } from './config';

export const queryParamsGenerator = (params) => ({
    search: {
        orgId: params.orgId,
        region: environmentConfig.defaultRegion,
        features: environmentConfig.enabledFeatures
    }
});

3. Computed or Transformed Values

import { getRolePermissions } from './permissions';
import { getDefaultFilters } from './filters';

export const queryParamsGenerator = (params) => {
    const rolePermissions = getRolePermissions(params.role);
    const defaultFilters = getDefaultFilters();

    return {
        userQuery: {
            id: params.userId,
            permissions: rolePermissions,
            filters: {
                ...defaultFilters,
                ...params.filters
            }
        }
    };
};

Example Implementation

// dimensions.ts
export const dimensions = {
    layout: 'horizontal',
    maxItems: 50,
    sortOrder: 'asc'
};

// searchConfig.ts
export const searchDefaults = {
    pageSize: 20,
    sortField: 'createdAt',
    includeArchived: false
};

// queryParamGenerator.ts
import { dimensions } from './dimensions';
import { searchDefaults } from './searchConfig';
import { formatDateRange } from './utils';

export const queryParamsGenerator = (params) => ({
    searchParams: {
        basic: {
            query: params.searchTerm,
            pageSize: searchDefaults.pageSize
        },
        advanced: {
            dimensions: dimensions,
            dateRange: formatDateRange(params.startDate, params.endDate),
            sorting: {
                field: searchDefaults.sortField,
                order: dimensions.sortOrder
            }
        }
    }
});

// Component Usage
const SearchComponent = () => {
    const params = {
        searchTerm: 'example',
        startDate: '2024-01-01',
        endDate: '2024-12-31'
    };

    const SearchQuery = useCustomQuery({
        variables: queryParamsGenerator(params).searchParams,
        fetchPolicy: 'cache-only'
    });

    return (
        <Suspense fallback={<Spinner />}>
            <Await resolve={SearchQuery}>
                {(data) => <SearchResults data={data} />}
            </Await>
        </Suspense>
    );
};

routes.json Integration

When using query parameter generators, you reference them in routes.json:

{
  "queries": {
    "SearchDocument": "queryParamsGenerator(params).searchParams"
  }
}

Generated Loader

export const defaultServerLoader = async ({ context, params, _dataContext = {} }) => {
    const { apolloClient: client } = context;
    
    // System automatically handles the query parameter generation
    const searchResults = client.query({
        query: SearchDocument,
        variables: queryParamsGenerator(params).searchParams,
        fetchPolicy: __SERVER__ ? 'network-only' : 'cache-first',
    });

    return {
        data: {
            searchResults
        }
    };
};

Comparison: Direct Params vs Query Parameter Generator

Direct Params (Simple Cases)

{
  "queries": {
    "GetTeamMembers": "{teamId: params.teamId, pageSize: 10}"
  }
}

✓ Good for: Simple parameter passing from URL/route parameters

Query Parameter Generator (Complex Cases)

export const queryParamsGenerator = (params) => ({
    teamMembers: {
        teamId: params.teamId,
        pageSize: environmentConfig.pageSize,
        permissions: getRolePermissions(params.role),
        filters: getTeamFilters(environmentConfig.region)
    }
});

✓ Good for:

• Including imported values
• Environment-specific configuration
• Computed or transformed values
• Complex parameter structures with external dependencies

Back to Index | Previous: Generated Data Loaders | Next: Resource Loaders