nuxt-state 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Navid Talebian
+
+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,151 @@
+# nuxt-state
+
+> Define shared Nuxt state using the same Composition API you already use in composables.
+
+`nuxt-state` is an experimental Nuxt 4 module that explores one small primitive:
+
+```ts
+defineState(() => {
+  // standard Vue Composition API
+  return {
+    /* public state */
+  };
+});
+```
+
+A regular composable runs its factory for every invocation. A composable created by
+`defineState` runs its factory lazily, once for the current Nuxt application instance,
+and returns that exact result to every caller in that app.
+
+This is a working prototype for discussion and possible future contribution to Nuxt.
+It is not yet presented as production-ready.
+
+## Why
+
+Nuxt's `useState()` is excellent for simple SSR-aware values. Pinia is a strong choice
+when an application wants a dedicated state-management library and its ecosystem.
+This project does not replace either one. It explores a lightweight native abstraction
+between a raw `useState()` value and a full state-management library.
+
+There are no stores, actions, getters, mutations, IDs, configuration objects, or special
+wrappers. The factory and its return value use normal Vue semantics.
+
+## Install
+
+```bash
+pnpm add nuxt-state
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["nuxt-state"],
+});
+```
+
+The package has not been published yet; during development, use this repository as a
+workspace dependency.
+
+## Usage
+
+Create a state in Nuxt 4's application source directory:
+
+```ts
+// app/states/counter.ts
+export const useCounter = defineState(() => {
+  const count = ref(0);
+  const double = computed(() => count.value * 2);
+
+  function increment() {
+    count.value++;
+  }
+
+  return {
+    count,
+    double,
+    increment,
+  };
+});
+```
+
+Exports from `app/states/`, including nested directories and multiple exports per file,
+are auto-imported. `defineState` is also auto-imported and can be used elsewhere, such
+as in `app/composables/`.
+
+```vue
+<script setup lang="ts">
+const { count, double, increment } = useCounter();
+
+count.value++;
+increment();
+console.log(double.value);
+</script>
+```
+
+Calling `useCounter()` in ten components returns the same object for that Nuxt app.
+Different server requests and different client apps receive different objects.
+
+The returned object is not cloned, wrapped, or transformed. Refs remain refs, computed
+refs remain computed refs, reactive objects remain reactive, and functions are unchanged.
+
+## Semantics
+
+- The factory is synchronous and takes no arguments.
+- The generated composable takes no arguments.
+- The factory is lazy and runs at first use.
+- It runs once per Nuxt app instance.
+- The exact factory result is returned to all callers in that app.
+- A module-local `WeakMap` keys instances by `NuxtApp`, providing request isolation while
+  allowing old application instances to be garbage-collected.
+- Separate `defineState()` calls have separate closure-owned caches, including calls in
+  the same file.
+
+Async factories are rejected by TypeScript and guarded at runtime for JavaScript users.
+Expose an async function from synchronous state or use Nuxt's data-fetching APIs instead.
+
+## SSR scope
+
+v0 guarantees isolation between SSR requests: module-level state does not become a
+process-wide user-state singleton. This is intentionally different from hydration.
+
+v0 does **not** serialize or hydrate arbitrary factory results. A result may contain
+functions, computed refs, class instances, and other runtime-only values. If a state is
+mutated during SSR, the client may recreate the factory's initial state during hydration.
+Do not rely on server mutations transferring to the client yet.
+
+## Current limitations
+
+- Nuxt 4 and Vue 3 only.
+- Synchronous factories only.
+- No persistence or browser-storage integration.
+- No arbitrary-state payload serialization or hydration yet.
+- No Nuxt Layers support yet.
+- State resets when its module is hot-reloaded; HMR preservation is not implemented.
+- Compatibility with every context-sensitive Nuxt composable inside a factory is not
+  guaranteed yet.
+- There is no reset API, keyed/multi-instance state, DevTools integration, or central
+  registry.
+
+See [ROADMAP.md](./ROADMAP.md) for the technical questions behind future hydration and
+context compatibility.
+
+## Development
+
+Requires Node.js 22+ and pnpm.
+
+```bash
+pnpm install
+pnpm dev
+pnpm lint
+pnpm test:types
+pnpm test
+pnpm prepack
+pnpm dev:build
+```
+
+The playground contains two counter components, a reactive object example, a nested
+state, and two independent states exported from one file.
+
+## License
+
+[MIT](./LICENSE)

package/dist/module.d.mts

@@ -0,0 +1,7 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+type ModuleOptions = Record<string, never>;
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-state",
+  "compatibility": {
+    "nuxt": "^4.0.0"
+  },
+  "configKey": "nuxt-state",
+  "version": "0.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,22 @@
+import { resolve } from 'node:path';
+import { defineNuxtModule, createResolver, addImports, addImportsDir } from '@nuxt/kit';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-state",
+    compatibility: {
+      nuxt: "^4.0.0"
+    }
+  },
+  defaults: {},
+  setup(_options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    addImports({
+      name: "defineState",
+      from: resolver.resolve("./runtime/app/composables/defineState")
+    });
+    addImportsDir(resolve(nuxt.options.srcDir, "states/**"));
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/composables/defineState.d.ts

@@ -0,0 +1,6 @@
+type NotPromise<T> = T extends PromiseLike<unknown> ? never : unknown;
+/**
+ * Turns a synchronous composable factory into state shared by one Nuxt app.
+ */
+export declare function defineState<T>(factory: () => T & NotPromise<T>): () => T;
+export {};

package/dist/runtime/app/composables/defineState.js

@@ -0,0 +1,21 @@
+import { useNuxtApp } from "#app";
+function isPromiseLike(value) {
+  return (typeof value === "object" && value !== null || typeof value === "function") && "then" in value && typeof value.then === "function";
+}
+export function defineState(factory) {
+  const instances = /* @__PURE__ */ new WeakMap();
+  return function useDefinedState() {
+    const nuxtApp = useNuxtApp();
+    if (instances.has(nuxtApp)) {
+      return instances.get(nuxtApp);
+    }
+    const instance = factory();
+    if (isPromiseLike(instance)) {
+      throw new TypeError(
+        "[nuxt-state] State factories must be synchronous. Expose an async function from the state or use Nuxt data-fetching composables instead."
+      );
+    }
+    instances.set(nuxtApp, instance);
+    return instance;
+  };
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "nuxt-state",
+  "version": "0.0.1",
+  "description": "Define shared Nuxt state using the same Composition API you already use in composables.",
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "vue",
+    "state",
+    "composable"
+  ],
+  "license": "MIT",
+  "author": "Navid Talebian",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/navidtm/nuxt-state.git"
+  },
+  "homepage": "https://github.com/navidtm/nuxt-state#readme",
+  "bugs": {
+    "url": "https://github.com/navidtm/nuxt-state/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.5.2"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.5.2",
+    "@nuxt/test-utils": "^4.1.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.9.0",
+    "happy-dom": "^20.8.3",
+    "nuxt": "^4.5.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11",
+    "vue": "^3.5.31",
+    "vue-tsc": "^3.3.11"
+  },
+  "scripts": {
+    "dev": "pnpm dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:types": "vue-tsc --noEmit && pnpm --dir playground exec vue-tsc --noEmit"
+  }
+}