@stackonward/nuxt-layer-base

De-branded Nuxt layer foundation for API client wiring, request-scoped session state, Pinia, i18n, and page-level SEO. It supplies replaceable seams instead of product routes, business models, or credentials.

Install

pnpm add @stackonward/nuxt-layer-base @stackonward/api-client @nuxtjs/i18n @pinia/nuxt pinia

Nuxt and Vue are peer dependencies of the consuming application.

Extend the layer

export default defineNuxtConfig({
  extends: ["@stackonward/nuxt-layer-base"],
  runtimeConfig: {
    public: {
      api: {
        baseUrl: process.env.NUXT_PUBLIC_API_BASE_URL || "",
      },
    },
  },
  i18n: {
    locales: [
      { code: "en", language: "en-US", file: "en.json" },
      { code: "fr", language: "fr-FR", file: "fr.json" },
    ],
  },
});

The layer enables Nuxt 4 compatibility behavior, Pinia, and Nuxt i18n. Its default locale is English with prefix_except_default; consuming layers extend or override that resource bundle.

Included application seams

| Seam | Default behavior | Consumer responsibility | | ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- | | $apiClient plugin | Creates @stackonward/api-client from public.api.baseUrl | Supply the real base URL and override provider-specific auth/error wiring | | useAuthStore | In-memory session plus an untyped viewer projection | Own persistence and the product viewer model | | useAuth | Exposes readonly session/auth refs and store setters | Override when the product needs a different auth contract | | usePageSeo | Applies page title, description, and Open Graph image | Own site defaults and structured data | | i18n resource | Provides generic loading, error, and retry labels | Add product locales and business copy |

The default API plugin deliberately has no refresh endpoint: when its TokenStore needs a refresh, it clears the session. A product with refresh credentials must replace that plugin or construct a token store with its own server-safe refresh adapter.

Session token adapter

The /runtime entry adapts product-owned session storage to the @stackonward/api-client TokenStore contract:

import type { Ref } from "vue";
import { createSessionTokenStore, type SessionState } from "@stackonward/nuxt-layer-base/runtime";

export function createTokenStore(
  session: Ref<SessionState | null>,
  refreshSession: (refreshToken: string) => Promise<SessionState | null>,
) {
  return createSessionTokenStore({
    getSession: () => session.value,
    setSession: (next) => {
      session.value = next;
    },
    refreshSession,
  });
}

The adapter refreshes within 60 seconds of expiry by default and collapses concurrent refreshes into one promise. Create one instance for the browser application and one instance per SSR request; never share user session state in a long-lived Nitro singleton.

SessionState, AuthState<TViewer>, StorageAdapter, and SessionTokenStoreOptions are exported from the same runtime entry.

Entry points

| Entry point | Purpose | | -------------------------------------- | ----------------------------------------------------- | | @stackonward/nuxt-layer-base | Nuxt layer used through extends | | @stackonward/nuxt-layer-base/runtime | Framework-independent session/token adapter and types |

Compatibility

• Nuxt >=3.15.0
• Vue ^3.5.0
• Pinia >=3.0.4 <4
• @pinia/nuxt >=0.11.0 <1
• @nuxtjs/i18n >=10.4.0 <11
• @stackonward/api-client ^0.0.2

Related packages

• @stackonward/api-client owns the generic HTTP and token-store contracts.
• @stackonward/nuxt-site-shell extends this layer with the public product-site module stack.

License

MIT