# 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:

```ts
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](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](https://app.croct.com/redirect/organizations/-organization-/workspaces/-workspace-/applications/-application-/integration) of your application.

- `debug`: `boolean` (optional) (default: false)

  Whether to enable [debug mode](/reference/sdk/nuxt/troubleshooting/debugging).

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

- `test`: `boolean` (optional) (default: false)

  Whether to enable [test mode](/reference/sdk/nuxt/testing/unit-testing).

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

- `defaultPreferredLocale`: `string` (optional)

  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`: `number` (optional)

  The default timeout for fetch requests in milliseconds.

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

- `baseEndpointUrl`: `string` (optional) (default: https\://api.croct.io)

  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](/reference/sdk/nuxt/testing/integration-testing) for more information.

- `disableUserTokenAuthentication`: `boolean` (optional) (default: false)

  Whether to disable token-based user authentication.

  By default, the SDK uses [tokens](/explanation/application/signed-tokens) to authenticate users for enhanced security.

- `tokenDuration`: `number` (optional) (default: 86400)

  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.

- `userIdResolver`: `string` (optional)

  The path to a module that exports a [function](types/user-id-resolver) to resolve the user ID for each request.

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

  **nuxt.config.ts**

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

  The module must export a default function that receives an [H3 event](https://h3.unjs.io/guide/event) and returns the user ID as a string, or `null` for anonymous users:

  **croct/resolveUserId.ts**

  ```ts
  export default event => getCookie(event, 'session-user') ?? null;
  ```

  This keeps the Croct token in sync with your authentication system automatically. See [Data collection](/reference/sdk/nuxt/data-collection#user-identity) for a complete example.

- `localeResolver`: `string` (optional)

  The path to a module that exports a [function](types/locale-resolver) to determine the preferred locale for each request.

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

  **nuxt.config.ts**

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

  The module must export a default function that receives an [H3 event](https://h3.unjs.io/guide/event) and returns a locale string, or `null` to use the default:

  **croct/resolveLocale.ts**

  ```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.

- `credentialsResolver`: `string` (optional)

  The path to a module that exports a [function](types/credentials-resolver) to resolve the application ID and API key for each request.

  This enables multi-tenancy, where a single application serves multiple tenants, each with its own [Croct application](/explanation/application/overview). The resolved application ID reaches the browser, while the API key stays on the server.

  For example, to resolve the credentials from the request host:

  **nuxt.config.ts**

  ```ts
  export default defineNuxtConfig({
    croct: {
      credentialsResolver: './croct/resolveCredentials',
    },
  })
  ```

  The module must export a default function that receives an [H3 event](https://h3.unjs.io/guide/event) and returns the credentials, or `null` to use the configured values:

  **croct/resolveCredentials.ts**

  ```ts
  import {getRequestHost} from 'h3';
  import type {CredentialsResolver, CroctCredentials} from '@croct/plug-nuxt/types';

  const resolveCredentials: CredentialsResolver = event => {
    const tenant = getRequestHost(event).split('.')[0];

    return $fetch<CroctCredentials>('https://secrets.example.com/credentials', {
      query: {tenant: tenant},
    }).catch(() => null);
  };

  export default resolveCredentials;
  ```

  Fetch the credentials from an external service, never from an internal Nuxt route. The middleware runs on every request, so calling an internal route re-invokes the resolver and causes infinite recursion. Cache each tenant's credentials in production to avoid a lookup per request.

- `urlSanitizer`: `string` (optional)

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

  For example, to strip sensitive query parameters:

  **nuxt.config.ts**

  ```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**

  ```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`: `object` (optional)

  Cookie configuration for identity management.

  - `clientId`: `object` (optional)

    Configuration for the Client ID cookie.

    - `name`: `string` (optional) (default: ct.client\_id)

      The name of the cookie that stores the Client ID.

    - `domain`: `string` (optional)

      The domain of the Client ID cookie.

      This is useful when you have a website with multiple subdomains and you want to recognize the same user across all of them.

    - `duration`: `number` (optional) (default: 31536000)

      The duration of the Client ID cookie in seconds.

      The default is 1 year.

  - `userToken`: `object` (optional)

    Configuration for the user token cookie.

    - `name`: `string` (optional) (default: ct.user\_token)

      The name of the cookie that stores the user token.

    - `domain`: `string` (optional)

      The domain of the user token cookie.

      This is useful when you have a website with multiple subdomains and you want to recognize the same user across all of them.

    - `duration`: `number` (optional) (default: 604800)

      The duration of the user token cookie in seconds.

      The default is 7 days.

  - `previewToken`: `object` (optional)

    Configuration for the preview token cookie.

    - `name`: `string` (optional) (default: ct.preview\_token)

      The name of the cookie that stores the preview token.

    - `domain`: `string` (optional)

      The domain of the preview token cookie.

      This is useful when you have a website with multiple subdomains and you want the preview to work across them.