@macrulez/masonry-kit-nuxt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danil Lisin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# **Masonry Kit Nuxt**
+
+![Masonry Kit Nuxt](https://github.com/macrulezru/assets/blob/master/packages-images/masonry-kit-nuxt-vuecraft.png?raw=true)
+
+Nuxt module wrapping
+[`@macrulez/masonry-kit-vue`](https://www.npmjs.com/package/@macrulez/masonry-kit-vue):
+auto-imported `<MasonryGrid>`/`useMasonry`, a universal plugin that
+seeds their option defaults from your `nuxt.config.ts`, and no manual
+`<ClientOnly>` wrapping needed — the component is already SSR-safe on
+its own, rendering a CSS `columns` approximation until it can measure
+for real.
+
+Part of the [masonry-kit](https://github.com/macrulezru/masonry-kit)
+monorepo.
+
+---
+
+## Features
+
+- **Auto-imports `<MasonryGrid>` and `useMasonry`** — no explicit `import` anywhere in your app
+- **Module options forwarded through `runtimeConfig`** — `direction`, `columns`, `rows`, `minLaneSize`, `gap`, `placement`, `animate`, `transitionDuration`, `transitionEasing`, `ssrColumns`, set once in `nuxt.config.ts` and applied everywhere
+- **A universal (server + client) plugin seeds those defaults** — most option defaults only matter once the engine exists client-side, but `ssrColumns` is read directly by `<MasonryGrid>`'s render function, which runs during SSR too — so the plugin isn't `.client`-only
+- **No `<ClientOnly>` needed anywhere** — `<MasonryGrid>` renders a CSS `columns` approximation server-side and switches to the real transform-based layout the moment it measures on the client, in the same frame
+
+---
+
+## When you'd reach for this
+
+You're already on Nuxt and want `<MasonryGrid>`/`useMasonry` wired up with zero manual setup — auto-imports, and one place to configure defaults instead of passing the same options at every call site.
+
+- **Passing the same `gap`/`columns` to every single `<MasonryGrid>` on the site gets old** — Set them once in `nuxt.config.ts` and every instance that doesn't override them picks up your project's defaults automatically.
+- **You'd rather not remember to import `<MasonryGrid>` in every component** — Auto-imports mean it's just available, the same way Nuxt's own built-ins are.
+- **A team member reaches for `<ClientOnly>` out of habit** — There's nothing to wrap; the component already renders a safe SSR approximation and swaps to the real layout after hydration on its own.
+
+---
+
+## Installation
+
+```bash
+npm install @macrulez/masonry-kit-nuxt
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@macrulez/masonry-kit-nuxt'],
+  masonry: {
+    columns: 'auto',
+    minLaneSize: 240,
+    gap: 16,
+  },
+})
+```
+
+Requires Nuxt `^3.9.0 || ^4.0.0`.
+
+### Quick start
+
+Once the module is registered, just use the component — no imports:
+
+```vue
+<template>
+  <!-- <MasonryGrid>/useMasonry are auto-imported -->
+  <MasonryGrid :items="items">
+    <template #item="{ item }">
+      <MyCard :data="item" />
+    </template>
+  </MasonryGrid>
+</template>
+```
+
+See
+[`@macrulez/masonry-kit-vue`'s README](https://www.npmjs.com/package/@macrulez/masonry-kit-vue)
+for the full `<MasonryGrid>`/`useMasonry` API — props, slots, `sortable`, virtualization, and more.
+
+### More examples
+
+#### What the module does
+
+1. **Auto-imports** `<MasonryGrid>` and `useMasonry` from `@macrulez/masonry-kit-vue` — no explicit `import` needed in your components.
+2. **Forwards module options** (`direction`, `columns`, `rows`, `minLaneSize`, `gap`, `placement`, `animate`, `transitionDuration`, `transitionEasing`, `ssrColumns`) into `runtimeConfig.public.masonry`.
+3. **Registers a universal plugin** that reads that runtime config and calls `setMasonryDefaults(...)` — so every `<MasonryGrid>`/`useMasonry` use that doesn't pass its own `options` picks up your configured defaults.
+
+#### Module options
+
+| Option               | Falls through to                                        |
+| -------------------- | ------------------------------------------------------- |
+| `direction`          | core's own default (`'vertical'`) when unset            |
+| `columns` / `rows`   | core's own default (`'auto'`) when unset                |
+| `minLaneSize`        | core's own default (`240`) when unset                   |
+| `gap`                | core's own default (`16`/`16`) when unset               |
+| `placement`          | core's own default (`'balanced'`) when unset            |
+| `animate`            | core's own default (`true`) when unset                  |
+| `transitionDuration` | core's own default (`250`) when unset                   |
+| `transitionEasing`   | core's own default when unset                           |
+| `ssrColumns`         | `columns`/`rows` (if concrete), else a conservative `2` |
+
+None of these are hardcoded in the module itself — an option you don't set stays `undefined` all the way through to `@macrulez/masonry-kit-core`'s own default, so a future change to core's default keeps applying automatically for Nuxt consumers too.
+
+#### Overriding defaults per instance
+
+Module options are the _fallback_, not a ceiling — any `<MasonryGrid :options="...">` prop still wins for that one instance:
+
+```vue
+<template>
+  <MasonryGrid :items="items" :options="{ columns: 2 }">
+    <!-- uses 2 columns here, regardless of the module-wide default -->
+    <template #item="{ item }">
+      <MyCard :data="item" />
+    </template>
+  </MasonryGrid>
+</template>
+```
+
+---
+
+## Documentation & links
+
+- 📖 **Full documentation:** [npm.vuecraft.ru/en/packages/masonry-kit](https://npm.vuecraft.ru/en/packages/masonry-kit/guide/nuxt-module.html)
+- 🌐 **VueCraft:** [vuecraft.ru/en](https://vuecraft.ru/en)
+- 👤 **Author:** [macrulez.ru/en](https://macrulez.ru/en)
+- 💻 **GitHub:** [macrulezru/masonry-kit/packages/nuxt](https://github.com/macrulezru/masonry-kit/tree/master/packages/nuxt)
+- 📦 **NPM:** [@macrulez/masonry-kit-nuxt](https://www.npmjs.com/package/@macrulez/masonry-kit-nuxt)
+- 🐛 **Issues:** [github.com/macrulezru/masonry-kit/issues](https://github.com/macrulezru/masonry-kit/issues)
+
+---
+
+## License
+
+MIT
+
+---
+
+## 💖 Support the project
+
+Open source takes time and effort. If this library saves you time or brings value, consider supporting further development.
+
+<a href="https://donate.cryptocloud.plus/M6O34NIN" target="_blank">
+  <img src="https://img.shields.io/badge/Donate-CryptoCloud-8A2BE2?style=for-the-badge&logo=cryptocurrency&logoColor=white" alt="Donate via CryptoCloud">
+</a>
+
+Thank you for being part of this journey. ❤️

package/dist/module.d.ts

@@ -0,0 +1,26 @@
+import { NuxtModule } from '@nuxt/schema';
+import { LaneSpec } from '@macrulez/masonry-kit-vue';
+
+interface ModuleOptions {
+    /** Falls through to @macrulez/masonry-kit-core's own default ('vertical') when unset. */
+    direction?: 'vertical' | 'horizontal';
+    columns?: LaneSpec;
+    rows?: LaneSpec;
+    /** Falls through to @macrulez/masonry-kit-core's own default (240) when unset. */
+    minLaneSize?: number;
+    gap?: number | {
+        main?: number;
+        cross?: number;
+    };
+    placement?: 'balanced' | 'ordered';
+    /** Falls through to @macrulez/masonry-kit-core's own default (true) when unset. */
+    animate?: boolean;
+    /** Falls through to @macrulez/masonry-kit-core's own default (250) when unset. */
+    transitionDuration?: number;
+    transitionEasing?: string;
+    /** CSS-columns SSR fallback (§4.4). Falls through to `columns`/`rows` (if concrete), else a conservative default of 2, when unset. */
+    ssrColumns?: number;
+}
+declare const masonryKitModule: NuxtModule<ModuleOptions>;
+
+export { type ModuleOptions, masonryKitModule as default };

package/dist/module.js

@@ -0,0 +1,36 @@
+// src/module.ts
+import { addComponent, addImports, addPlugin, createResolver, defineNuxtModule } from "@nuxt/kit";
+var masonryKitModule = defineNuxtModule({
+  meta: {
+    name: "@macrulez/masonry-kit-nuxt",
+    configKey: "masonry"
+  },
+  // No `defaults` here on purpose: an option the user didn't set in
+  // nuxt.config.ts must stay `undefined` all the way through to
+  // @macrulez/masonry-kit-core's own defaults — hardcoding one here would
+  // silently shadow it, making a change to core's default look like it does
+  // nothing for a Nuxt consumer.
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    addComponent({ name: "MasonryGrid", export: "MasonryGrid", filePath: "@macrulez/masonry-kit-vue" });
+    addImports({ name: "useMasonry", from: "@macrulez/masonry-kit-vue" });
+    nuxt.options.runtimeConfig.public.masonry = {
+      direction: options.direction,
+      columns: options.columns,
+      rows: options.rows,
+      minLaneSize: options.minLaneSize,
+      gap: options.gap,
+      placement: options.placement,
+      animate: options.animate,
+      transitionDuration: options.transitionDuration,
+      transitionEasing: options.transitionEasing,
+      ssrColumns: options.ssrColumns
+    };
+    addPlugin(resolver.resolve("./runtime/plugin"));
+  }
+});
+var module_default = masonryKitModule;
+export {
+  module_default as default
+};
+//# sourceMappingURL=module.js.map

package/dist/module.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/module.ts"],"sourcesContent":["import { addComponent, addImports, addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'\nimport type { NuxtModule } from '@nuxt/schema'\nimport type { LaneSpec } from '@macrulez/masonry-kit-vue'\n\nexport interface ModuleOptions {\n  /** Falls through to @macrulez/masonry-kit-core's own default ('vertical') when unset. */\n  direction?: 'vertical' | 'horizontal'\n  columns?: LaneSpec\n  rows?: LaneSpec\n  /** Falls through to @macrulez/masonry-kit-core's own default (240) when unset. */\n  minLaneSize?: number\n  gap?: number | { main?: number; cross?: number }\n  placement?: 'balanced' | 'ordered'\n  /** Falls through to @macrulez/masonry-kit-core's own default (true) when unset. */\n  animate?: boolean\n  /** Falls through to @macrulez/masonry-kit-core's own default (250) when unset. */\n  transitionDuration?: number\n  transitionEasing?: string\n  /** CSS-columns SSR fallback (§4.4). Falls through to `columns`/`rows` (if concrete), else a conservative default of 2, when unset. */\n  ssrColumns?: number\n}\n\nconst masonryKitModule: NuxtModule<ModuleOptions> = defineNuxtModule<ModuleOptions>({\n  meta: {\n    name: '@macrulez/masonry-kit-nuxt',\n    configKey: 'masonry',\n  },\n  // No `defaults` here on purpose: an option the user didn't set in\n  // nuxt.config.ts must stay `undefined` all the way through to\n  // @macrulez/masonry-kit-core's own defaults — hardcoding one here would\n  // silently shadow it, making a change to core's default look like it does\n  // nothing for a Nuxt consumer.\n  setup(options, nuxt) {\n    const resolver = createResolver(import.meta.url)\n\n    addComponent({ name: 'MasonryGrid', export: 'MasonryGrid', filePath: '@macrulez/masonry-kit-vue' })\n    addImports({ name: 'useMasonry', from: '@macrulez/masonry-kit-vue' })\n\n    nuxt.options.runtimeConfig.public.masonry = {\n      direction: options.direction,\n      columns: options.columns,\n      rows: options.rows,\n      minLaneSize: options.minLaneSize,\n      gap: options.gap,\n      placement: options.placement,\n      animate: options.animate,\n      transitionDuration: options.transitionDuration,\n      transitionEasing: options.transitionEasing,\n      ssrColumns: options.ssrColumns,\n    }\n\n    // Universal plugin (server + client) — most of these are only consulted\n    // once the engine exists client-side (onMounted), but `ssrColumns`\n    // (§4.4) is read directly by <MasonryGrid>'s render function, which also\n    // runs during SSR, so the defaults need to be seeded there too.\n    addPlugin(resolver.resolve('./runtime/plugin'))\n  },\n})\n\nexport default masonryKitModule\n"],"mappings":";AAAA,SAAS,cAAc,YAAY,WAAW,gBAAgB,wBAAwB;AAsBtF,IAAM,mBAA8C,iBAAgC;AAAA,EAClF,MAAM;AAAA,IACJ,MAAM;AAAA,IACN,WAAW;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,SAAS,MAAM;AACnB,UAAM,WAAW,eAAe,YAAY,GAAG;AAE/C,iBAAa,EAAE,MAAM,eAAe,QAAQ,eAAe,UAAU,4BAA4B,CAAC;AAClG,eAAW,EAAE,MAAM,cAAc,MAAM,4BAA4B,CAAC;AAEpE,SAAK,QAAQ,cAAc,OAAO,UAAU;AAAA,MAC1C,WAAW,QAAQ;AAAA,MACnB,SAAS,QAAQ;AAAA,MACjB,MAAM,QAAQ;AAAA,MACd,aAAa,QAAQ;AAAA,MACrB,KAAK,QAAQ;AAAA,MACb,WAAW,QAAQ;AAAA,MACnB,SAAS,QAAQ;AAAA,MACjB,oBAAoB,QAAQ;AAAA,MAC5B,kBAAkB,QAAQ;AAAA,MAC1B,YAAY,QAAQ;AAAA,IACtB;AAMA,cAAU,SAAS,QAAQ,kBAAkB,CAAC;AAAA,EAChD;AACF,CAAC;AAED,IAAO,iBAAQ;","names":[]}

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,5 @@
+import * as nuxt_app from 'nuxt/app';
+
+declare const _default: nuxt_app.Plugin<Record<string, unknown>> & nuxt_app.ObjectPlugin<Record<string, unknown>>;
+
+export { _default as default };

package/dist/runtime/plugin.js

@@ -0,0 +1,11 @@
+// src/runtime/plugin.ts
+import { setMasonryDefaults } from "@macrulez/masonry-kit-vue";
+import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+var plugin_default = defineNuxtPlugin(() => {
+  const config = useRuntimeConfig().public.masonry;
+  if (config) setMasonryDefaults(config);
+});
+export {
+  plugin_default as default
+};
+//# sourceMappingURL=plugin.js.map

package/dist/runtime/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/runtime/plugin.ts"],"sourcesContent":["import { setMasonryDefaults, type MasonryDefaults } from '@macrulez/masonry-kit-vue'\nimport { defineNuxtPlugin, useRuntimeConfig } from 'nuxt/app'\n\n// Universal (runs on both server and client), not `.client`-suffixed:\n// `ssrColumns` (§4.4) is read directly by <MasonryGrid>'s render function,\n// which runs during SSR too.\nexport default defineNuxtPlugin(() => {\n  const config = useRuntimeConfig().public.masonry as MasonryDefaults | undefined\n  if (config) setMasonryDefaults(config)\n})\n"],"mappings":";AAAA,SAAS,0BAAgD;AACzD,SAAS,kBAAkB,wBAAwB;AAKnD,IAAO,iBAAQ,iBAAiB,MAAM;AACpC,QAAM,SAAS,iBAAiB,EAAE,OAAO;AACzC,MAAI,OAAQ,oBAAmB,MAAM;AACvC,CAAC;","names":[]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@macrulez/masonry-kit-nuxt",
+  "version": "0.1.0",
+  "description": "Nuxt module wrapping @macrulez/masonry-kit-vue: auto-imported <MasonryGrid> and useMasonry, module options for default layout behavior",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/module.js",
+  "module": "./dist/module.js",
+  "types": "./dist/module.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "nuxt": "^3.9.0 || ^4.0.0"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.5.2",
+    "@macrulez/masonry-kit-vue": "0.1.0"
+  },
+  "devDependencies": {
+    "@nuxt/schema": "^4.5.2",
+    "nuxt": "^4.5.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}