@studio-fes/layer-base

@studio-fes/layer-base

Base Nuxt layer with shared utilities, components, and configurations for building modern web applications.

Features

🎨 Styling & Animations

• UnoCSS: Utility-first CSS framework with Wind preset
• GSAP: Professional-grade animation library with custom easings

🖼️ Media Optimization

• Nuxt Image: Optimized image component with lazy loading
• Nuxt Fonts: Automatic font optimization
• Unlazy: Advanced lazy loading utilities

⚡ Developer Experience

• VueUse: Collection of Vue composition utilities
• Nuxt Scripts: Optimized third-party script loading
• TypeScript: Full type safety

Installation

npm install @studio-fes/layer-base

Usage

Extend this layer in your nuxt.config.ts:

export default defineNuxtConfig({
  extends: ['@studio-fes/layer-base']
})

What's Included

Components

<Image>

Optimized image component with lazy loading support.

<template>
  <Image :image="image" />
</template>

<Text>

Text component with interpolation support.

<template>
  <Text text="Your text here" />
</template>

Composables

useGSAP()

GSAP animation utilities with custom easings.

const { gsap } = useGSAP()

gsap.to(element, { duration: 1, x: 100 })

useLockBody()

Lock/unlock body scroll (useful for modals).

const { lock, unlock } = useLockBody()

onMounted(() => lock())
onUnmounted(() => unlock())

Utils

Custom GSAP easings and utility functions are available in utils/.

Configuration

The layer provides sensible defaults in nuxt.config.ts:

{
  modules: [
    '@nuxt/eslint',
    '@nuxt/fonts',
    '@nuxt/image',
    '@nuxt/scripts',
    '@nuxtjs/i18n',
    '@nuxtjs/seo',
    '@unocss/nuxt',
    '@vueuse/nuxt',
    'gsap-nuxt-module',
    'nuxt-svgo',
  ],
  runtimeConfig: {
    public: {
      baseUrl: import.meta.env.NUXT_PUBLIC_BASE_URL || '',
    },
  },
  image: {
    provider: 'ipx',
    cloudflare: {
      baseURL: import.meta.env.NUXT_IMAGE_CLOUDFLARE_BASE_URL,
    },
    format: ['webp'],
  },
}

Variabili d'ambiente

# fallback dell'URL del sito quando site-config non ha `url` (es. non arriva dal CMS)
NUXT_PUBLIC_BASE_URL=https://www.example.com
# provider immagini (letta da @nuxt/image, default 'ipx')
NUXT_IMAGE_PROVIDER=cloudflare
# dominio Cloudflare per le immagini, usato solo con provider 'cloudflare'
NUXT_IMAGE_CLOUDFLARE_BASE_URL=https://cdn.example.com
# crediti nell'HTML
NUXT_CREDITS_ENABLED=false
NUXT_CREDITS_TEXT="..."

Sono lette con import.meta.env, quindi al build: in Docker/Coolify devono esserci durante la build, non solo all'avvio.

Immagini

Il provider di default è ipx. Per usare Cloudflare:

NUXT_IMAGE_PROVIDER=cloudflare
NUXT_IMAGE_CLOUDFLARE_BASE_URL=https://cdn.example.com

NUXT_IMAGE_PROVIDER è letta da @nuxt/image stesso e vince su image.provider del config. In alternativa si scrivono image.provider e image.cloudflare.baseURL nel nuxt.config.ts del progetto (il baseURL del progetto vince sulla variabile).

Le varianti NUXT_PUBLIC_IMAGE_PROVIDER / NUXT_PUBLIC_IMAGE_DOMAIN non sono lette da nessuno.

Prefetch delle pagine

NuxtLink (e Anchor) precaricano chunk e dati della pagina all'hover/focus, con il _payload.json nativo di Nuxt:

• routeRules: { '/**': { isr: true } } fa generare il payload di ogni pagina. Sul preset node Nitro non usa isr per cachare l'HTML; su Vercel/Netlify è un ISR vero: lì va sovrascritto (es. isr: 60).
• experimental.payloadExtraction: 'client': al primo caricamento i dati restano nell'HTML, il payload serve solo alle navigazioni.
• server/middleware/payload-cache-control.ts dà a _payload.json Cache-Control: private, max-age=60, così il payload precaricato all'hover viene riusato al click.
• Le query con graphqlCaching.client di nuxt-graphql-middleware non leggono il payload e vengono rifatte al click: nelle pagine meglio non usarlo.

Development

# Install dependencies
pnpm install

# Develop with playground
pnpm dev

# Build
pnpm build

# Lint
pnpm lint

Extending

Create a new layer that extends this one:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@studio-fes/layer-base'],
  // Your custom configuration
})

License

MIT