defineConfig()

You can specify global configuration that will be applied to all created composables and functions. In order to achieve this, you need to use the defineConfig() composable.

import { defineConfig } from '@kovalson/prevue';

defineConfig({
  apiUrl: 'https://your-api.domain',
  headers: {
    Authorization: 'Bearer token',
    // ...
  },
  convertCase: true,
  pagination: {
    dataWrapper: 'data',
    paginationWrapper: 'pagination',
    currentPage: 'currentPage',
    lastPage: 'lastPage',
    perPage: 'perPage',
    total: 'total',
  },
  requestOptions: {
    headers: {
      // ...
    },
  },
});

Note that this is a special composable in the package. This function does not return any object or value at all. What's more, it can only be called once, as any further call will cause an error to be thrown.

Config Options

The following is a complete list of all properties that can be passed to the composable.

Property	Default	Type	Description
apiUrl		string	The base part of API URL. Example: https://your-api.domain
headers		HeadersInit or () => HeadersInit	Headers to attach to all API requests.
convertCase	false	boolean	Whether to automatically convert incoming data objects' keys to camelCase.
pagination		IPaginationSetup	Global pagination template for all responses.
requestOptions		TApiOptions	Global API request options. The TApiOptions type extends FetchOptions<'json'> from ofetch.

Precedence

Any configuration values passed directly to other composables (such as defineApi() etc.) will take precedence over the global configuration. In other words, the global configuration can be seen as a fallback for all parameters that weren't otherwise specified.

Headers & Request Options

Request Options are a superset of Headers (see FetchOptions in ofetch for reference). However, Prevue allows you to configure both options for convenience. In such case, the headers property will overwrite any headers set in requestOptions.

Also, both headers and requestOptions can be further overwritten by any options passed directly as a parameter to the request endpoint method.

Usage

It is crucial to run this function before any API call is made. The very first use of the defineConfig() composable causes the global configuration object to be frozen so it cannot be further changed.

This was designed specifically to avoid any unwanted mutations to the global configuration in the runtime.

Vue 3

For example, if you're initializing Vue 3 app the standard way, you should define the global config just before that.

import { defineConfig } from '@kovalson/prevue';
import { createApp } from 'vue';
import App from './App.vue';

defineConfig({
  // ...
});

const app = createApp(App);

Nuxt 3

When using Nuxt 3, you can create a simple plugin that will set up Prevue's global configuration.

// plugins/prevue.ts
import { defineConfig } from '@kovalson/prevue';

export default defineNuxtPlugin(() => {
  defineConfig({
    // ...
  });
});

Examples

Headers

Headers can be declared as a static object of type HeadersInit or a function that returns such object.

import { defineConfig } from '@kovalson/prevue';

// Static object
defineConfig({
  headers: {
    Authorization: 'Bearer token',
  },
});

// Function
defineConfig({
  headers() {
    return {
      Authorization: 'Bearer token',
    };
  },
});

This is specifically designed for cases when some headers might be related on other states of your application, and thus conditionally set. The authorization process is a good example to illustrate when you might need to use a function instead of a static object.

import { defineConfig } from '@kovalson/prevue';
import { useAuthUser } from '~/models/User';

defineConfig({
  headers() {
    const authUser = useAuthUser();

    return {
      Authorization: `Bearer ${authUser.token}`,
    };
  },
});

You can freely use any runtime composables inside the headers' function as it is going to be run after the app is fully initialized and all contexts and imports are resolved.

Pagination Template

You can configure a global pagination template for all responses of all models:

import { defineConfig } from '@kovalson/prevue';

defineConfig({
  pagination: {
    paginationWrapper: 'pages',
    dataWrapper: 'items',
    currentPage: 'current',
    lastPage: 'last',
    perPage: 'per_page',
    total: 'count',
  },
});

If you need more control over the response, you can use a pagination response mapper function:

import { defineConfig } from '@kovalson/prevue';

defineConfig({
  pagination: {
    dataWrapper: 'items',
    mapper(response) {
      return {
        currentPage: response.pages.current,
        lastPage: Math.ceil(response.pages.meta.resultsCount / response.pages.current * response.pages.perPage),
        perPage: 10,
        total: response.pages.meta.resultsCount,
      };
    },
  },
});