useSpStore

import { useSpStore } from '@bbc/front-end-kit/vue/showpad'

The useSpStore is the Central Hub and Decision Layer for all Showpad-related functionality within the application. It acts as a facade that coordinates between specific backend stores (SDK and API) to provide a unified, reactive interface for components.

Overview

Following the core architecture, useSpStore implements a "SDK-first, API-fallback" strategy. It abstracts the complexity of deciding which source to use and handles the orchestration of initialization stages.

Getting started

const spStore = useSpStore();

// initialise the store
spStore.init()
    .then(() => {
        console.log('done')
    })
    .catch((error) => {
        console.error(error);
    });

Extra load stages

Projects often require additional asynchronous setup before the app is considered "Ready". You can register these using addLoadStage.

const spStore = useSpStore();

spStore.addLoadStage('Loading Projects', async () => {
    const projectStore = useProjectStore();
    await projectStore.fetchAll();
});

Conditional load stages

You can provide a condition to skip a stage if it's not relevant for the current session.

spStore.addLoadStage('Admin Sync', async () => {
    // Sync logic
}, { condition: () => spStore.userInfo.isAdmin });

Config JSON Generation Tooling

The useSpStore works seamlessly with the ConfigGenButton component to power the Config JSON Generation workflow used in development mode.

The store acts as the central coordinator: you register the routes that should be scanned via configGenRoutes, and the ConfigGenButton will iterate through each of them automatically. The store's isConfigBuilding flag (proxied from useSpConfigStore) signals to the rest of your app that a scan is in progress, which you can use to ensure the full DOM is rendered before scanning starts.

Development only

The ConfigGenButton only renders when isConfigBuilding is true, which is activated by clicking the button itself. This keeps the tooling out of the way during normal usage.

Example

The typical setup registers routes early in your app's lifecycle and then places the ConfigGenButton component somewhere globally (e.g. App.vue).

main.js / app setup

const spStore = useSpStore();

// Register the routes the config generator should scan
spStore.configGenRoutes = [
    '/overview',
    '/products',
    '/products/detail',
    '/contact',
];

await spStore.init();

App.vue

<template>
    <RouterView />

    <!-- Only visible (and functional) in dev mode during config generation -->
    <ConfigGenButton />
</template>

<script setup>
import { ConfigGenButton } from '@bbc/front-end-kit/vue/showpad';
import { useSpStore } from '@bbc/front-end-kit/vue/showpad';

const spStore = useSpStore();
</script>

Gating DOM-heavy logic with isConfigBuilding

If certain parts of your UI lazy-load content, you can use isConfigBuilding to ensure everything is visible before the scanner moves on:

<script setup>
import { useSpStore } from '@bbc/front-end-kit/vue/showpad';

const spStore = useSpStore();
</script>

<template>
    <!--
        When config is being built, force-expand all sections
        so every data-sp-* attribute is present in the DOM.
    -->
    <AccordionSection :forceOpen="spStore.isConfigBuilding">
        <slot />
    </AccordionSection>
</template>

When the scan completes, the final config object is logged to the browser console. Copy it into your config.json to finish.

API

State & Properties

`loaded`

A reactive boolean indicating if the store and all registered load stages have finished loading.

Values: Ref<Boolean>

`loading`

A reactive boolean indicating if the store or any registered load stage is currently active.

Values: ComputedRef<Boolean>

`loadStage`

The current descriptive string of the loading process (e.g., "Loading Showpad SDK", "Authenticating").

Values: ComputedRef<String>

`error`

Contains the error object if initialization fails, including the stage where it occurred.

Values: Ref<{ stage: string, error: any } | null>

`userInfo`

Reactive reference to the current Showpad user's information.

Values: ComputedRef<UserInfo | null>

`deviceInfo`

Reactive reference to the current device information.

Values: ComputedRef<DeviceInfo | null>

`config`

Reactive reference to the Showpad Configuration object.

Values: ComputedRef<Config | null>

`apiConfig`

The authenticated API configuration, containing access tokens.

Values: Ref<ApiConfig | null>

`appMode`

The current application mode. Starts as false before the app mode is determined.

Values: Ref<'development' | 'production' | false>

`isDev`

Convenience flag indicating the app is in development mode.

Values: ComputedRef<Boolean>

`isProd`

Convenience flag indicating the app is in production mode.

Values: ComputedRef<Boolean>

`configGenRoutes`

An array of route paths that the ConfigGenButton will iterate through when generating the config JSON. Populated in your app setup before calling init().

Values: Ref<String[]>

`currentGenRoute`

The route currently being scanned during a config generation run. Useful for tracking progress or conditionally rendering content during the scan.

Values: Ref<String | null>

`genConfig`

Boolean flag that, when set to true in development mode, switches updateDom() from injecting config values into triggering config JSON generation. Proxied from useSpConfigStore.

Values: Ref<Boolean>

`isConfigBuilding`

Computed flag that is true only when the app is in development mode, the current user is an admin, and genConfig is enabled. Used to gate DOM-heavy or lazy-loaded content that must be visible for the scanner. Proxied from useSpConfigStore.

Values: ComputedRef<Boolean>

`loadPromise`

The Promise returned by the most recent init() call. Useful for awaiting initialization from outside the call site.

Values: Ref<Promise | null>

Methods

`init (options)`

Initializes the Showpad connection. It orchestrates the loading of the SDK, authentication, and API access.

Parameters:

options.authenticate (Boolean): Request API authentication tokens.
options.apiAccess (Boolean): Initialize the REST API store (implies authentication).

Returns: Promise<void>

init() never rejects

Errors during initialization are caught internally and stored on error.value — init() always resolves. Check error.value after the promise settles to detect failures rather than using .catch().

`addLoadStage (name, callback, options)`

Registers a custom loading stage that must complete before loaded becomes true.

Parameters:

name (String): The label to show during this stage.
callback (Function): The asynchronous function to execute.
options.condition (Function): A function returning a boolean; if false, the stage is skipped.
options.loadStageTracking (Function): A getter function to track granular progress within this stage.

`forceLoadStage (label)`

Manually overrides the current loadStage label. Useful inside custom addLoadStage callbacks to display granular progress messages.

Parameters:

label (String): The string to display as the current stage.

`registerLoadStageSource (getter)`

Registers an external reactive source whose loading and loadStage values should be included in the computed loading and loadStage properties of this store.

Parameters:

getter (Function): A zero-argument function that returns an object with loading and loadStage properties.