@gluhar/app
Gluhar main package. This combines and configures @gluhar/theme, @gluhar/i18n, @gluhar/sanity and @gluhar/core into one main package. Provides numerous components, composables, utils and types.
Installation
Install the module to your Nuxt application with one command:
npx nuxi module add @gluhar/app
Usage
Page transitions (usePageTransition)
Router-driven page transitions. The leave plays before navigation and holds it until the
timeline is done; the enter waits until the incoming page has rendered (Nuxt's
page:finish, so a page awaiting useFetch / useSinglePage is on screen first), capped
by readyTimeout. Use it in ONE component that wraps the page, never per page:
<!-- components/layout/PageTransition.vue -->
<script setup lang="ts">
const wrapper = ref<HTMLElement>();
const overlay = ref<HTMLElement>();
usePageTransition({
// Forward = leave (visible → hidden), reversed = enter. The project owns the look.
timeline: (gsap) =>
gsap
.timeline()
.fromTo(wrapper.value!, { opacity: 1 }, { opacity: 0, duration: 0.5 })
.fromTo(overlay.value!, { autoAlpha: 0 }, { autoAlpha: 1, duration: 0.5 }, 0),
});
</script>
<template>
<div ref="wrapper"><slot /></div>
<div ref="overlay" class="pointer-events-none fixed inset-0 invisible bg-white" />
</template>
Scrolling needs nothing here: Nuxt's router scrolls the window to the top (or the hash) once the new page rendered, and Lenis is paused for the leave and resumed for the enter, resyncing to that position.
<!-- layouts/default.vue: no :key on the wrapper, it must not remount per route -->
<PageTransition><main><slot /></main><Footer /></PageTransition>
| Option | Default | |
|---|---|---|
timeline(gsap) | required | Built in onMounted (refs are set). Don't set paused / onComplete / onReverseComplete: the composable pauses it and kill()s it on unmount |
onEnter(to) | — | Runs after the new page rendered and the router scrolled, before the enter plays |
skip(to, from) | — | Navigations to let through untouched. Same-path (hash / query only) navigations never transition |
firstEnter | "none" | "none": the server-rendered page shows as is (no flash, nothing held from LCP). "manual": starts hidden until usePageTransitionStore().allowFirstEnter(), e.g. from a loader |
readyTimeout | 3000 | Longest wait for the incoming page before entering anyway |
A navigation that is aborted or throws after the leave started brings the current page
back. usePageTransitionStore() exposes phase (idle / leaving / entering /
entered), entered, transitioning, enterCycle / leaveCycle (bumped per completed
enter / leave, to replay a section's intro) and setDelay(ms) (hold the next enter).
Smooth scrolling (gluhar.lenis)
Lenis on the window, on by default:
// nuxt.config.ts
gluhar: {
lenis: { lerp: 0.1, wheelMultiplier: 1 }, // or true (defaults) / false (native scrolling)
}
- Driven by GSAP's ticker, with
ScrollTrigger.updateon every scroll, so pinned and scrubbed sections stay in the same frame as the scroll. - Lenis honours
prefers-reduced-motionitself and then scrolls natively. - Options are serialized into runtime config, so functions (
easing,prevent,virtualScroll) and elements can't be set here. Configure those on the instance. useLenis()returns{ lenis }, a computed of the instance. It isnullon the server, withlenis: false, or before the client plugin ran, so always optional-chain it:lenis.value?.scrollTo("#faq", { offset: -80 }).- Scroll in-page through
lenis.value.scrollTowhile it runs, never with a GSAP tween on the window: the two fight over the position. - To keep Lenis off one natively scrollable element (a map, a code block), add
data-lenis-prevent.
The page itself always scrolls on the window. There is no page-level scroll container
(useLenis("#scroller")): one breaks native anchors, the router's scroll restoration,
position: sticky against the viewport and every ScrollTrigger that doesn't name it as
its scroller.
Nested smooth scrolling (<GLenisScroller>)
For an area that scrolls on its own inside the page (a modal body, a side panel, a horizontal strip), with its own Lenis:
<GLenisScroller class="h-[60svh]" content-class="p-6" :options="{ lerp: 0.12 }">
…
</GLenisScroller>
- The element needs a bounded size (a height, or flex/grid sizing) to scroll at all.
- It carries
data-lenis-prevent, so the window Lenis ignores wheel and touch events inside it and the two never scroll at once. It works withgluhar.lenis: falsetoo. - Exposes
lenis,scrollerRefandcontentRef. A ScrollTrigger inside it must name the element:scroller: scroller.value.scrollerRef. - Its instance is not the one
useLenis()returns, and page transitions don't pause it.
Sanity images (<SanityImg>)
Pass sizes for a responsive, server-rendered image: srcset over widths (never past
the original's width), auto=format, quality 75, loading="lazy" (override with
loading="eager" + fetchpriority="high" for the first image) and object-position from
the hotspot. placeholder adds the lqip as a blurred background until the image has loaded (then it's
removed, so it never shows through object-contain letterboxing). Dereference the asset for the
dimensions and the lqip: photo{ ..., asset->{ _id, metadata { lqip, dimensions } } }.
<SanityImg class="absolute inset-0 size-full" :image="photo" sizes="(min-width: 48rem) 33vw, 100vw" />
Without sizes it keeps the old behaviour: the URL is sized to the element after mount
(no src on the server), so prefer sizes for lists and anything above the fold.
SEO and link previews (useSeo)
useSeo(seo?) sets title, description and the OG / Twitter set, server-rendered and kept in
sync on the client, falling back to the default SEO document field by field. Pass a getter
for values that depend on state (a filtered view), plain strings or locale fields, an
ogImage Sanity image (a 1200×630 crop on its hotspot is built from the asset; an
asset.url is used as is) and an absolute url for og:url:
useSeo(() => ({ title: viewTitle.value, ogImage: first.value?.photos?.[0], url: absoluteUrl.value }));
GSAP
gsap is a dependency of @gluhar/app. ScrollTrigger and ScrollToPlugin are registered
on the client. Import it (import { gsap } from "gsap") or use the auto-imports
useGSAP() and useScrollTrigger(), which return the same objects. A project that adds
gsap itself should keep it on the same range so npm installs one copy: two copies mean
two tickers, and Lenis would update a ScrollTrigger nobody listens to.
v-gsap-nuxt is not installed (since 6.0.0-next.10).
Config
Contribution
Local development
# Install dependencies
npm install
# Generate type stubs
npm run dev:prepare
# Develop with the playground
npm run dev
# Build the playground
npm run dev:build
# Run ESLint
npm run lint
# Run Vitest
npm run test
npm run test:watch
# Release new version
npm run release