Configuration

Learn how to configure the Nuxt SDK module.

The Nuxt SDK is configured through the croct key in your nuxt.config.ts file. Here is a basic example that enables debug mode:

export default defineNuxtConfig({  modules: ['@croct/plug-nuxt'],  croct: {    appId: '00000000-0000-0000-0000-000000000000',    debug: true,  },})

All module options can also be set through environment variables.

Module options

The following options are available under the croct key:

appId
string

The Application ID in the form of a UUID.

You can find this ID on the Integration page of your application.

debug(optional)
boolean

Whether to enable debug mode.

When enabled, the SDK logs additional information to the console to help you debug your application.

Default:false
test(optional)
boolean

Whether to enable test mode.

When enabled, the SDK uses a mock event transport layer to simulate successful transmission, which is useful for testing.

Default:false
defaultPreferredLocale(optional)
string

The default preferred locale for fetching content, like en-us or pt-br.

This value determines the default locale used by the SDK when no locale is specified.

defaultFetchTimeout(optional)
number

The default timeout for fetch requests in milliseconds.

This value determines how long the SDK waits for a response before timing out.

baseEndpointUrl(optional)
string

The base URL for API calls.

This option lets you override the default API base URL, which is useful for testing purposes.

See Integration testing for more information.

Default:https://api.croct.io
disableUserTokenAuthentication(optional)
boolean

Whether to disable token-based user authentication.

By default, the SDK uses tokens to authenticate users for enhanced security.

Default:false
tokenDuration(optional)
number

The duration of the user token in seconds.

This value determines how long the user token is valid before the SDK generates a new token.

By default, the token is valid for 24 hours.

Default:86400
userIdResolver(optional)
string

The path to a module that exports a function to resolve the user ID for each request.

For example, to read the user ID from a session cookie:

nuxt.config.ts
export default defineNuxtConfig({  croct: {    userIdResolver: './croct/resolveUserId',  },})

The module must export a default function that receives an H3 event and returns the user ID as a string, or null for anonymous users:

croct/resolveUserId.ts
export default event => getCookie(event, 'session-user') ?? null;

This keeps the Croct token in sync with your authentication system automatically. See Data collection for a complete example.

localeResolver(optional)
string

The path to a module that exports a function to determine the preferred locale for each request.

For example, to resolve the locale from the Accept-Language header:

nuxt.config.ts
export default defineNuxtConfig({  croct: {    localeResolver: './croct/resolveLocale',  },})

The module must export a default function that receives an H3 event and returns a locale string, or null to use the default:

croct/resolveLocale.ts
export default event => getHeader(event, 'accept-language')?.split(',')[0] ?? null;

This is useful for websites that localize content based on the URL, subdomain, headers, or cookies.

urlSanitizer(optional)
string

The path to a module that exports a function to sanitize URLs before tracking.

For example, to strip sensitive query parameters:

nuxt.config.ts
export default defineNuxtConfig({  croct: {    urlSanitizer: './croct/sanitizeUrl',  },})

The module must export a default function that receives a URL string and returns a URL object with sensitive parameters removed:

croct/sanitizeUrl.ts
export default url => {  const sanitized = new URL(url);  sanitized.searchParams.delete('token');
  return sanitized;};

This prevents sensitive data like tokens or emails from being sent in tracked page URLs.

Cookie configuration for identity management.