@stackonward/nuxt-layer-base

@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

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

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