@gluhar/app

中文文档
6.4.1发布于 2026/11/16MITTypeScriptES Module近 30 天下载 2933

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.

原始使用文档
文档目录10 节
  1. Installation
  2. Usage
  3. Page transitions ( usePageTransition )
  4. Smooth scrolling ( gluhar.lenis )
  5. Nested smooth scrolling ( <GLenisScroller> )
  6. Sanity images ( <SanityImg> )
  7. SEO and link previews ( useSeo )
  8. GSAP
  9. Config
  10. Contribution

@gluhar/app

npm version npm downloads License Nuxt

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.

✨  Release Notes

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>
OptionDefault
timeline(gsap)requiredBuilt 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
readyTimeout3000Longest 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.update on every scroll, so pinned and scrubbed sections stay in the same frame as the scroll.
  • Lenis honours prefers-reduced-motion itself 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 is null on the server, with lenis: false, or before the client plugin ran, so always optional-chain it: lenis.value?.scrollTo("#faq", { offset: -80 }).
  • Scroll in-page through lenis.value.scrollTo while 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 with gluhar.lenis: false too.
  • Exposes lenis, scrollerRef and contentRef. 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.

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

版本与发布记录

@gluhar/app 共发布 81 个版本,首次发布于 2025/01/22;过去 12 个月发布了 34 个版本。

版本发布日期距今
6.4.1latest2026/11/16今天
6.4.02026/11/161 天前
6.3.22026/11/161 天前
6.3.12026/11/161 天前
6.3.02026/11/151 天前
6.2.02026/11/151 天前

其他发布通道:dev → 3.0.1-dev.2,next → 6.0.0-next.12。

关于 @gluhar/app 的常见问题

@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.

如何安装 @gluhar/app?

在项目目录运行 npm install @gluhar/app,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:nuxt(^4.6.2)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gluhar/app 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gluhar/app 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gluhar/app 可以商用吗?

@gluhar/app 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gluhar/app 的下载量有多少?

根据 npm 官方下载统计,@gluhar/app 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,933 次,日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gluhar/app 还在维护吗?

最新版本 6.4.1 发布于 2026/11/16(今天);至今共发布 81 个版本,其中过去 12 个月发布了 34 个;首次发布于 2025/01/22。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。