@nuvler/theme-sdk

Contrato público compartilhado entre temas Nuvler e o Store.

import { defineTheme, THEME_API_VERSION, THEME_RUNTIME_VERSION } from "@nuvler/theme-sdk";

export const theme = defineTheme({
  manifest: {
    schemaVersion: 1,
    id: "meu-tema",
    name: "Meu tema",
    version: "1.0.1",
    runtimeVersion: THEME_RUNTIME_VERSION,
    sdkVersion: `^${THEME_API_VERSION}`,
    entry: "src/theme.tsx",
    styles: ["src/theme.css"],
    presentation: {
      description: "Tema da minha loja",
      colors: {
        primary: "#1d4ed8", primaryText: "#ffffff",
        secondary: "#f59e0b", secondaryText: "#0f172a", accent: "#d97706",
        background: "#f8fafc", surface: "#ffffff", surfaceAlt: "#f1f5f9",
        text: "#0f172a", textMuted: "#64748b", border: "#e2e8f0",
        headerBackground: "#ffffff", headerText: "#0f172a",
        footerBackground: "#0f172a", footerText: "#f8fafc",
      },
      layout: { containerWidth: 1200, borderRadius: 16 },
    },
  },
  // tokens, template e components
});

version identifica a versão imutável do tema. runtimeVersion identifica o protocolo mount/unmount e sdkVersion declara a faixa do SDK aceita.

primary, secondary, background e text permanecem obrigatórios para compatibilidade. Os demais tokens semânticos são opcionais no contrato, mas o starter atual já os declara e os runtimes aplicam fallbacks para temas antigos.

Use productUrl(product) ao gerar links de produto. Quando categoryPath estiver presente, a URL inclui toda a hierarquia da categoria principal; com APIs antigas, o helper mantém o fallback /produto/slug.

Componentes da Home declarados pelo tema

Na Theme API 1.3, manifest.presentation.homeComponents declara componentes que o Gestão pode editar sem conhecer previamente sua implementação. Cada seção usa type: "theme-component" e carrega componentKey, schemaVersion e props. Formulários usam a ação segura contact.submit e recebem a função em HomeProps.submitContact ou ThemeRuntimeSdk.contact.submit.

O contrato completo e os exemplos estão em docs/dynamic-home-components.md.